tclock 0.1.2__py3-none-any.whl

tclock/modes/timer.py

@@ -0,0 +1,99 @@
+"""Timer mode: counts down one or more durations, flashes when done."""
+
+from collections.abc import Callable, Sequence
+
+from tclock.modes.base import PAUSED_FOOTER, ElapsedClock, Frame, wall_clock_ms
+from tclock.timefmt import DurationFormat, format_duration
+
+
+class Timer:
+    def __init__(
+        self,
+        durations_ms: Sequence[int],
+        *,
+        titles: Sequence[str] = (),
+        repeat: bool = False,
+        fmt: DurationFormat = DurationFormat.HOUR_MIN_SEC_DECI,
+        paused: bool = False,
+        auto_quit: bool = False,
+        execute: str | None = None,
+        now_ms: Callable[[], int] = wall_clock_ms,
+    ) -> None:
+        if not durations_ms:
+            raise ValueError("timer needs at least one duration")
+        if any(d <= 0 for d in durations_ms):
+            raise ValueError("timer durations must be positive")
+        self.durations_ms = list(durations_ms)
+        self.titles = list(titles)
+        self.repeat = repeat
+        self.fmt = fmt
+        self.auto_quit = auto_quit
+        self.execute = execute or None
+        self.execute_pending = False
+        """The UI should run :attr:`execute` and call :meth:`set_execute_result`."""
+        self.execute_result: str | None = None
+        self._clock = ElapsedClock(now_ms, running=not paused)
+
+    def remaining(self) -> tuple[int, int]:
+        """(milliseconds left in the current duration, index of that duration).
+
+        After the last duration (without ``repeat``) the remaining value goes negative
+        and keeps counting down, so callers can show how long ago the timer ended.
+        """
+        passed = self._clock.elapsed_ms()
+        if self.repeat:
+            passed %= sum(self.durations_ms)
+        idx = 0
+        checkpoint = self.durations_ms[0]
+        while checkpoint < passed and idx < len(self.durations_ms) - 1:
+            idx += 1
+            checkpoint += self.durations_ms[idx]
+        return checkpoint - passed, idx
+
+    def title(self, idx: int) -> str | None:
+        if not self.titles:
+            return None
+        return self.titles[min(idx, len(self.titles) - 1)]
+
+    def set_execute_result(self, result: str) -> None:
+        self.execute_result = result
+        self.execute_pending = False
+
+    def is_finished(self) -> bool:
+        return self.auto_quit and self.execute_result is not None
+
+    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:
+        remaining, idx = self.remaining()
+        header = self.title(idx)
+        footer = PAUSED_FOOTER if self.is_paused() else self.execute_result
+        if remaining >= 0:
+            return Frame(text=format_duration(remaining, self.fmt), header=header, footer=footer)
+
+        # The timer has run out.
+        if self.execute_result is None and not self.execute_pending:
+            if self.execute:
+                self.execute_pending = True
+            else:
+                self.execute_result = ""
+                footer = PAUSED_FOOTER if self.is_paused() else self.execute_result
+        overrun = -remaining
+        flash = overrun % 1000 < 500
+        return Frame(
+            text=format_duration(overrun, self.fmt) if flash else None,
+            header=header,
+            footer=footer,
+            flash=flash,
+            finished=self.is_finished(),
+        )

tclock/parsing.py

