tclock 0.1.2__py3-none-any.whl

tclock/__init__.py

@@ -0,0 +1,10 @@
+"""tclock: a clock, timer, stopwatch and countdown for the terminal."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("tclock")
+except PackageNotFoundError:  # running from a checkout that is not installed
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

tclock/app.tcss

@@ -0,0 +1,55 @@
+Screen {
+    align: center middle;
+    overflow: hidden hidden;
+    layers: base keybar;
+}
+
+Screen.-flash {
+    background: ansi_green;
+}
+
+Screen.-flash Label {
+    color: ansi_black;
+}
+
+#body {
+    height: auto;
+    overflow: hidden hidden;
+}
+
+#header, #footer {
+    width: 100%;
+    text-align: center;
+}
+
+#header {
+    margin-bottom: 1;
+}
+
+#footer {
+    margin-top: 1;
+}
+
+/* The key bar sits on its own layer so showing it never moves the digits. */
+#keybar {
+    layer: keybar;
+    dock: bottom;
+}
+
+HelpScreen {
+    align: center middle;
+    background: $background 60%;
+}
+
+HelpScreen > #help {
+    width: auto;
+    height: auto;
+    padding: 1 2;
+    border: round $primary;
+    border-title-align: center;
+}
+
+HelpScreen #help-keys {
+    width: auto;
+    height: auto;
+}

tclock/cli.py

@@ -0,0 +1,215 @@
+"""Command-line interface. Parses arguments into :class:`Options` and starts the TUI."""
+
+from typing import Annotated
+
+import typer
+
+from tclock import __version__, ui
+from tclock.config import load_config
+from tclock.modes import Stopwatch
+from tclock.parsing import ParseError, parse_color, parse_datetime, parse_duration, parse_timezone
+from tclock.resolve import Options, ResolveError, resolve
+
+app = typer.Typer(
+    name="tclock",
+    help="A clock, timer, stopwatch and countdown in your terminal. Press q to quit.",
+    invoke_without_command=True,
+    add_completion=False,
+    no_args_is_help=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _validate_color(value: str | None) -> str | None:
+    if value is not None:
+        try:
+            parse_color(value)
+        except ParseError as exc:
+            raise typer.BadParameter(str(exc)) from None
+    return value
+
+
+def _validate_durations(values: list[str] | None) -> list[str] | None:
+    for value in values or []:
+        try:
+            parse_duration(value)
+        except ParseError as exc:
+            raise typer.BadParameter(str(exc)) from None
+    return values
+
+
+def _validate_timezone(value: str | None) -> str | None:
+    if value is not None:
+        try:
+            parse_timezone(value)
+        except ParseError as exc:
+            raise typer.BadParameter(str(exc)) from None
+    return value
+
+
+def _validate_datetime(value: str | None) -> str | None:
+    if value is not None:
+        try:
+            parse_datetime(value)
+        except ParseError as exc:
+            raise typer.BadParameter(str(exc)) from None
+    return value
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"tclock {__version__}")
+        raise typer.Exit()
+
+
+def _options(ctx: typer.Context) -> Options:
+    options = ctx.find_root().obj
+    assert isinstance(options, Options)
+    return options
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    color: Annotated[
+        str | None,
+        typer.Option(
+            "--color",
+            "-c",
+            callback=_validate_color,
+            help="Digit color: black, red, green, yellow, blue, magenta, cyan, gray, darkgray, "
+            "lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan, white, "
+            "or #rrggbb.",
+        ),
+    ] = None,
+    size: Annotated[
+        int | None, typer.Option("--size", "-s", min=1, help="Digit size, a positive integer.")
+    ] = None,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show version.")
+    ] = False,
+) -> None:
+    ctx.obj = Options(color=color, size=size)
+    if ctx.invoked_subcommand is None:
+        _launch(ctx.obj)
+
+
+@app.command()
+def clock(
+    ctx: typer.Context,
+    timezone: Annotated[
+        str | None,
+        typer.Option(
+            "--timezone", "-z", callback=_validate_timezone, help='IANA zone, e.g. "Europe/Oslo".'
+        ),
+    ] = None,
+    no_date: Annotated[bool, typer.Option("--no-date", "-D", help="Hide the date.")] = False,
+    no_seconds: Annotated[bool, typer.Option("--no-seconds", "-S", help="Hide seconds.")] = False,
+    millis: Annotated[
+        bool, typer.Option("--millis", "-m", help="Show tenths of a second.")
+    ] = False,
+) -> None:
+    """Show the current time (the default mode)."""
+    options = _options(ctx)
+    options.mode = "clock"
+    options.timezone = timezone
+    options.no_date = no_date
+    options.no_seconds = no_seconds
+    options.millis = millis
+    _launch(options)
+
+
+@app.command()
+def timer(
+    ctx: typer.Context,
+    durations: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--duration",
+            "-d",
+            callback=_validate_durations,
+            help="Duration like 30s, 5m, 1h, 2d. Repeat the flag to run several in sequence.",
+        ),
+    ] = None,
+    titles: Annotated[
+        list[str] | None,
+        typer.Option("--title", "-t", help="Title per duration. Repeat the flag for several."),
+    ] = None,
+    repeat: Annotated[bool, typer.Option("--repeat", "-r", help="Restart when finished.")] = False,
+    no_millis: Annotated[bool, typer.Option("--no-millis", "-M", help="Hide tenths.")] = False,
+    paused: Annotated[bool, typer.Option("--paused", "-P", help="Start paused.")] = False,
+    auto_quit: Annotated[bool, typer.Option("--quit", "-Q", help="Exit when time is up.")] = False,
+    execute: Annotated[
+        str | None,
+        typer.Option("--execute", "-e", help="Shell command to run when time is up."),
+    ] = None,
+) -> None:
+    """Count down one or more durations. Space pauses and resumes."""
+    options = _options(ctx)
+    options.mode = "timer"
+    options.durations = durations or []
+    options.titles = titles or []
+    options.repeat = repeat
+    options.no_millis = no_millis
+    options.paused = paused
+    options.auto_quit = auto_quit
+    options.execute = execute
+    _launch(options)
+
+
+@app.command()
+def stopwatch(ctx: typer.Context) -> None:
+    """Count up from zero. Space pauses and resumes; the time is printed on exit."""
+    options = _options(ctx)
+    options.mode = "stopwatch"
+    _launch(options)
+
+
+@app.command()
+def countdown(
+    ctx: typer.Context,
+    time: Annotated[
+        str | None,
+        typer.Option(
+            "--time",
+            "-t",
+            callback=_validate_datetime,
+            help='Target: "2027-01-01", "20:00", "2026-12-25 20:00:00" or RFC 3339.',
+        ),
+    ] = None,
+    title: Annotated[str | None, typer.Option("--title", "-T", help="Header text.")] = None,
+    continue_on_zero: Annotated[
+        bool, typer.Option("--continue", "-c", help="Keep counting past the target.")
+    ] = False,
+    reverse: Annotated[
+        bool, typer.Option("--reverse", "-r", help="Count up since the target instead.")
+    ] = False,
+    millis: Annotated[
+        bool, typer.Option("--millis", "-m", help="Show tenths of a second.")
+    ] = False,
+) -> None:
+    """Show the time until (or since) a specific moment."""
+    options = _options(ctx)
+    options.mode = "countdown"
+    options.time = time
+    options.title = title
+    options.continue_on_zero = continue_on_zero
+    options.reverse = reverse
+    options.millis = millis
+    _launch(options)
+
+
+def _launch(options: Options) -> None:
+    config = load_config()
+    try:
+        resolved = resolve(options, config)
+    except ResolveError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from None
+    final = ui.run(resolved.engine, color=resolved.color, size=resolved.size, config=config)
+    if isinstance(final, Stopwatch):
+        typer.echo(f"Stopwatch time: {final.display_time()}")
+
+
+def main() -> None:
+    app()

tclock/config.py

@@ -0,0 +1,119 @@
+"""The optional TOML config file.
+
+Location: ``platformdirs.user_config_path("tclock") / "config.toml"``, i.e.
+``~/.config/tclock/config.toml`` on Linux, ``~/Library/Application Support/tclock/config.toml``
+on macOS and ``%APPDATA%\\tclock\\config.toml`` on Windows. The schema is the one used by
+the Rust clock-tui. Anything wrong in the file produces a warning and a default, never an
+error.
+"""
+
+import sys
+import tomllib
+import types
+from collections.abc import Callable
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any, cast, get_args, get_origin
+
+import platformdirs
+
+APP_NAME = "tclock"
+
+
+@dataclass(slots=True)
+class DefaultConfig:
+    mode: str = "clock"
+    color: str = "green"
+    size: int = 1
+
+
+@dataclass(slots=True)
+class ClockConfig:
+    show_date: bool = True
+    show_seconds: bool = True
+    show_millis: bool = False
+    timezone: str | None = None
+
+
+@dataclass(slots=True)
+class TimerConfig:
+    durations: list[str] = field(default_factory=lambda: ["25m", "5m"])
+    titles: list[str] = field(default_factory=list)
+    repeat: bool = False
+    show_millis: bool = True
+    start_paused: bool = False
+    auto_quit: bool = False
+    execute: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class CountdownConfig:
+    time: str | None = None
+    title: str | None = None
+    show_millis: bool = False
+    continue_on_zero: bool = False
+    reverse: bool = False
+
+
+@dataclass(slots=True)
+class Config:
+    default: DefaultConfig = field(default_factory=DefaultConfig)
+    clock: ClockConfig = field(default_factory=ClockConfig)
+    timer: TimerConfig = field(default_factory=TimerConfig)
+    countdown: CountdownConfig = field(default_factory=CountdownConfig)
+
+
+def warn_stderr(message: str) -> None:
+    print(message, file=sys.stderr)
+
+
+def config_path() -> Path:
+    return platformdirs.user_config_path(APP_NAME) / "config.toml"
+
+
+def load_config(path: Path | None = None, *, warn: Callable[[str], None] = warn_stderr) -> Config:
+    """Read the config file, falling back to defaults for anything missing or wrong."""
+    path = path if path is not None else config_path()
+    if not path.is_file():
+        return Config()
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        warn(f"tclock: ignoring {path}: {exc}")
+        return Config()
+    return Config(
+        default=_section(DefaultConfig, data, "default", warn),
+        clock=_section(ClockConfig, data, "clock", warn),
+        timer=_section(TimerConfig, data, "timer", warn),
+        countdown=_section(CountdownConfig, data, "countdown", warn),
+    )
+
+
+def _section[T](cls: type[T], data: dict[str, Any], name: str, warn: Callable[[str], None]) -> T:
+    raw = data.get(name, {})
+    result = cls()
+    if not isinstance(raw, dict):
+        warn(f"tclock: config section [{name}] must be a table; using defaults")
+        return result
+    for f in fields(cast(Any, cls)):
+        if f.name not in raw:
+            continue
+        value = raw[f.name]
+        if _matches(value, f.type):
+            setattr(result, f.name, value)
+        else:
+            warn(f"tclock: config {name}.{f.name} has the wrong type; using the default")
+    return result
+
+
+def _matches(value: object, expected: Any) -> bool:
+    if isinstance(expected, types.UnionType):
+        return any(_matches(value, arg) for arg in get_args(expected))
+    if expected is type(None):
+        return value is None
+    if get_origin(expected) is list:
+        (item_type,) = get_args(expected)
+        return isinstance(value, list) and all(_matches(item, item_type) for item in value)
+    if expected is int:
+        return isinstance(value, int) and not isinstance(value, bool)
+    return isinstance(value, expected)

tclock/font.py

@@ -0,0 +1,76 @@
+"""The "bricks" block font used for the big digits.
+
+Each glyph is 6 columns by 5 rows at size 1. A row is described as run lengths that
+alternate off/on starting with "off": ``(0, 6)`` is ``██████``, ``(2, 2)`` is ``  ██``,
+``(0, 2, 2, 2)`` is ``██  ██``. Glyph table copied from clock-tui's BricksFont.
+"""
+
+GLYPH_WIDTH = 6
+GLYPH_HEIGHT = 5
+SPACING = 2
+BLOCK = "█"
+
+Runs = tuple[int, ...]
+
+GLYPHS: dict[str, tuple[Runs, Runs, Runs, Runs, Runs]] = {
+    "0": ((0, 6), (0, 2, 2, 2), (0, 2, 2, 2), (0, 2, 2, 2), (0, 6)),
+    "1": ((0, 4), (2, 2), (2, 2), (2, 2), (0, 6)),
+    "2": ((0, 6), (4, 2), (0, 6), (0, 2), (0, 6)),
+    "3": ((0, 6), (4, 2), (0, 6), (4, 2), (0, 6)),
+    "4": ((0, 2, 2, 2), (0, 2, 2, 2), (0, 6), (4, 2), (4, 2)),
+    "5": ((0, 6), (0, 2), (0, 6), (4, 2), (0, 6)),
+    "6": ((0, 6), (0, 2), (0, 6), (0, 2, 2, 2), (0, 6)),
+    "7": ((0, 6), (4, 2), (4, 2), (4, 2), (4, 2)),
+    "8": ((0, 6), (0, 2, 2, 2), (0, 6), (0, 2, 2, 2), (0, 6)),
+    "9": ((0, 6), (0, 2, 2, 2), (0, 6), (4, 2), (0, 6)),
+    ":": ((), (2, 2), (), (2, 2), ()),
+    ".": ((), (), (), (), (2, 2)),
+    "-": ((), (), (0, 6), (), ()),
+}
+
+
+def _row(runs: Runs, size: int) -> str:
+    cells: list[str] = []
+    on = False
+    for length in runs:
+        cells.append((BLOCK if on else " ") * (length * size))
+        on = not on
+    return "".join(cells).ljust(GLYPH_WIDTH * size)
+
+
+def _glyph(ch: str, size: int) -> list[str]:
+    runs = GLYPHS.get(ch)
+    if runs is None:
+        return [" " * (GLYPH_WIDTH * size)] * (GLYPH_HEIGHT * size)
+    rows: list[str] = []
+    for row_runs in runs:
+        rows.extend([_row(row_runs, size)] * size)
+    return rows
+
+
+def text_width(text: str, size: int) -> int:
+    """Total columns ``render(text, size)`` occupies."""
+    if not text:
+        return 0
+    return len(text) * (GLYPH_WIDTH * size + SPACING) - SPACING
+
+
+def text_width_rows(rows: list[str]) -> int:
+    """Width of already rendered rows (all rows of a glyph string are equally wide)."""
+    return len(rows[0]) if rows else 0
+
+
+def render(text: str, size: int = 1) -> list[str]:
+    """Render ``text`` as ``GLYPH_HEIGHT * size`` rows of block characters.
+
+    Glyphs are separated by ``SPACING`` blank columns (not scaled). Characters without
+    a glyph render as blank space of glyph width, so layout stays stable.
+    """
+    if size < 1:
+        raise ValueError(f"size must be >= 1, got {size}")
+    height = GLYPH_HEIGHT * size
+    if not text:
+        return [""] * height
+    glyphs = [_glyph(ch, size) for ch in text]
+    gap = " " * SPACING
+    return [gap.join(glyph[i] for glyph in glyphs) for i in range(height)]

tclock/modes/__init__.py

@@ -0,0 +1,20 @@
+"""Mode engines: clock, timer, stopwatch and countdown."""
+
+from tclock.modes.base import PAUSED_FOOTER, ElapsedClock, Frame, Mode, Pausable, wall_clock_ms
+from tclock.modes.clock import Clock
+from tclock.modes.countdown import Countdown
+from tclock.modes.stopwatch import Stopwatch
+from tclock.modes.timer import Timer
+
+__all__ = [
+    "PAUSED_FOOTER",
+    "Clock",
+    "Countdown",
+    "ElapsedClock",
+    "Frame",
+    "Mode",
+    "Pausable",
+    "Stopwatch",
+    "Timer",
+    "wall_clock_ms",
+]

tclock/modes/base.py

@@ -0,0 +1,75 @@
+"""Shared types for mode engines.
+
+Engines are plain Python: they read an injected millisecond clock and return a
+:class:`Frame` describing what the UI should show. They never import Textual.
+"""
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+PAUSED_FOOTER = "PAUSED (press <SPACE> to resume)"
+
+
+def wall_clock_ms() -> int:
+    """Current wall-clock time in whole milliseconds."""
+    return time.time_ns() // 1_000_000
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    """One tick's worth of display state."""
+
+    text: str | None
+    """Digits to draw, or ``None`` to leave the digit area blank (blink-off phase)."""
+    header: str | None = None
+    footer: str | None = None
+    flash: bool = False
+    """Invert colors (green background) - used when a timer has run out."""
+    finished: bool = False
+    """The app should exit."""
+
+
+@runtime_checkable
+class Mode(Protocol):
+    def snapshot(self) -> Frame: ...
+
+
+@runtime_checkable
+class Pausable(Protocol):
+    def is_paused(self) -> bool: ...
+
+    def toggle_paused(self) -> None: ...
+
+
+class ElapsedClock:
+    """Accumulates elapsed milliseconds with pause/resume."""
+
+    def __init__(self, now_ms: Callable[[], int] = wall_clock_ms, *, running: bool = True) -> None:
+        self._now = now_ms
+        self._accumulated_ms = 0
+        self._started_at_ms: int | None = now_ms() if running else None
+
+    def elapsed_ms(self) -> int:
+        if self._started_at_ms is None:
+            return self._accumulated_ms
+        return self._accumulated_ms + (self._now() - self._started_at_ms)
+
+    def is_paused(self) -> bool:
+        return self._started_at_ms is None
+
+    def pause(self) -> None:
+        if self._started_at_ms is not None:
+            self._accumulated_ms += self._now() - self._started_at_ms
+            self._started_at_ms = None
+
+    def resume(self) -> None:
+        if self._started_at_ms is None:
+            self._started_at_ms = self._now()
+
+    def toggle_paused(self) -> None:
+        if self.is_paused():
+            self.resume()
+        else:
+            self.pause()

