time-manager 0.2.20__py3-none-any.whl

app.py

@@ -0,0 +1,237 @@
+"""time-manager entry point.
+
+Commands:
+- `time-manager sw`                 Start a stopwatch
+- `tm sw`                           Start a stopwatch
+- `tm stopwatch`                    Start a stopwatch
+- `time-manager cd <amount> [unit]` Start a countdown timer
+- `tm cd <amount> [unit]`           Start a countdown timer
+- `tm countdown <amount> [unit]`    Start a countdown timer
+"""
+
+from __future__ import annotations
+
+import os
+
+# Terminal emulators differ in how they advertise TrueColor support.
+# These defaults help keep Textual/Rich rendering consistent across Windows Terminal,
+# VS Code/Cursor terminals, etc. Users can still override by setting these env vars.
+os.environ.setdefault("COLORTERM", "truecolor")
+os.environ.setdefault("RICH_COLOR_SYSTEM", "truecolor")
+
+from importlib import metadata as _metadata
+
+import typer
+
+from cli import run_countdown_cli, run_stopwatch_cli
+from tui import CountdownTui, StopwatchTui
+
+_ALIASES: dict[str, str] = {
+    "stopwatch": "sw",
+    "countdown": "cd",
+}
+
+
+class _TmGroup(typer.core.TyperGroup):
+    """Typer group with command aliases (so help doesn't list duplicates)."""
+
+    def get_command(self, ctx: typer.Context, cmd_name: str):
+        command = super().get_command(ctx, cmd_name)
+        if command is not None:
+            return command
+
+        alias = _ALIASES.get(cmd_name)
+        if alias is None:
+            return None
+
+        return super().get_command(ctx, alias)
+
+
+# Create the Typer app
+app = typer.Typer(
+    help=(
+        "A terminal based stopwatch and countdown timer.\n\n"
+        "Examples:\n"
+        "  tm sw\n"
+        "  tm sw -i\n"
+        "  tm cd 5 m\n"
+        "  tm cd 5 m -i\n"
+        "  tm countdown 10 s\n"
+    ),
+    cls=_TmGroup,
+    add_completion=False,
+)
+
+INTERACTIVE = typer.Option(
+    False,
+    "--interactive",
+    "-i",
+    help="Run in interactive (Textual TUI) mode.",
+)
+
+
+def _get_version() -> str:
+    for dist_name in ("time-manager", "tm"):
+        try:
+            return _metadata.version(dist_name)
+        except _metadata.PackageNotFoundError:
+            continue
+    return "unknown"
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    typer.echo(_get_version())
+    raise typer.Exit()
+
+
+_UNIT_SECONDS: dict[str, int] = {
+    # seconds
+    "s": 1,
+    "sec": 1,
+    "secs": 1,
+    "second": 1,
+    "seconds": 1,
+    # minutes
+    "m": 60,
+    "min": 60,
+    "mins": 60,
+    "minute": 60,
+    "minutes": 60,
+    # hours
+    "h": 3600,
+    "hr": 3600,
+    "hrs": 3600,
+    "hour": 3600,
+    "hours": 3600,
+}
+
+
+def _die(message: str) -> None:
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+def _parse_countdown_seconds(amount: int, unit: str) -> int:
+    if amount <= 0:
+        _die("Time must be greater than 0.")
+
+    normalized_unit = unit.lower().strip()
+    multiplier = _UNIT_SECONDS.get(normalized_unit)
+    if multiplier is None:
+        _die(f"Unknown unit '{normalized_unit}'. Please use 's', 'm', or 'h'.")
+
+    seconds = amount * multiplier
+    if seconds <= 0:
+        _die("Time must be greater than 0.")
+
+    return seconds
+
+
+def _print_error_box(message: str) -> None:
+    """Print an error message in a boxed panel when Rich is available."""
+    try:
+        from rich import box
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.text import Text
+    except Exception:
+        typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+        return
+
+    Console(stderr=True).print(
+        Panel(
+            Text(message, style="bold red"),
+            title="Error",
+            border_style="red",
+            box=box.ROUNDED,
+            expand=True,
+        )
+    )
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    interactive: bool = INTERACTIVE,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """
+    A terminal based stopwatch and countdown timer.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["interactive"] = interactive
+
+    if ctx.invoked_subcommand is not None:
+        return
+
+    # Treat calling `tm` with no command as an error, but show help by default.
+    _print_error_box("Missing command.")
+    # Use Typer/Click's built-in help so it's complete and stays standard
+    # (includes e.g. completion flags and any future global options).
+    typer.echo(ctx.get_help())
+    raise typer.Exit(code=1)
+
+
+@app.command(help="Start a stopwatch. (alias: stopwatch)")
+def sw(ctx: typer.Context, interactive: bool = INTERACTIVE) -> None:
+    """
+    Start a stopwatch.
+
+    Examples:
+    tm sw
+    tm sw -i
+    tm stopwatch
+    """
+    effective_interactive = bool(
+        interactive or (ctx.obj or {}).get("interactive", False)
+    )
+    if effective_interactive:
+        StopwatchTui().run()
+    else:
+        run_stopwatch_cli()
+
+
+@app.command(help="Start a countdown timer. (alias: countdown)")
+def cd(
+    ctx: typer.Context,
+    amount: int = typer.Argument(..., help="The amount of time."),
+    unit: str = typer.Argument(
+        "m", help="The unit of time. [s]econds, [m]inutes, [h]ours."
+    ),
+    interactive: bool = INTERACTIVE,
+):
+    """
+    Start a countdown timer.
+
+    Examples:
+    tm cd 5 m
+    tm cd 5 m -i
+    tm countdown 10 s
+    """
+
+    seconds = _parse_countdown_seconds(amount, unit)
+
+    effective_interactive = bool(
+        interactive or (ctx.obj or {}).get("interactive", False)
+    )
+    if effective_interactive:
+        CountdownTui(seconds).run()
+    else:
+        run_countdown_cli(seconds)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

cli/__init__.py

@@ -0,0 +1,5 @@
+# time-manager CLI Components
+
+from .cli import run_stopwatch_cli, run_countdown_cli
+
+__all__ = ["run_stopwatch_cli", "run_countdown_cli"]

cli/cli.py

@@ -0,0 +1,140 @@
+import time
+import sys
+import select
+import termios
+import tty
+from rich.align import Align
+from rich.console import Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+from core.formatting import format_time
+from core.termclock import Stopwatch, Countdown
+
+
+class NonBlockingInput:
+    """Context manager for non-blocking terminal input."""
+
+    def __enter__(self):
+        self.old_settings = termios.tcgetattr(sys.stdin)
+        tty.setcbreak(sys.stdin.fileno())
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self.old_settings)
+
+    @staticmethod
+    def get_char():
+        """Check for and return a character if available, else None."""
+        if select.select([sys.stdin], [], [], 0) == ([sys.stdin], [], []):
+            return sys.stdin.read(1)
+        return None
+
+
+def run_stopwatch_cli():
+    stopwatch = Stopwatch()
+    stopwatch.start()
+
+    subtitle = "Space: Start/Stop | r: Reset | q: Quit"
+
+    try:
+        with NonBlockingInput(), Live(refresh_per_second=60, screen=False) as live:
+            while True:
+                # Handle Input
+                char = NonBlockingInput.get_char()
+                if char:
+                    if char.lower() == "q":
+                        break
+                    elif char == " ":
+                        stopwatch.toggle()
+                    elif char.lower() == "r":
+                        stopwatch.reset()
+
+                # Update Display
+                elapsed = stopwatch.elapsed
+                time_str = format_time(elapsed, show_centiseconds=False)
+                # Always display HH:MM:SS (even when hours == 0)
+                if time_str.count(":") == 1:
+                    time_str = f"00:{time_str}"
+
+                # Visual feedback for paused state
+                style = "bold green" if stopwatch.is_running else "dim green"
+                border_style = "green" if stopwatch.is_running else "white"
+
+                display = Group(
+                    Align.center(Text(time_str, style=style)),
+                    Align.center(Text("HH:MM:SS", style="dim")),
+                )
+
+                panel = Panel(
+                    display,
+                    title="Stopwatch",
+                    subtitle=subtitle,
+                    box=box.ROUNDED,
+                    border_style=border_style,
+                    padding=(1, 2),
+                )
+                live.update(panel)
+                time.sleep(1 / 60)
+    except KeyboardInterrupt:
+        pass
+
+
+def run_countdown_cli(seconds: int):
+    countdown = Countdown(seconds)
+
+    subtitle = "Space: Pause/Resume | q: Quit"
+
+    try:
+        with NonBlockingInput(), Live(refresh_per_second=10, screen=False) as live:
+            while not countdown.is_finished:
+                # Handle Input
+                char = NonBlockingInput.get_char()
+                if char:
+                    if char.lower() == "q":
+                        break
+                    elif char == " ":
+                        countdown.toggle()
+
+                countdown.tick()
+                remaining = countdown.time_left
+                time_str = format_time(remaining, show_centiseconds=False)
+
+                # Change color based on urgency
+                color = "blue"
+                if remaining < 10:
+                    color = "red"
+                elif remaining < 30:
+                    color = "yellow"
+
+                # Visual feedback for paused state
+                style = f"bold {color}" if countdown.is_running else f"dim {color}"
+                border_style = color if countdown.is_running else "white"
+
+                panel = Panel(
+                    Text(time_str, style=style, justify="center"),
+                    title="Countdown",
+                    subtitle=subtitle,
+                    box=box.ROUNDED,
+                    border_style=border_style,
+                    padding=(1, 2),
+                )
+                live.update(panel)
+                time.sleep(0.1)
+
+            # Final "Time's Up" display
+            if countdown.is_finished:
+                panel = Panel(
+                    Text("00:00", style="bold red blink", justify="center"),
+                    title="Countdown",
+                    subtitle="Time's Up!",
+                    box=box.ROUNDED,
+                    border_style="red",
+                    padding=(1, 2),
+                )
+                live.update(panel)
+                time.sleep(2)  # Show for a bit before exiting
+
+    except KeyboardInterrupt:
+        pass

core/formatting.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+
+def format_time(seconds: float, *, show_centiseconds: bool = True) -> str:
+    """Format a duration in seconds as MM:SS(.CC) or HH:MM:SS(.CC)."""
+
+    seconds = max(0.0, float(seconds))
+    minutes, secs = divmod(seconds, 60)
+    hours, minutes = divmod(minutes, 60)
+
+    if show_centiseconds:
+        centiseconds = int((seconds * 100) % 100)
+        if hours > 0:
+            return f"{int(hours):02}:{int(minutes):02}:{int(secs):02}.{centiseconds:02}"
+        return f"{int(minutes):02}:{int(secs):02}.{centiseconds:02}"
+
+    if hours > 0:
+        return f"{int(hours):02}:{int(minutes):02}:{int(secs):02}"
+    return f"{int(minutes):02}:{int(secs):02}"

core/termclock.py

@@ -0,0 +1,97 @@
+from time import monotonic
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Stopwatch:
+    """Core logic for a stopwatch."""
+
+    _start_time: Optional[float] = None
+    _accumulated_time: float = 0.0
+    _running: bool = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def elapsed(self) -> float:
+        """Return the total elapsed time in seconds."""
+        if self._running:
+            return self._accumulated_time + (monotonic() - self._start_time)
+        return self._accumulated_time
+
+    def start(self):
+        if not self._running:
+            self._start_time = monotonic()
+            self._running = True
+
+    def stop(self):
+        if self._running:
+            self._accumulated_time += monotonic() - self._start_time
+            self._start_time = None
+            self._running = False
+
+    def reset(self):
+        self._running = False
+        self._accumulated_time = 0.0
+        self._start_time = None
+
+    def toggle(self):
+        if self._running:
+            self.stop()
+        else:
+            self.start()
+
+
+@dataclass
+class Countdown:
+    """Core logic for a countdown timer."""
+
+    initial_seconds: int
+    _time_left: float = field(init=False)
+    _last_tick: Optional[float] = field(init=False, default=None)
+    _running: bool = field(init=False, default=True)
+
+    def __post_init__(self):
+        self._time_left = float(self.initial_seconds)
+        self._last_tick = monotonic()
+
+    @property
+    def time_left(self) -> float:
+        return max(0.0, self._time_left)
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def is_finished(self) -> bool:
+        return self._time_left <= 0
+
+    def tick(self):
+        """Update the timer based on elapsed real time."""
+        if self._running and self._time_left > 0:
+            now = monotonic()
+            if self._last_tick:
+                delta = now - self._last_tick
+                self._time_left -= delta
+            self._last_tick = now
+        else:
+            self._last_tick = monotonic()
+
+    def pause(self):
+        self._running = False
+        self._last_tick = None
+
+    def resume(self):
+        if not self._running:
+            self._running = True
+            self._last_tick = monotonic()
+
+    def toggle(self):
+        if self._running:
+            self.pause()
+        else:
+            self.resume()

time_manager-0.2.20.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: time-manager
+Version: 0.2.20
+Summary: A terminal based stopwatch and countdown timer
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: textual-dev>=1.8.0
+Requires-Dist: textual>=6.11.0
+Requires-Dist: typer>=0.21.0
+Description-Content-Type: text/markdown
+
+# time-manager
+
+A powerful and visually stunning terminal-based timer application built with [Textual](https://textual.textualize.io/) and [Typer](https://typer.tiangolo.com/).
+
+- **CLI Interface (default)**: Lightweight mode (no Textual UI).
+- **TUI Interface**: Beautiful, responsive terminal user interface via `-i/--interactive`.
+- **Notifications**: Visual and audio feedback (bell) when a countdown completes.
+
+![Stopwatch TUI Screenshot](./docs/stopwatch-tui.png)
+
+## Features
+
+- **Stopwatch**: Precise stopwatch with centisecond resolution.
+- **Countdown**: Configurable countdown timer with support for seconds, minutes, and hours.
+
+## Installation
+
+- Requires **Python 3.10+**
+- Installs two commands: `tm` (recommended) and `time-manager`
+
+From PyPI:
+
+```bash
+pip install time-manager
+```
+
+If you use uv:
+
+```bash
+uv tool install time-manager
+
+# or (inside a project)
+uv add time-manager
+```
+
+## Usage
+
+time-manager provides two command names for convenience:
+
+- `tm` - Short and convenient alias
+- `time-manager` - Full command name
+
+Both commands work identically. Examples:
+
+```bash
+tm sw              # or: time-manager sw   (also: tm stopwatch)
+tm cd 5 m          # or: time-manager cd 5 m (also: tm countdown 5 m)
+```
+
+### Stopwatch
+
+Start a stopwatch to track elapsed time:
+
+```bash
+tm sw
+```
+
+For interactive TUI mode:
+
+```bash
+tm sw -i
+```
+
+**Controls (TUI mode):**
+- `Space`: Start/Stop
+- `r`: Reset
+- `q`: Quit
+
+### Countdown Timer
+
+Start a countdown for a specific duration:
+
+```bash
+tm cd 5 m    # 5 minutes
+tm cd 60 s   # 60 seconds
+tm cd 1 h    # 1 hour
+```
+
+For interactive TUI mode:
+
+```bash
+tm cd 5 m -i
+```
+
+**Controls (TUI mode):**
+- `Space`: Pause/Resume
+- `q`: Quit
+
+## Development
+
+### Prerequisites
+
+- [uv](https://github.com/astral-sh/uv) installed on your system.
+- Python 3.10+
+
+### Installation for Development
+
+To install in editable mode for development:
+
+```bash
+make local
+```
+
+### Global Installation (Recommended for Testing)
+
+To install as a system-wide utility:
+
+```bash
+make global
+```
+
+This builds a standalone executable and copies it to `/usr/local/bin/time-manager`, and also creates a `/usr/local/bin/tm` symlink.
+
+### Make Commands
+
+| Command                | Description                                       |
+| ---------------------- | ------------------------------------------------- |
+| `make local`           | Install in editable mode for development          |
+| `make global`          | Build and install system-wide to `/usr/local/bin` |
+| `make build`           | Build standalone executable (with version bump)   |
+| `make bump`            | Bump patch version (default)                      |
+| `TYPE=MINOR make bump` | Bump minor version                                |
+| `TYPE=MAJOR make bump` | Bump major version                                |
+| `make clean`           | Remove build artifacts                            |
+| `make uninstall`       | Remove global installation                        |
+
+### Project Structure
+
+```
+time-manager/
+├── src/
+│   ├── app.py              # CLI entry point using Typer
+│   ├── cli/
+│   │   ├── __init__.py     # CLI package exports
+│   │   └── cli.py          # CLI implementations for timers
+│   ├── core/
+│   │   ├── formatting.py   # Time formatting utilities
+│   │   └── termclock.py    # Core timer logic
+│   └── tui/
+│       ├── __init__.py     # TUI package exports
+│       ├── countdown.py    # Countdown TUI
+│       ├── stopwatch.py    # Stopwatch TUI
+│       └── theme.tcss      # Textual CSS theme
+├── scripts/
+│   └── bump.sh             # Version bump script
+├── pyproject.toml          # Project configuration
+├── uv.lock                 # Dependency lock file
+├── Makefile                # Build and install commands
+├── LICENSE                 # Project license
+└── README.md               # This file
+```
+
+### Publishing to PyPI
+
+This repo uses `make publish` (via `scripts/publish.sh`) and defaults to **TestPyPI**.
+
+#### Test PyPI (default)
+
+To publish to Test PyPI (uses `TEST_PYPI_PUBLISH_TOKEN`):
+
+```bash
+make build
+make publish
+```
+
+#### Production PyPI
+
+To publish to production PyPI (uses `PYPI_PUBLISH_TOKEN`):
+
+```bash
+make build
+PROD=TRUE make publish
+```
+
+### Uninstallation
+
+To remove the global installation:
+
+```bash
+make uninstall
+```

time_manager-0.2.20.dist-info/RECORD

@@ -0,0 +1,14 @@
+app.py,sha256=gCGHj1heTrg_pFafK-0ZJGAWaYSlVjnbcuvzuRul1Zo,5787
+cli/__init__.py,sha256=438YugZ3QU07-5Spswk0OLcHC_B3JDjB8ZHRT9hn4SM,139
+cli/cli.py,sha256=yZi5u8phWkSucZ9zPi1bF8jdtJmzNW4iUzV7SEna6pU,4639
+core/formatting.py,sha256=3SVZ3xUaEN3mtEecFgMqxesSh5-XDUbAiwBzZ61846k,694
+core/termclock.py,sha256=RptBEob2O__-tRu9siD8HUxw5UT2uPLN1B1HodyxkLI,2467
+tui/__init__.py,sha256=TwfmFKYVnc3n4uIrm19PYSAcgdsaH2W4YxVlVbEDYCc,139
+tui/countdown.py,sha256=krCZgbz4ILVcOsv-8Lo1iwPnnUhHVI37_x273CHcxqQ,3265
+tui/stopwatch.py,sha256=11lFQ3q96oyL-Krt6_ePRc8eVvVf6Am1MOhJLMSmaV8,3841
+tui/theme.tcss,sha256=-DtnprXFmvzuOVIVjLSkIhGT8Q4KD3eA50ry7Twzpt4,4510
+time_manager-0.2.20.dist-info/METADATA,sha256=msDYBTDI5V4QfYeHTow_1HcWauzI80Dm-W2xIxDd0mI,4734
+time_manager-0.2.20.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+time_manager-0.2.20.dist-info/entry_points.txt,sha256=m_D7FaJTbf0SyyQMkyqsTWjgNEo20-MbzF-1DyZEUv0,56
+time_manager-0.2.20.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+time_manager-0.2.20.dist-info/RECORD,,