term-clock-app 1.0.0__tar.gz

term_clock_app-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo Wood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

term_clock_app-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: term-clock-app
+Version: 1.0.0
+Summary: A terminal digital clock that scales to fill the window.
+Author: Lorenzo Wood
+License: MIT License
+        
+        Copyright (c) 2026 Lorenzo Wood
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/lorenzowood/term-clock
+Project-URL: Repository, https://github.com/lorenzowood/term-clock
+Project-URL: Issues, https://github.com/lorenzowood/term-clock/issues
+Keywords: clock,terminal,tui,ssh
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# term-clock
+
+A digital clock for the terminal. It shows `hh:mm:ss`, stays on the wall-clock
+second, and grows to fill the window.
+
+Works over SSH the same way it works locally: alternate screen, no flicker,
+CTRL+C returns you to the prompt.
+
+## Install
+
+```sh
+pip install term-clock-app
+```
+
+The PyPI name is `term-clock-app` because `term-clock` / `termclock` is already taken. The command you run is still `term-clock`.
+
+From a clone:
+
+```sh
+pip install -e .
+```
+
+Python 3.9 or newer. No runtime dependencies.
+
+## Run
+
+```sh
+term-clock
+# or
+python -m term_clock
+```
+
+```sh
+term-clock --padding 1 --spacing 2          # defaults
+term-clock --padding 2 --spacing 4
+term-clock --hour-format 12
+term-clock --hour-format 24
+```
+
+Press **CTRL+C** to quit.
+
+## Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--padding N` | `1` | Blank rows and columns on every side |
+| `--spacing N` | `2` | Blank columns between digits |
+| `--hour-format {12,24}` | system clock, or `24` | 12-hour with AM/PM, or 24-hour |
+
+The default hour format follows the environment's time locale
+(`LC_TIME` / `T_FMT`) when that can be read. If it cannot, the clock uses 24-hour.
+
+## Display
+
+- **7 or fewer lines**: a plain text clock, centred.
+- **8+ lines**: large seven-segment digits drawn with full blocks `█` for
+  horizontal and vertical bars, and the four triangles `◤ ◥ ◣ ◢` for 45°
+  corner cuts (one column per row — never sampled, never an off-angle
+  diagonal). They grow to fill the window (each axis stretched by at most
+  1.5× before the rest becomes centring margin). If the window is too small
+  for a readable clock, it falls back to the text version.
+- **Colons**: two small axis-aligned blocks (no diagonals), centred, spanning
+  at most one third of the digit height.
+- **12-hour**: AM or PM sits to the right of the digits.
+- **Timing**: after each flip the process sleeps until the next wall-clock
+  second, then measures how late or early it woke (target: within 2 ms) and
+  shortens or lengthens the following sleep. A resize is picked up on the
+  next second. Unchanged cells are not rewritten.
+
+## Develop
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Pure rendering lives in `term_clock/core.py` (unit-tested). The terminal loop
+is in `term_clock/cli.py`.
+
+See `DESIGN.md` for the design and the TDD log.
+
+## License
+
+MIT. See `LICENSE`.

term_clock_app-1.0.0/README.md

