pypomodo 0.3.1__tar.gz

pypomodo-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Davidson (WulfAlpha)
+
+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.

pypomodo-0.3.1/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: pypomodo
+Version: 0.3.1
+Summary: A terminal-first Pomodoro timer in the Unix tradition, with named timers, routines, and event hooks
+Keywords: pomodoro,timer,countdown,cli,terminal
+Author: Andrew Davidson
+Author-email: Andrew Davidson <drace.davidson@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 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/wulfalpha/pypomo
+Project-URL: Issues, https://github.com/wulfalpha/pypomo/issues
+Project-URL: Changelog, https://github.com/wulfalpha/pypomo/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# pypomo
+
+A terminal-first Pomodoro timer in the Unix tradition. pypomo keeps time well:
+durations, named timers, finite Pomodoro routines, pause and resume, and clean
+output for terminals and pipes. Notifications, sounds, and logging are left to
+the tools you already use, through [event hooks](#hooks) and
+[JSON lines output](#json-lines-output).
+Requires Python 3.12 or newer; no runtime dependencies.
+
+Licensed under the [MIT License](LICENSE). See the [changelog](CHANGELOG.md)
+for what changed in each release.
+
+Install from PyPI with uv or pipx. The package is named `pypomodo`; the command
+is `pypomo`:
+
+```bash
+uv tool install pypomodo
+pipx install pypomodo
+```
+
+Or install from a checkout with `pip install .`, or run with `uv run pypomo`.
+
+```bash
+pypomo 15m
+pypomo 30s
+pypomo 2h
+pypomo 1h30m15s
+pypomo 1h 30m
+pypomo pomo
+pypomo --list
+```
+
+Durations use positive whole-number totals with `d`, `h`, `m`, and `s`
+(days, hours, minutes, seconds). Compound units must appear in that order
+without repeats. Values such as `90m` and `36h` are valid. Countdowns always
+display as `HH:MM:SS`, so `2d` shows `48:00:00`. Each duration is limited to
+365 days (`365d`), including durations in config files.
+Spaces may separate units, with or without quotes: `pypomo 1h 30m` and
+`pypomo "1h 30m"` both equal `1h30m`, and config durations such as
+`"1h 30m"` work too. Spaces are allowed only between units (`5 m` is rejected),
+and tabs or other whitespace are not accepted.
+
+In a terminal, the timer name and `HH:MM:SS` countdown update on a single line:
+`pomo · 00:24:59 remaining`. Completion or cancellation replaces that line,
+then ends it with a newline so your shell prompt starts cleanly. Completion
+also rings the terminal bell.
+Use `--silent` to suppress the bell while keeping the countdown visible.
+
+Redirected output contains separate start and completion (or cancellation)
+lines without terminal control characters. Use `--live` to force in-place
+updates through a pipe, for example `pypomo 5m --live | lolcat`. The receiving
+program must support terminal control sequences and flush output promptly.
+Ctrl+C cancels the timer with exit status 130. Invalid input exits with status 2.
+On POSIX systems, SIGTERM and SIGHUP also cancel the timer, with exit statuses
+143 and 129 respectively. On Windows, Ctrl+Break cancels the same way, with
+exit status 149. A broken output pipe exits quietly with status 141.
+If stdout is unavailable, the timer runs silently to its deadline.
+
+## Pausing
+
+While a timer runs in a terminal, press `p` (or Space) to pause and `p` again
+to resume; the paused time is added back to the timer. Press `q` to cancel,
+exactly like Ctrl+C. Keys work whenever standard input is the terminal and
+pypomo is the foreground job, including with redirected output, where the log
+gains `paused at …` and `resumed at …` lines. Keys are read immediately and are
+not echoed; the terminal's normal input mode is restored on exit.
+
+The timer uses a monotonic clock, so changing the system clock does not change
+the countdown. Ctrl+Z does not pause it: stopped process time still counts.
+Use `p` to pause.
+Laptop-suspend behavior depends on the platform's monotonic clock; pypomo does
+not currently normalize it or guarantee that suspended time counts. Ordinary
+sleep overshoot does not accumulate into display drift, though long scheduling
+stalls can still skip displayed seconds.
+
+## Configuration
+
+Create `~/.config/pypomo/config.toml` (or `$XDG_CONFIG_HOME/pypomo/config.toml`
+when set).
+Relative `XDG_CONFIG_HOME` values are ignored. On Windows the default remains
+`%USERPROFILE%\.config\pypomo`. UTF-8 files with or without a BOM are accepted.
+TOML supports comments and sections:
+
+```toml
+default_units = "minutes"
+
+[timers]
+break = "15m"
+lunch = "30m"
+deep-work = "1h30m"
+
+[pretty]
+enabled = false # Use --pretty to enable for a single run
+
+[pretty.bar]
+enabled = true
+width = 20
+filled = "█"
+empty = "░"
+
+[pretty.colors]
+enabled = true
+label = "cyan"
+remaining = "white"
+bar = "green"
+complete = "green"
+cancelled = "yellow"
+paused = "yellow"   # paused and ready-to-start lines
+```
+
+Existing `config.json` files remain supported with the same settings as nested
+JSON objects. If both files exist, `config.toml` takes precedence; files are not
+merged. Use `--config PATH` to explicitly select a `.toml` or `.json` file.
+An invalid TOML config reports an error rather than silently falling back to JSON.
+
+With this config, `pypomo 15` means 15 minutes, `pypomo break` means 15 minutes,
+and `pypomo pomo` runs the default Pomodoro routine. Explicit units always take precedence.
+`default_units` accepts `seconds`, `minutes`, `hours`, `days`, or `s`, `m`, `h`, `d`.
+Without it, bare numbers are rejected. Configured durations are strings and
+use the same syntax and defaults as CLI durations.
+
+Names are case-sensitive, start with a letter, and contain only letters,
+digits, underscores, or hyphens. Missing settings retain built-in defaults.
+No config is required; an explicitly selected config must exist.
+`pomo` is reserved for the default Pomodoro routine. For a single focus timer,
+use `pypomo 25m` or define a timer named `focus`.
+
+## Pomodoro routines
+
+`pypomo pomo` runs four 25-minute focus sessions, with 5-minute short breaks
+between them and a 15-minute long break after the last focus session. Phases
+advance automatically by default; the routine finishes after the long break
+rather than repeating indefinitely. Ctrl+C or `q` cancels the entire routine.
+
+To wait for you between phases, set `auto_start = false` or pass
+`--no-auto-start` (`--auto-start` overrides a config that disables it). After
+each phase ends, the display shows `sprint.pomo · short break 1/3 · ready ·
+press Enter to start`, and the next phase begins when you press Enter. Waiting
+time does not count against the next phase; `q` or Ctrl+C cancels instead.
+Without a terminal keyboard, pypomo reads a line from standard input instead,
+and starts immediately if standard input is closed or exhausted, so unattended
+runs never block. The flags have no effect on single timers.
+
+Customize the default or add named routines in your config:
+
+```toml
+[pomo]
+focus = "25m"
+short_break = "5m"
+long_break = "15m"
+rounds = 4
+auto_start = true   # false: wait for Enter before each phase after the first
+
+[pomodoros.sprint]
+focus = "15m"
+short_break = "3m"
+long_break = "10m"
+rounds = 3
+```
+
+```bash
+pypomo pomo --pretty
+pypomo sprint.pomo --pretty
+pypomo --list
+```
+
+`rounds` is a positive integer counting focus sessions. `auto_start` is a boolean. A one-round routine
+has one focus session followed by a long break, with no short break.
+The maximum is 1,000 focus rounds per routine.
+Durations must be positive strings, using the same duration syntax and
+`default_units` as ordinary timers. Omitted default settings use built-in
+values; custom routines inherit omitted settings from the configured `[pomo]`.
+Routine names follow the same naming rules as timers. A timer `sprint` and a
+routine `sprint.pomo` can coexist.
+
+The display includes the routine name, phase and round, such as
+`sprint.pomo · focus 1/3`. Live output stays on one line across phase changes;
+the progress bar measures the current phase and resets at each transition.
+The terminal bell rings when each phase ends. Redirected output records the
+start and completion of each phase on separate lines.
+
+Preview a routine's phases and total duration without starting it:
+
+```bash
+pypomo pomo --preview
+pypomo sprint.pomo --preview
+pypomo 1h30m --preview
+```
+
+The total includes all focus sessions and breaks, including the final long
+break. The built-in routine totals `02:10:00`. A final line estimates the local
+end time if the timer started now, such as `Ends: 14:35 if started now`, dated
+when it falls on a later day. It does not account for pauses, and routines that
+wait between phases say so. `--auto-start` and `--no-auto-start` apply to the
+preview. `--preview` also supports named
+timers and explicit durations. It cannot be combined with `--list`.
+`--silent` suppresses bells for every phase of a running routine.
+
+For compatibility, a legacy `[timers] pomo = "25m"` setting (or its JSON
+equivalent) supplies the default routine's focus duration. An explicit
+`[pomo] focus` takes precedence. **The `pomo` command now runs a complete
+routine, even with a legacy config**, rather than a single focus timer.
+JSON supports the same structure using `pomo` and `pomodoros` objects.
+
+## Pretty output
+
+```bash
+pypomo pomo --pretty
+pypomo pomo --no-pretty
+pypomo 5m --pretty --live
+```
+
+`--pretty` enables the configured bar and theme; `--no-pretty` overrides
+`pretty.enabled = true`. Without a flag, the config decides (default: false).
+The progress bar fills as time elapses and remains visible on completion or
+cancellation. Disable `pretty.bar.enabled` for colors only, or disable
+`pretty.colors.enabled` for a bar without colors. Disable both to retain plain
+text. Each styled segment resets its color so it does not affect the shell prompt.
+
+Bar width is 1–80 characters. Filled and empty glyphs must each be a single
+narrow printable character (for example `#` and `-`, or `█` and `░`); spaces
+are allowed, but emoji, wide characters, combining marks and control characters
+are rejected. The bar shrinks or disappears when the terminal is narrow;
+long labels are truncated to preserve the status, and extremely narrow displays
+truncate the status as well. Available colors are
+`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and `default`
+(the terminal's default foreground). Actual shades follow your terminal palette.
+
+Styling applies to terminal output or output forced live with `--live`.
+Redirected output remains plain without `--live`, even with `--pretty`.
+For coloring with an external program, use `pypomo 5m --live | lolcat`;
+add `--no-pretty` if styling is enabled in your config.
+
+A nonempty `NO_COLOR` disables colors while preserving the progress bar.
+`TERM=dumb` uses plain start/end lines, including when `--live` is supplied.
+Output uses readable ASCII separators and bar glyphs when the stream's encoding
+cannot represent the configured characters. Other unencodable text is escaped.
+Live rendering requires a terminal that understands ANSI control sequences.
+
+## Hooks
+
+pypomo does the timing and leaves notifications, sounds, and logging to other
+programs. A hook is a command run when a timer event happens:
+
+```toml
+[hooks]
+end = ["notify-send", "pypomo", "Time is up"]
+pause = "playerctl pause"
+resume = "playerctl play"
+any = 'echo "$(date -Is) $PYPOMO_EVENT $PYPOMO_LABEL" >> ~/.local/state/pomodoro.log'
+```
+
+Events are `start`, `end`, `pause`, `resume`, `cancel`, and `wait`; an `any`
+hook runs for every event, after the event's own hook. Each phase of a routine
+has its own `start` and `end`. `wait` happens when a routine with
+`auto_start = false` begins waiting for Enter before a phase, so a hook can say
+"break ready". Quitting while waiting sends `cancel` for that phase.
+A list runs the program directly; a string runs through the system shell
+(`sh` on POSIX, `cmd` on Windows), so shell variables, pipes, and redirection work.
+Add hooks for a single run with `--hook CMD` (repeatable, shell syntax,
+equivalent to an extra `any` hook), or ignore configured hooks with `--no-hooks`.
+
+| Variable | Value |
+| --- | --- |
+| `PYPOMO_EVENT` | `start`, `end`, `pause`, `resume`, `cancel`, or `wait` |
+| `PYPOMO_TIMER` | the timer as given: `25m`, `tea`, `sprint.pomo` |
+| `PYPOMO_LABEL` | the displayed label: `sprint.pomo · focus 1/3` |
+| `PYPOMO_PHASE` | `timer`, `focus`, `short_break`, or `long_break` |
+| `PYPOMO_ROUND`, `PYPOMO_ROUNDS` | round and total rounds; empty for single timers |
+| `PYPOMO_DURATION` | the timer or phase length in seconds |
+| `PYPOMO_REMAINING` | whole seconds left (`0` at `end`) |
+| `PYPOMO_LAST` | `1` for a single timer or a routine's final phase, else `0` |
+
+Hooks never affect the timer. pypomo starts them in the background without
+waiting, so a slow hook does not delay the countdown, and hooks for consecutive
+events may overlap. A hook's exit status is ignored. A command that cannot be
+started produces one warning on stderr and the timer continues. Hooks receive no
+standard input and their standard output is discarded, keeping pypomo's output
+clean for pipes; standard error stays connected so failures are visible. Each
+hook runs in its own session or process group, so Ctrl+C or closing the
+terminal does not interrupt a hook that is already running.
+`--preview` and `--list` never run hooks.
+
+Example: a desktop notification only when a whole routine finishes:
+
+```bash
+pypomo pomo --hook '[ "$PYPOMO_EVENT" = end ] && [ "$PYPOMO_LAST" = 1 ] && notify-send "Routine done"'
+```
+
+## JSON lines output
+
+`--format jsonl` replaces the countdown display with one JSON object per event
+on standard output, for `jq`, scripts, and logs:
+
+```bash
+pypomo pomo --format jsonl | jq -r '"\(.time) \(.event) \(.label)"'
+pypomo pomo --format jsonl >> ~/.local/state/pomodoro.jsonl
+```
+
+```json
+{"event": "end", "timer": "pomo", "label": "pomo \u00b7 focus 1/4", "phase": "focus", "round": 1, "rounds": 4, "duration": 1500, "remaining": 0, "last": false, "time": "2026-11-07T14:25:00-05:00"}
+```
+
+Events and fields match the [hook variables](#hooks), plus `time`, the local
+time with its UTC offset. `round` and `rounds` are `null` for single timers.
+Each line is written and flushed as the event happens, and the output is ASCII
+(other characters use JSON escapes), so it is valid in any locale.
+Nothing else is written to standard output: no countdown, prompts, or bell.
+Pause keys still work, and their events appear in the stream; a routine that
+waits between phases emits `wait` and starts on Enter (or a line of input).
+Hooks run alongside JSON output. The text display remains the default
+(`--format text`). `--format jsonl` cannot be combined with `--list`,
+`--preview`, or `--live`. Exit statuses are unchanged, so a stream that ends
+in `cancel` is followed by exit status 130.
+
+## Development
+
+```bash
+uv sync                      # create .venv with pypomo (editable) and ruff
+uv run python -m unittest discover -s tests -v
+uv run pypomo 1s
+uv run ruff check src tests
+```
+
+Without uv, the tests need no dependencies:
+`PYTHONPATH=src python -m unittest discover -s tests -v`.
+
+## Releasing
+
+The package is named `pypomodo` on PyPI (`pypomo` was too similar to an
+existing project); the command and the Python package remain `pypomo`.
+To release, bump `version` in `pyproject.toml`, date the changelog section,
+merge, then tag the merge commit and push the tag:
+
+```bash
+git tag -a v0.4.0 -m "pypomo 0.4.0" && git push origin v0.4.0
+```
+
+The `Publish` workflow checks that the tag matches the package version, builds
+and tests the wheel, and uploads it to PyPI with trusted publishing from the
+`pypi` environment. No API token is stored in the repository.
+
+## Continuous integration
+
+GitHub Actions runs on pushes to `main` and on pull requests, with a manual run
+option. It tests Python 3.12 and 3.15 on Linux, macOS, and Windows, and 3.13 and
+3.14 on Linux. Each job lints the code, builds the source distribution and
+wheel, installs the wheel, runs the test suite against the installed package,
+and checks `pypomo --help`, `pypomo --list`, and a one-second timer.
+Linux PTY tests cover live output, Ctrl+C, pause/resume keys, and waiting between phases; POSIX signal tests run on Linux and
+macOS. Encoding tests run on every platform. Terminal appearance and interactive
+Windows console behavior still benefit from manual testing.