tclock/modes/clock.py

@@ -0,0 +1,39 @@
+"""Clock mode: the current time, optionally in another timezone."""
+
+from collections.abc import Callable
+from datetime import datetime, tzinfo
+from zoneinfo import ZoneInfo
+
+from tclock.modes.base import Frame
+
+
+class Clock:
+    def __init__(
+        self,
+        *,
+        show_date: bool = True,
+        show_secs: bool = True,
+        show_millis: bool = False,
+        tz: ZoneInfo | None = None,
+        now: Callable[[tzinfo | None], datetime] = datetime.now,
+    ) -> None:
+        self.show_date = show_date
+        self.show_secs = show_secs
+        self.show_millis = show_millis
+        self.tz = tz
+        self._now = now
+
+    def snapshot(self) -> Frame:
+        now = self._now(self.tz)
+        if self.show_millis:
+            text = f"{now:%H:%M:%S}.{now.microsecond // 100_000}"
+        elif self.show_secs:
+            text = f"{now:%H:%M:%S}"
+        else:
+            text = f"{now:%H:%M}"
+        header = None
+        if self.show_date:
+            header = f"{now:%Y-%m-%d}"
+            if self.tz is not None:
+                header += f" {self.tz.key}"
+        return Frame(text=text, header=header)

tclock/modes/countdown.py