@@ -0,0 +1,84 @@
+# term-clock
+
+A digital clock for the terminal. It shows `hh:mm:ss`, stays on the wall-clock
+second, and grows to fill the window.
+
+Works over SSH the same way it works locally: alternate screen, no flicker,
+CTRL+C returns you to the prompt.
+
+## Install
+
+```sh
+pip install term-clock-app
+```
+
+The PyPI name is `term-clock-app` because `term-clock` / `termclock` is already taken. The command you run is still `term-clock`.
+
+From a clone:
+
+```sh
+pip install -e .
+```
+
+Python 3.9 or newer. No runtime dependencies.
+
+## Run
+
+```sh
+term-clock
+# or
+python -m term_clock
+```
+
+```sh
+term-clock --padding 1 --spacing 2          # defaults
+term-clock --padding 2 --spacing 4
+term-clock --hour-format 12
+term-clock --hour-format 24
+```
+
+Press **CTRL+C** to quit.
+
+## Options
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--padding N` | `1` | Blank rows and columns on every side |
+| `--spacing N` | `2` | Blank columns between digits |
+| `--hour-format {12,24}` | system clock, or `24` | 12-hour with AM/PM, or 24-hour |
+
+The default hour format follows the environment's time locale
+(`LC_TIME` / `T_FMT`) when that can be read. If it cannot, the clock uses 24-hour.
+
+## Display
+
+- **7 or fewer lines**: a plain text clock, centred.
+- **8+ lines**: large seven-segment digits drawn with full blocks `█` for
+  horizontal and vertical bars, and the four triangles `◤ ◥ ◣ ◢` for 45°
+  corner cuts (one column per row — never sampled, never an off-angle
+  diagonal). They grow to fill the window (each axis stretched by at most
+  1.5× before the rest becomes centring margin). If the window is too small
+  for a readable clock, it falls back to the text version.
+- **Colons**: two small axis-aligned blocks (no diagonals), centred, spanning
+  at most one third of the digit height.
+- **12-hour**: AM or PM sits to the right of the digits.
+- **Timing**: after each flip the process sleeps until the next wall-clock
+  second, then measures how late or early it woke (target: within 2 ms) and
+  shortens or lengthens the following sleep. A resize is picked up on the
+  next second. Unchanged cells are not rewritten.
+
+## Develop
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Pure rendering lives in `term_clock/core.py` (unit-tested). The terminal loop
+is in `term_clock/cli.py`.
+
+See `DESIGN.md` for the design and the TDD log.
+
+## License
+
+MIT. See `LICENSE`.

term_clock_app-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "term-clock-app"
+version = "1.0.0"
+description = "A terminal digital clock that scales to fill the window."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Lorenzo Wood" }]
+keywords = ["clock", "terminal", "tui", "ssh"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/lorenzowood/term-clock"
+Repository = "https://github.com/lorenzowood/term-clock"
+Issues = "https://github.com/lorenzowood/term-clock/issues"
+
+[project.scripts]
+term-clock = "term_clock.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[tool.setuptools]
+packages = ["term_clock"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

term_clock_app-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

term_clock_app-1.0.0/term_clock/__init__.py

@@ -0,0 +1,3 @@
+"""A terminal digital clock that scales to fill the window."""
+
+__version__ = "1.0.0"

term_clock_app-1.0.0/term_clock/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

term_clock_app-1.0.0/term_clock/cli.py

@@ -0,0 +1,203 @@
+"""Terminal runtime: paints the clock and stays current until CTRL+C."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+import time
+from typing import Callable, Sequence, TextIO
+
+from . import core
+
+_ALT_ON = "\x1b[?1049h"
+_ALT_OFF = "\x1b[?1049l"
+_CURSOR_HIDE = "\x1b[?25l"
+_CURSOR_SHOW = "\x1b[?25h"
+_WRAP_OFF = "\x1b[?7l"
+_WRAP_ON = "\x1b[?7h"
+# Home, erase the visible screen, erase the scrollback. A full-width last
+# line would otherwise wrap and push every frame into the history.
+_CLEAR = "\x1b[H\x1b[2J\x1b[3J"
+
+
+def _nonneg(value: str) -> int:
+    n = int(value)
+    if n < 0:
+        raise argparse.ArgumentTypeError("must be >= 0")
+    return n
+
+
+_TOLERANCE_MS = 2.0
+_LEAD_MAX_MS = 100.0
+
+
+def next_second_ms(now_ms: float) -> float:
+    """Wall-clock millisecond of the next whole second after ``now_ms``."""
+    return (int(now_ms) // 1000 + 1) * 1000.0
+
+
+def sleep_ms(now_ms: float, target_ms: float, lead_ms: float) -> float:
+    """How long to sleep now so we arrive at ``target_ms``, given ``lead_ms``.
+
+    ``lead_ms`` is the estimated sleep overshoot, subtracted from the wait.
+    It is never allowed to skip past the boundary.
+    """
+    remain = target_ms - now_ms
+    if remain <= 0:
+        return 0.0
+    wait = remain - lead_ms
+    if wait <= 0:
+        wait = remain
+    return wait
+
+
+def adjust_lead_ms(lead_ms: float, error_ms: float) -> float:
+    """If we missed the second by more than 2 ms, shift the next sleep."""
+    if abs(error_ms) <= _TOLERANCE_MS:
+        return lead_ms
+    return min(_LEAD_MAX_MS, max(0.0, lead_ms + error_ms))
+
+
+def _wall_ms() -> float:
+    return time.time_ns() / 1_000_000.0
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="term-clock",
+        description="A terminal digital clock that scales to fill the window.",
+    )
+    p.add_argument(
+        "--padding",
+        type=_nonneg,
+        default=1,
+        metavar="N",
+        help="blank rows and columns around the clock (default: 1)",
+    )
+    p.add_argument(
+        "--spacing",
+        type=_nonneg,
+        default=2,
+        metavar="N",
+        help="blank columns between digits (default: 2)",
+    )
+    p.add_argument(
+        "--hour-format",
+        choices=("12", "24"),
+        default=None,
+        dest="hour_format",
+        help="12 or 24 (default: follow the system clock, or 24 if unknown)",
+    )
+    return p.parse_args(argv)
+
+
+def frame_for(
+    t: time.struct_time,
+    cols: int,
+    rows: int,
+    style: core.Style | None = None,
+) -> list[str]:
+    """Build the screen buffer for time ``t`` at the given terminal size."""
+    style = style or core.Style()
+    time_str = core.format_time(
+        t.tm_hour, t.tm_min, t.tm_sec, hour_format=style.hour_format
+    )
+    suffix = core.hour_period(t.tm_hour) if style.hour_format == "12" else ""
+    return core.render(time_str, rows=rows, cols=cols, style=style, suffix=suffix)
+
+
+def _write_diff(out: TextIO, old: Sequence[str], new: Sequence[str]) -> None:
+    """Emit cursor-addressed runs for cells that differ."""
+    for y, (a, b) in enumerate(zip(old, new)):
+        if a == b:
+            continue
+        width = max(len(a), len(b))
+        a = a.ljust(width)
+        b = b.ljust(width)
+        x = 0
+        while x < width:
+            if a[x] == b[x]:
+                x += 1
+                continue
+            start = x
+            while x < width and a[x] != b[x]:
+                x += 1
+            out.write(f"\x1b[{y + 1};{start + 1}H{b[start:x]}")
+
+
+class Painter:
+    """Off-screen current/next buffers; only changed cells are written."""
+
+    def __init__(self, out: TextIO) -> None:
+        self._out = out
+        self._last: list[str] | None = None
+
+    def paint(self, frame: Sequence[str]) -> None:
+        frame = list(frame)
+        if frame == self._last:
+            return
+        if self._last is None or len(self._last) != len(frame):
+            self._out.write(_CLEAR + "\n".join(frame))
+        else:
+            _write_diff(self._out, self._last, frame)
+        self._last = frame
+        self._out.flush()
+
+    def invalidate(self) -> None:
+        self._last = None
+
+
+def run(
+    out: TextIO | None = None,
+    get_size: Callable[[], tuple[int, int]] | None = None,
+    get_time: Callable[[], time.struct_time] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    style: core.Style | None = None,
+    now_ms: Callable[[], float] | None = None,
+) -> int:
+    out = out if out is not None else sys.stdout
+    get_size = get_size or (lambda: tuple(shutil.get_terminal_size((80, 24))))
+    get_time = get_time or time.localtime
+    now_ms = now_ms or _wall_ms
+
+    out.write(_ALT_ON + _CURSOR_HIDE + _WRAP_OFF)
+    out.flush()
+    painter = Painter(out)
+    last_size: tuple[int, int] | None = None
+    lead_ms = 0.0
+
+    def paint() -> None:
+        nonlocal last_size
+        cols, rows = get_size()
+        if (cols, rows) != last_size:
+            painter.invalidate()
+            last_size = (cols, rows)
+        painter.paint(frame_for(get_time(), cols=cols, rows=rows, style=style))
+
+    try:
+        while True:
+            paint()
+            target = next_second_ms(now_ms())
+            now = now_ms()
+            wait = sleep_ms(now, target, lead_ms)
+            if wait > 0:
+                sleep(wait / 1000.0)
+            lead_ms = adjust_lead_ms(lead_ms, now_ms() - target)
+    except KeyboardInterrupt:
+        return 0
+    finally:
+        out.write(_WRAP_ON + _CURSOR_SHOW + _ALT_OFF)
+        out.flush()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ns = parse_args(argv)
+    hour_format = ns.hour_format or core.system_hour_format()
+    return run(
+        style=core.Style(
+            padding=ns.padding,
+            spacing=ns.spacing,
+            hour_format=hour_format,
+        ),
+    )