tclock 0.1.2__tar.gz

tclock-0.1.2/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Eivind Teig
+
+This project is a Python port of clock-tui, Copyright (c) 2022 Race604
+(https://github.com/race604/clock-tui), also released under the MIT License.
+
+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 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.

tclock-0.1.2/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: tclock
+Version: 0.1.2
+Summary: A clock, timer, stopwatch and countdown for your terminal, built with Textual
+Keywords: clock,timer,stopwatch,countdown,tui,textual,terminal
+Author: Eivind Teig
+Author-email: Eivind Teig <eivind.teig@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: textual>=8.0
+Requires-Dist: typer>=0.15
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: tzdata ; sys_platform == 'win32'
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/eivl/tclock
+Project-URL: Repository, https://github.com/eivl/tclock
+Project-URL: Issues, https://github.com/eivl/tclock/issues
+Project-URL: Original, https://github.com/race604/clock-tui
+Description-Content-Type: text/markdown
+
+# tclock
+
+A clock, timer, stopwatch and countdown for your terminal, drawn with big block digits.
+Built with [Textual](https://textual.textualize.io/). A Python port of
+[race604/clock-tui](https://github.com/race604/clock-tui).
+
+Works on Linux, macOS and Windows. Requires Python 3.14 or newer.
+
+## Install
+
+```shell
+uv tool install tclock
+# or
+pipx install tclock
+# or
+pip install tclock
+```
+
+## Usage
+
+```shell
+tclock                 # clock (default mode)
+tclock clock -z Asia/Tokyo -D      # another timezone, no date line
+tclock timer -d 25m -d 5m -t Work -t Break -r
+tclock stopwatch
+tclock countdown -t 2027-01-01 -T "New year"
+tclock -c '#e63946' -s 2           # colour and size apply to every mode
+```
+
+Keys while running:
+
+| Key              | Action                                 |
+|------------------|----------------------------------------|
+| `q`, `Ctrl+C`    | quit                                   |
+| `Space`          | pause / resume (timer and stopwatch)   |
+| `c`              | switch to clock                        |
+| `w`              | switch to stopwatch                    |
+| `t`              | switch to timer (defaults from config) |
+| `?`              | show / hide the key overlay            |
+
+A key bar with the same bindings appears along the bottom whenever you touch the keyboard
+or mouse and fades out after a few seconds, so the clock stays clean at rest.
+
+Run `tclock --help` or `tclock <mode> --help` for every flag.
+
+### Clock
+
+`tclock clock [-z TZ] [-D] [-S] [-m]` shows the current time. `-z` takes an IANA zone such
+as `Europe/Oslo`. `-D` hides the date, `-S` hides seconds, `-m` shows tenths of a second.
+
+### Timer
+
+`tclock timer -d 5m` counts down five minutes. Durations are a number plus `s`, `m`, `h`
+or `d`. Repeat `-d` to run several durations in sequence and `-t` to title each of them.
+`-r` repeats the sequence, `-P` starts paused, `-Q` quits when time is up, `-M` hides
+tenths.
+
+`-e` runs a shell command when the timer ends and shows its result in the footer:
+
+```shell
+tclock timer -d 25m -e 'notify-send tclock "Time is up"'      # Linux
+tclock timer -d 25m -e 'osascript -e "display notification \"Time is up\""'   # macOS
+tclock timer -d 25m -e 'msg * Time is up'                       # Windows
+```
+
+When the timer runs out the screen flashes green until you quit or switch mode.
+
+### Stopwatch
+
+`tclock stopwatch` counts up. Press `Space` to pause. The final time is printed to the
+terminal after you quit.
+
+### Countdown
+
+`tclock countdown -t WHEN [-T TITLE] [-c] [-r] [-m]` shows the time until `WHEN`, which
+can be `20:00`, `20:00:00` (today), `2027-01-01` (midnight), `2026-12-25 20:00:00` (local
+time) or RFC 3339 such as `2026-12-25T20:00:00-04:00`. `-c` keeps counting (negative)
+after the moment has passed instead of blinking `0:00`; `-r` counts up since the moment.
+
+## Configuration
+
+tclock reads an optional TOML file:
+
+| OS      | Path                                                        |
+|---------|-------------------------------------------------------------|
+| Linux   | `~/.config/tclock/config.toml` (honours `$XDG_CONFIG_HOME`) |
+| macOS   | `~/Library/Application Support/tclock/config.toml`          |
+| Windows | `%APPDATA%\tclock\config.toml`                              |
+
+Command-line flags override the file; the file overrides built-in defaults. Every key is
+optional. The full schema, with the built-in defaults:
+
+```toml
+[default]
+mode = "clock"          # clock, timer, stopwatch or countdown when no mode is given
+color = "green"
+size = 1
+
+[clock]
+show_date = true
+show_seconds = true
+show_millis = false
+# timezone = "Europe/Oslo"
+
+[timer]
+durations = ["25m", "5m"]
+titles = []
+repeat = false
+show_millis = true
+start_paused = false
+auto_quit = false
+execute = []            # joined with spaces into one shell command
+
+[countdown]
+# time = "2027-01-01"
+# title = "New year"
+show_millis = false
+continue_on_zero = false
+reverse = false
+```
+
+A broken file or a wrong value produces a warning on stderr and the default is used.
+
+## Differences from the Rust clock-tui
+
+- Flags that took several values now repeat instead: `-d 25m -d 5m`, `-t Work -t Break`.
+- `--execute` takes one quoted shell string instead of a list of words.
+- The config file lives in the platform-native location listed above rather than always
+  in `~/.config/tclock/`.
+- `tclock timer` without `-d` uses the `[timer] durations` from the config file
+  (`25m`, `5m` by default) instead of a fixed `5m`.
+- `tclock countdown` without `--time` falls back to `[countdown] time` in the config file.
+- `Ctrl+C` quits. In the Rust binary it switches to clock mode, because its key matcher
+  ignores the Ctrl modifier (so `Ctrl+Q`, `Ctrl+W` and `Ctrl+T` also act like the plain
+  letters there).
+- Mode keys work from every mode. In the Rust binary a widget, once created, stays in a
+  fixed priority order (clock > timer > stopwatch > countdown), so e.g. `t` from the
+  clock has no visible effect and `w` from a timer keeps showing the timer.
+- The `?` help overlay and the auto-hiding key bar are additions.
+
+## Development
+
+```shell
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy src
+uv run tclock
+```
+
+## Releasing
+
+Releases are automated with GitHub Actions:
+
+1. In the Actions tab run **Release** and choose `patch`, `minor`, `major`, `rc` or
+   `stable`. The workflow runs `uv version --bump`, commits `chore: release vX.Y.Z` to
+   `main` and pushes the tag `vX.Y.Z`.
+2. The tag triggers **Publish**, which builds the sdist and wheel and uploads them to PyPI
+   with [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+One-time setup: on pypi.org add a trusted publisher for this repository with workflow
+`publish.yml` and environment `pypi`, and create a `pypi` environment in the GitHub repo
+settings. If `main` is branch-protected, give the Release workflow a token that may push
+to it (a PAT stored as a secret, or a ruleset bypass for GitHub Actions).
+
+## License
+
+MIT. Original clock-tui by Race604, also MIT.

tclock-0.1.2/README.md

@@ -0,0 +1,167 @@
+# tclock
+
+A clock, timer, stopwatch and countdown for your terminal, drawn with big block digits.
+Built with [Textual](https://textual.textualize.io/). A Python port of
+[race604/clock-tui](https://github.com/race604/clock-tui).
+
+Works on Linux, macOS and Windows. Requires Python 3.14 or newer.
+
+## Install
+
+```shell
+uv tool install tclock
+# or
+pipx install tclock
+# or
+pip install tclock
+```
+
+## Usage
+
+```shell
+tclock                 # clock (default mode)
+tclock clock -z Asia/Tokyo -D      # another timezone, no date line
+tclock timer -d 25m -d 5m -t Work -t Break -r
+tclock stopwatch
+tclock countdown -t 2027-01-01 -T "New year"
+tclock -c '#e63946' -s 2           # colour and size apply to every mode
+```
+
+Keys while running:
+
+| Key              | Action                                 |
+|------------------|----------------------------------------|
+| `q`, `Ctrl+C`    | quit                                   |
+| `Space`          | pause / resume (timer and stopwatch)   |
+| `c`              | switch to clock                        |
+| `w`              | switch to stopwatch                    |
+| `t`              | switch to timer (defaults from config) |
+| `?`              | show / hide the key overlay            |
+
+A key bar with the same bindings appears along the bottom whenever you touch the keyboard
+or mouse and fades out after a few seconds, so the clock stays clean at rest.
+
+Run `tclock --help` or `tclock <mode> --help` for every flag.
+
+### Clock
+
+`tclock clock [-z TZ] [-D] [-S] [-m]` shows the current time. `-z` takes an IANA zone such
+as `Europe/Oslo`. `-D` hides the date, `-S` hides seconds, `-m` shows tenths of a second.
+
+### Timer
+
+`tclock timer -d 5m` counts down five minutes. Durations are a number plus `s`, `m`, `h`
+or `d`. Repeat `-d` to run several durations in sequence and `-t` to title each of them.
+`-r` repeats the sequence, `-P` starts paused, `-Q` quits when time is up, `-M` hides
+tenths.
+
+`-e` runs a shell command when the timer ends and shows its result in the footer:
+
+```shell
+tclock timer -d 25m -e 'notify-send tclock "Time is up"'      # Linux
+tclock timer -d 25m -e 'osascript -e "display notification \"Time is up\""'   # macOS
+tclock timer -d 25m -e 'msg * Time is up'                       # Windows
+```
+
+When the timer runs out the screen flashes green until you quit or switch mode.
+
+### Stopwatch
+
+`tclock stopwatch` counts up. Press `Space` to pause. The final time is printed to the
+terminal after you quit.
+
+### Countdown
+
+`tclock countdown -t WHEN [-T TITLE] [-c] [-r] [-m]` shows the time until `WHEN`, which
+can be `20:00`, `20:00:00` (today), `2027-01-01` (midnight), `2026-12-25 20:00:00` (local
+time) or RFC 3339 such as `2026-12-25T20:00:00-04:00`. `-c` keeps counting (negative)
+after the moment has passed instead of blinking `0:00`; `-r` counts up since the moment.
+
+## Configuration
+
+tclock reads an optional TOML file:
+
+| OS      | Path                                                        |
+|---------|-------------------------------------------------------------|
+| Linux   | `~/.config/tclock/config.toml` (honours `$XDG_CONFIG_HOME`) |
+| macOS   | `~/Library/Application Support/tclock/config.toml`          |
+| Windows | `%APPDATA%\tclock\config.toml`                              |
+
+Command-line flags override the file; the file overrides built-in defaults. Every key is
+optional. The full schema, with the built-in defaults:
+
+```toml
+[default]
+mode = "clock"          # clock, timer, stopwatch or countdown when no mode is given
+color = "green"
+size = 1
+
+[clock]
+show_date = true
+show_seconds = true
+show_millis = false
+# timezone = "Europe/Oslo"
+
+[timer]
+durations = ["25m", "5m"]
+titles = []
+repeat = false
+show_millis = true
+start_paused = false
+auto_quit = false
+execute = []            # joined with spaces into one shell command
+
+[countdown]
+# time = "2027-01-01"
+# title = "New year"
+show_millis = false
+continue_on_zero = false
+reverse = false
+```
+
+A broken file or a wrong value produces a warning on stderr and the default is used.
+
+## Differences from the Rust clock-tui
+
+- Flags that took several values now repeat instead: `-d 25m -d 5m`, `-t Work -t Break`.
+- `--execute` takes one quoted shell string instead of a list of words.
+- The config file lives in the platform-native location listed above rather than always
+  in `~/.config/tclock/`.
+- `tclock timer` without `-d` uses the `[timer] durations` from the config file
+  (`25m`, `5m` by default) instead of a fixed `5m`.
+- `tclock countdown` without `--time` falls back to `[countdown] time` in the config file.
+- `Ctrl+C` quits. In the Rust binary it switches to clock mode, because its key matcher
+  ignores the Ctrl modifier (so `Ctrl+Q`, `Ctrl+W` and `Ctrl+T` also act like the plain
+  letters there).
+- Mode keys work from every mode. In the Rust binary a widget, once created, stays in a
+  fixed priority order (clock > timer > stopwatch > countdown), so e.g. `t` from the
+  clock has no visible effect and `w` from a timer keeps showing the timer.
+- The `?` help overlay and the auto-hiding key bar are additions.
+
+## Development
+
+```shell
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy src
+uv run tclock
+```
+
+## Releasing
+
+Releases are automated with GitHub Actions:
+
+1. In the Actions tab run **Release** and choose `patch`, `minor`, `major`, `rc` or
+   `stable`. The workflow runs `uv version --bump`, commits `chore: release vX.Y.Z` to
+   `main` and pushes the tag `vX.Y.Z`.
+2. The tag triggers **Publish**, which builds the sdist and wheel and uploads them to PyPI
+   with [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+One-time setup: on pypi.org add a trusted publisher for this repository with workflow
+`publish.yml` and environment `pypi`, and create a `pypi` environment in the GitHub repo
+settings. If `main` is branch-protected, give the Release workflow a token that may push
+to it (a PAT stored as a secret, or a ruleset bypass for GitHub Actions).
+
+## License
+
+MIT. Original clock-tui by Race604, also MIT.

tclock-0.1.2/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "tclock"
+version = "0.1.2"
+description = "A clock, timer, stopwatch and countdown for your terminal, built with Textual"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = [
+    "clock",
+    "timer",
+    "stopwatch",
+    "countdown",
+    "tui",
+    "textual",
+    "terminal",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=8.0",
+    "typer>=0.15",
+    "platformdirs>=4.0",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[[project.authors]]
+name = "Eivind Teig"
+email = "eivind.teig@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/eivl/tclock"
+Repository = "https://github.com/eivl/tclock"
+Issues = "https://github.com/eivl/tclock/issues"
+Original = "https://github.com/race604/clock-tui"
+
+[project.scripts]
+tclock = "tclock.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

tclock-0.1.2/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[project]
+name = "tclock"
+version = "0.1.2"
+description = "A clock, timer, stopwatch and countdown for your terminal, built with Textual"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Eivind Teig", email = "eivind.teig@gmail.com" }]
+requires-python = ">=3.14"
+keywords = ["clock", "timer", "stopwatch", "countdown", "tui", "textual", "terminal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=8.0",
+    "typer>=0.15",
+    "platformdirs>=4.0",
+    "tzdata; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/eivl/tclock"
+Repository = "https://github.com/eivl/tclock"
+Issues = "https://github.com/eivl/tclock/issues"
+Original = "https://github.com/race604/clock-tui"
+
+[project.scripts]
+tclock = "tclock.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true

tclock-0.1.2/src/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-0.1.2/src/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;
+}