@@ -0,0 +1,94 @@
+"""Parsers for CLI and config values. All failures raise :class:`ParseError`."""
+
+import re
+from datetime import date, datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+class ParseError(ValueError):
+    """A user-supplied value could not be interpreted."""
+
+
+_DURATION_RE = re.compile(r"^(\d+)([smhd])$", re.IGNORECASE)
+_UNIT_MS = {"s": 1_000, "m": 60_000, "h": 3_600_000, "d": 86_400_000}
+
+_HEX_RE = re.compile(r"^#[0-9a-f]{6}$")
+
+# clock-tui color names -> Textual color strings (ratatui's 16 ANSI colors).
+COLOR_NAMES: dict[str, str] = {
+    "black": "ansi_black",
+    "red": "ansi_red",
+    "green": "ansi_green",
+    "yellow": "ansi_yellow",
+    "blue": "ansi_blue",
+    "magenta": "ansi_magenta",
+    "cyan": "ansi_cyan",
+    "gray": "ansi_white",
+    "darkgray": "ansi_bright_black",
+    "lightred": "ansi_bright_red",
+    "lightgreen": "ansi_bright_green",
+    "lightyellow": "ansi_bright_yellow",
+    "lightblue": "ansi_bright_blue",
+    "lightmagenta": "ansi_bright_magenta",
+    "lightcyan": "ansi_bright_cyan",
+    "white": "ansi_bright_white",
+}
+
+_NAIVE_FORMATS = ("%Y-%m-%d", "%Y-%m-%d %H:%M:%S")
+_TIME_FORMATS = ("%H:%M", "%H:%M:%S")
+
+
+def parse_duration(text: str) -> int:
+    """``10s``, ``5m``, ``1h``, ``2d`` (case-insensitive) -> milliseconds."""
+    match = _DURATION_RE.match(text)
+    if match is None:
+        raise ParseError(f"{text!r} is not a valid duration (examples: 30s, 5m, 1h, 2d)")
+    number, unit = match.groups()
+    return int(number) * _UNIT_MS[unit.lower()]
+
+
+def parse_color(text: str) -> str:
+    """A clock-tui color name or ``#rrggbb`` -> Textual color string."""
+    lowered = text.strip().lower()
+    if lowered in COLOR_NAMES:
+        return COLOR_NAMES[lowered]
+    if _HEX_RE.match(lowered):
+        return lowered
+    names = ", ".join(COLOR_NAMES)
+    raise ParseError(f"{text!r} is not a valid color; use #rrggbb or one of: {names}")
+
+
+def parse_datetime(text: str, *, today: date | None = None) -> datetime:
+    """Parse ``HH:MM``, ``HH:MM:SS``, ``YYYY-MM-DD``, ``YYYY-MM-DD HH:MM:SS`` or RFC 3339.
+
+    Naive forms are interpreted in the local timezone. The result is always aware.
+    """
+    text = text.strip()
+    today = today or datetime.now().date()
+    for fmt in _TIME_FORMATS:
+        try:
+            parsed_time = datetime.strptime(text, fmt).time()
+        except ValueError:
+            continue
+        return datetime.combine(today, parsed_time).astimezone()
+    for fmt in _NAIVE_FORMATS:
+        try:
+            return datetime.strptime(text, fmt).astimezone()
+        except ValueError:
+            continue
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        raise ParseError(
+            f"{text!r} is not a valid time; use HH:MM, YYYY-MM-DD, "
+            "'YYYY-MM-DD HH:MM:SS' or RFC 3339"
+        ) from None
+    return parsed.astimezone()
+
+
+def parse_timezone(text: str) -> ZoneInfo:
+    """An IANA zone key such as ``Europe/Oslo``."""
+    try:
+        return ZoneInfo(text.strip())
+    except ZoneInfoNotFoundError, ValueError:
+        raise ParseError(f"{text!r} is not a known timezone (example: Europe/Oslo)") from None

tclock/resolve.py