@@ -0,0 +1,41 @@
+"""Countdown mode: time until (or, reversed, since) a fixed moment."""
+
+from collections.abc import Callable
+from datetime import datetime
+
+from tclock.modes.base import Frame, wall_clock_ms
+from tclock.timefmt import DurationFormat, format_duration
+
+
+class Countdown:
+    def __init__(
+        self,
+        target: datetime,
+        *,
+        title: str | None = None,
+        continue_on_zero: bool = False,
+        reverse: bool = False,
+        fmt: DurationFormat = DurationFormat.HOUR_MIN_SEC,
+        now_ms: Callable[[], int] = wall_clock_ms,
+    ) -> None:
+        if target.tzinfo is None:
+            target = target.astimezone()
+        self.target_ms = int(target.timestamp() * 1000)
+        self.title = title
+        self.continue_on_zero = continue_on_zero
+        self.reverse = reverse
+        self.fmt = fmt
+        self._now = now_ms
+
+    def remaining_ms(self) -> int:
+        remaining = self.target_ms - self._now()
+        return -remaining if self.reverse else remaining
+
+    def snapshot(self) -> Frame:
+        remaining = self.remaining_ms()
+        if remaining < 0 and not self.continue_on_zero:
+            # Blink "0:00" at 1 Hz once the moment has passed.
+            if (-remaining) % 1000 < 500:
+                return Frame(text=None, header=self.title)
+            return Frame(text=format_duration(0, self.fmt), header=self.title)
+        return Frame(text=format_duration(remaining, self.fmt), header=self.title)

tclock/modes/stopwatch.py

@@ -0,0 +1,33 @@
+"""Stopwatch mode: counts up from zero, pausable with Space."""
+
+from collections.abc import Callable
+
+from tclock.modes.base import PAUSED_FOOTER, ElapsedClock, Frame, wall_clock_ms
+from tclock.timefmt import DurationFormat, format_duration
+
+
+class Stopwatch:
+    def __init__(self, *, now_ms: Callable[[], int] = wall_clock_ms) -> None:
+        self._clock = ElapsedClock(now_ms)
+
+    def elapsed_ms(self) -> int:
+        return self._clock.elapsed_ms()
+
+    def display_time(self) -> str:
+        return format_duration(self.elapsed_ms(), DurationFormat.HOUR_MIN_SEC_DECI)
+
+    def is_paused(self) -> bool:
+        return self._clock.is_paused()
+
+    def pause(self) -> None:
+        self._clock.pause()
+
+    def resume(self) -> None:
+        self._clock.resume()
+
+    def toggle_paused(self) -> None:
+        self._clock.toggle_paused()
+
+    def snapshot(self) -> Frame:
+        footer = PAUSED_FOOTER if self.is_paused() else None
+        return Frame(text=self.display_time(), footer=footer)