@@ -0,0 +1,163 @@
+"""Merge CLI options with the config file and build the mode engine.
+
+Precedence: CLI flag > config file > built-in default. CLI booleans are "set" flags, so
+they can only turn a behaviour on (``flag or config_value``), matching clock-tui.
+CLI values arrive already validated by the CLI layer; config values are validated here
+with a warning and a fallback for each bad key.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from zoneinfo import ZoneInfo
+
+from tclock.config import Config, warn_stderr
+from tclock.modes import Clock, Countdown, Mode, Stopwatch, Timer
+from tclock.parsing import ParseError, parse_color, parse_datetime, parse_duration, parse_timezone
+from tclock.timefmt import DurationFormat
+
+MODES = ("clock", "timer", "stopwatch", "countdown")
+
+Warn = Callable[[str], None]
+
+
+class ResolveError(Exception):
+    """The combination of CLI options and config cannot produce a runnable mode."""
+
+
+@dataclass(slots=True, kw_only=True)
+class Options:
+    """What the user asked for on the command line. ``None``/``False``/``[]`` = not given."""
+
+    mode: str | None = None
+    color: str | None = None
+    size: int | None = None
+    # clock
+    timezone: str | None = None
+    no_date: bool = False
+    no_seconds: bool = False
+    millis: bool = False
+    # timer
+    durations: list[str] = field(default_factory=list)
+    titles: list[str] = field(default_factory=list)
+    repeat: bool = False
+    no_millis: bool = False
+    paused: bool = False
+    auto_quit: bool = False
+    execute: str | None = None
+    # countdown
+    time: str | None = None
+    title: str | None = None
+    continue_on_zero: bool = False
+    reverse: bool = False
+
+
+@dataclass(slots=True)
+class Resolved:
+    engine: Mode
+    color: str
+    size: int
+
+
+def resolve(options: Options, config: Config, *, warn: Warn = warn_stderr) -> Resolved:
+    mode = options.mode or config.default.mode
+    if mode not in MODES:
+        warn(f"tclock: unknown mode {mode!r} in config; using clock")
+        mode = "clock"
+
+    engine: Mode
+    if mode == "timer":
+        engine = build_timer(options, config, warn=warn)
+    elif mode == "stopwatch":
+        engine = build_stopwatch()
+    elif mode == "countdown":
+        engine = build_countdown(options, config, warn=warn)
+    else:
+        engine = build_clock(options, config, warn=warn)
+
+    return Resolved(
+        engine=engine, color=_color(options, config, warn), size=_size(options, config, warn)
+    )
+
+
+def _color(options: Options, config: Config, warn: Warn) -> str:
+    if options.color is not None:
+        return parse_color(options.color)
+    try:
+        return parse_color(config.default.color)
+    except ParseError as exc:
+        warn(f"tclock: config default.color: {exc}; using green")
+        return parse_color("green")
+
+
+def _size(options: Options, config: Config, warn: Warn) -> int:
+    if options.size is not None:
+        return options.size
+    if config.default.size < 1:
+        warn(f"tclock: config default.size must be >= 1, got {config.default.size}; using 1")
+        return 1
+    return config.default.size
+
+
+def build_clock(options: Options, config: Config, *, warn: Warn = warn_stderr) -> Clock:
+    tz: ZoneInfo | None = None
+    if options.timezone is not None:
+        tz = parse_timezone(options.timezone)
+    elif config.clock.timezone is not None:
+        try:
+            tz = parse_timezone(config.clock.timezone)
+        except ParseError as exc:
+            warn(f"tclock: config clock.timezone: {exc}; using local time")
+    return Clock(
+        show_date=not options.no_date and config.clock.show_date,
+        show_secs=not options.no_seconds and config.clock.show_seconds,
+        show_millis=options.millis or config.clock.show_millis,
+        tz=tz,
+    )
+
+
+def build_timer(options: Options, config: Config, *, warn: Warn = warn_stderr) -> Timer:
+    if options.durations:
+        durations_ms = [parse_duration(d) for d in options.durations]
+    else:
+        durations_ms = []
+        for text in config.timer.durations:
+            try:
+                durations_ms.append(parse_duration(text))
+            except ParseError as exc:
+                warn(f"tclock: config timer.durations: {exc}; skipping it")
+        if not durations_ms:
+            durations_ms = [25 * 60_000, 5 * 60_000]
+
+    show_millis = not options.no_millis and config.timer.show_millis
+    execute = options.execute or " ".join(config.timer.execute) or None
+    return Timer(
+        durations_ms,
+        titles=options.titles or config.timer.titles,
+        repeat=options.repeat or config.timer.repeat,
+        fmt=DurationFormat.HOUR_MIN_SEC_DECI if show_millis else DurationFormat.HOUR_MIN_SEC,
+        paused=options.paused or config.timer.start_paused,
+        auto_quit=options.auto_quit or config.timer.auto_quit,
+        execute=execute,
+    )
+
+
+def build_stopwatch() -> Stopwatch:
+    return Stopwatch()
+
+
+def build_countdown(options: Options, config: Config, *, warn: Warn = warn_stderr) -> Countdown:
+    time_text = options.time or config.countdown.time
+    if time_text is None:
+        raise ResolveError("countdown needs --time or a [countdown] time entry in the config file")
+    try:
+        target = parse_datetime(time_text)
+    except ParseError as exc:
+        raise ResolveError(str(exc)) from None
+    show_millis = options.millis or config.countdown.show_millis
+    return Countdown(
+        target,
+        title=options.title or config.countdown.title,
+        continue_on_zero=options.continue_on_zero or config.countdown.continue_on_zero,
+        reverse=options.reverse or config.countdown.reverse,
+        fmt=DurationFormat.HOUR_MIN_SEC_DECI if show_millis else DurationFormat.HOUR_MIN_SEC,
+    )

tclock/timefmt.py

@@ -0,0 +1,37 @@
+"""Formatting of millisecond durations as D:HH:MM:SS[.d] strings."""
+
+from enum import Enum
+
+
+class DurationFormat(Enum):
+    """How much precision a formatted duration shows."""
+
+    HOUR_MIN_SEC = "hms"
+    HOUR_MIN_SEC_DECI = "hmsd"
+
+
+def format_duration(ms: int, fmt: DurationFormat) -> str:
+    """Format ``ms`` like ``1:05``, ``1:30:00``, ``2:01:00:00`` or ``0:05.3``.
+
+    Minutes and seconds are always present. Hours appear once the duration reaches one
+    hour, days once it reaches 24 hours. The leading component is not zero-padded, the
+    rest are. Negative durations get a leading ``-``.
+    """
+    negative = ms < 0
+    ms = abs(ms)
+    total_seconds, millis = divmod(ms, 1000)
+    total_minutes, seconds = divmod(total_seconds, 60)
+    total_hours, minutes = divmod(total_minutes, 60)
+    days, hours = divmod(total_hours, 24)
+
+    parts: list[str] = []
+    if days > 0:
+        parts.append(str(days))
+    if total_hours > 0:
+        parts.append(f"{hours:02d}" if parts else str(hours))
+    parts.append(f"{minutes:02d}" if parts else str(minutes))
+    parts.append(f"{seconds:02d}")
+    result = ":".join(parts)
+    if fmt is DurationFormat.HOUR_MIN_SEC_DECI:
+        result += f".{millis // 100}"
+    return f"-{result}" if negative else result

tclock/ui.py

@@ -0,0 +1,230 @@
+"""Textual front end: one app, one big-digit widget, header and footer labels."""
+
+import subprocess
+from collections.abc import Callable
+
+from rich.text import Text
+from textual import events, work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.geometry import Size
+from textual.screen import ModalScreen, Screen
+from textual.timer import Timer as TextualTimer
+from textual.widget import Widget
+from textual.widgets import Footer, Label, Static
+
+from tclock import font
+from tclock.config import Config
+from tclock.modes import Mode, Pausable, Timer
+from tclock.resolve import Options, build_clock, build_stopwatch, build_timer
+
+FLASH_CLASS = "-flash"
+FLASH_TEXT_COLOR = "ansi_black"
+
+# (keys, what they do) as shown in the "?" overlay.
+KEY_HELP: tuple[tuple[str, str], ...] = (
+    ("q, Ctrl+C", "Quit"),
+    ("Space", "Pause / resume (timer and stopwatch)"),
+    ("c", "Clock"),
+    ("w", "Stopwatch"),
+    ("t", "Timer (durations from the config file)"),
+    ("?", "Toggle this help"),
+)
+
+
+def run_shell(command: str) -> str:
+    """Run ``command`` in the platform shell and summarise the outcome on one line."""
+    try:
+        proc = subprocess.run(command, shell=True, capture_output=True, text=True, errors="replace")
+    except OSError as exc:
+        return f"[FAILED] {exc}"
+    if proc.returncode != 0:
+        return " ".join(f"[ERROR] {proc.stderr}".split())
+    return " ".join(f"[SUCCEED] {proc.stdout}".split())
+
+
+class BigTime(Widget):
+    """Draws text in the bricks font, centred horizontally."""
+
+    DEFAULT_CSS = """
+    BigTime {
+        width: 100%;
+        height: auto;
+        text-wrap: nowrap;
+        text-overflow: clip;
+    }
+    """
+
+    def __init__(self, size: int = 1, *, id: str | None = None) -> None:
+        super().__init__(id=id)
+        # Not ``self.size``: Textual's Widget.size is a read-only property.
+        self.scale = size
+        self.rows: list[str] = font.render("", size)
+
+    def set_text(self, text: str | None) -> None:
+        rows = font.render(text or "", self.scale)
+        if rows != self.rows:
+            self.rows = rows
+            self.refresh(layout=True)
+
+    def render(self) -> Text:
+        # Centre by hand: when the digits are wider than the terminal this leaves them
+        # left-aligned and clipped on the right, like clock-tui, instead of cutting
+        # off the leading digit.
+        width = self.size.width
+        pad = " " * max(0, (width - font.text_width_rows(self.rows)) // 2)
+        return Text("\n".join(pad + row for row in self.rows), no_wrap=True, end="")
+
+    def get_content_height(self, container: Size, viewport: Size, width: int) -> int:
+        return len(self.rows)
+
+
+class HelpScreen(ModalScreen[None]):
+    """The "?" overlay listing every key."""
+
+    BINDINGS = [
+        Binding("question_mark", "dismiss", "Close help", show=False),
+        Binding("escape", "dismiss", "Close help", show=False),
+        Binding("q", "dismiss", "Close help", show=False),
+    ]
+
+    def compose(self) -> ComposeResult:
+        width = max(len(keys) for keys, _ in KEY_HELP)
+        lines = "\n".join(f"{keys:<{width}}   {what}" for keys, what in KEY_HELP)
+        with Vertical(id="help") as box:
+            box.border_title = "Keys"
+            yield Static(lines, id="help-keys")
+
+
+class ClockApp(App[None]):
+    CSS_PATH = "app.tcss"
+    ENABLE_COMMAND_PALETTE = False
+    TICK_SECONDS = 0.1
+    KEY_BAR_SECONDS = 3.0
+    """How long the key bar stays visible after the last keyboard or mouse input."""
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("ctrl+c", "quit", "Quit", show=False, priority=True),
+        Binding("space", "toggle_pause", "Pause", key_display="Space"),
+        Binding("c", "mode_clock", "Clock"),
+        Binding("w", "mode_stopwatch", "Stopwatch"),
+        Binding("t", "mode_timer", "Timer"),
+        Binding("question_mark", "toggle_help", "Help", key_display="?"),
+    ]
+
+    def __init__(
+        self,
+        engine: Mode,
+        *,
+        color: str,
+        size: int,
+        config: Config,
+        runner: Callable[[str], str] = run_shell,
+    ) -> None:
+        super().__init__()
+        self.engine = engine
+        # Not ``self.size``/``self.color``: App.size is a read-only Textual property.
+        self.digit_color = color
+        self.digit_size = size
+        self.config = config
+        self._runner = runner
+        self._execute_running = False
+        self._key_bar_timer: TextualTimer | None = None
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="body"):
+            yield Label("", id="header")
+            yield BigTime(self.digit_size, id="time")
+            yield Label("", id="footer")
+        yield Footer(id="keybar")
+
+    def on_mount(self) -> None:
+        # Keep references: ``self.query_one`` looks at the *active* screen, which is
+        # the help overlay while it is open.
+        self.main_screen: Screen[object] = self.screen
+        self._header = self.main_screen.query_one("#header", Label)
+        self._footer = self.main_screen.query_one("#footer", Label)
+        self._big = self.main_screen.query_one(BigTime)
+        self._key_bar = self.main_screen.query_one(Footer)
+        self._key_bar.display = False
+        self.tick()
+        self.set_interval(self.TICK_SECONDS, self.tick)
+
+    async def on_event(self, event: events.Event) -> None:
+        if isinstance(event, events.InputEvent):
+            self._show_key_bar()
+        await super().on_event(event)
+
+    def _show_key_bar(self) -> None:
+        if self._key_bar_timer is not None:
+            self._key_bar_timer.stop()
+        self._key_bar.display = True
+        self._key_bar_timer = self.set_timer(self.KEY_BAR_SECONDS, self._hide_key_bar)
+
+    def _hide_key_bar(self) -> None:
+        self._key_bar.display = False
+        self._key_bar_timer = None
+
+    def tick(self) -> None:
+        frame = self.engine.snapshot()
+        self._header.update(frame.header or "")
+        self._footer.update(frame.footer or "")
+        self._big.set_text(frame.text)
+        self._big.styles.color = FLASH_TEXT_COLOR if frame.flash else self.digit_color
+        self.main_screen.set_class(frame.flash, FLASH_CLASS)
+        self._maybe_execute()
+        if frame.finished:
+            self.exit()
+
+    def _maybe_execute(self) -> None:
+        engine = self.engine
+        if not isinstance(engine, Timer) or not engine.execute_pending or self._execute_running:
+            return
+        if engine.execute is None:
+            return
+        self._execute_running = True
+        self._run_execute(engine, engine.execute)
+
+    @work(thread=True, exclusive=True)
+    def _run_execute(self, timer: Timer, command: str) -> None:
+        result = self._runner(command)
+        self.call_from_thread(self._on_execute_done, timer, result)
+
+    def _on_execute_done(self, timer: Timer, result: str) -> None:
+        timer.set_execute_result(result)
+        self._execute_running = False
+        if timer is self.engine:
+            self.tick()
+
+    def action_toggle_pause(self) -> None:
+        if isinstance(self.engine, Pausable):
+            self.engine.toggle_paused()
+            self.tick()
+
+    def action_mode_clock(self) -> None:
+        self._switch(build_clock(Options(), self.config))
+
+    def action_mode_stopwatch(self) -> None:
+        self._switch(build_stopwatch())
+
+    def action_mode_timer(self) -> None:
+        self._switch(build_timer(Options(), self.config))
+
+    def action_toggle_help(self) -> None:
+        if isinstance(self.screen, HelpScreen):
+            self.pop_screen()
+        else:
+            self.push_screen(HelpScreen())
+
+    def _switch(self, engine: Mode) -> None:
+        self.engine = engine
+        self._execute_running = False
+        self.tick()
+
+
+def run(engine: Mode, *, color: str, size: int, config: Config) -> Mode:
+    """Run the TUI until the user quits; return the engine that was active at exit."""
+    app = ClockApp(engine, color=color, size=size, config=config)
+    app.run()
+    return app.engine