termdown 2.0.0__tar.gz → 2.0.1__tar.gz

{termdown-2.0.0 → termdown-2.0.1}/CHANGELOG.md

@@ -1,3 +1,33 @@
+# 2.0.1
+
+2026-11-07
+
+* fixed unknown font names silently falling back to a different font
+* fixed font path missing from TTF/OTF loading error
+* fixed display lagging behind when holding down keys (#107)
+* fixed stopwatch going negative when reset while paused (#109)
+* fixed stopwatch going negative when taking a lap while paused
+* fixed stopwatch total including paused time when quitting while paused
+* fixed countdown ending up to a second late after pausing or resetting
+* fixed clock updating late after pausing
+* fixed time paused before a reset being added to the countdown when unpausing
+* fixed countdown restarting paused when it reached zero while paused
+* fixed countdown announcing 4/9/29 minutes instead of 5/10/30
+* fixed `--exec-cmd` receiving fractional seconds as `{0}`
+* fixed announcements and `--exec-cmd` repeating on keypresses
+* fixed random fonts (e.g. `-f random`) being rejected, they're now picked once at startup
+* fixed non-ASCII characters in `--title` not being replaced
+* fixed durations like `1h30` silently ignoring everything after the first match
+* fixed past dates without a year (e.g. `5th 10:00`) being moved by one day
+* fixed past times being moved to tomorrow off by an hour across DST changes
+* fixed unparseable TIME crashing with a traceback instead of showing an error
+* fixed `--quit-after` in stopwatch mode restarting with every lap
+* fixed `--quit-after` quitting up to a second late in clock and stopwatch mode
+* fixed blank space around ASCII art requiring a larger terminal than necessary (#84)
+* fixed `--outfile` not containing the final time after quitting stopwatch mode (#60)
+* fixed invalid options (e.g. existing `--outfile` or broken font files) crashing with a traceback instead of showing an error
+
+
 # 2.0.0
 
 2026-01-31

{termdown-2.0.0 → termdown-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: termdown
-Version: 2.0.0
+Version: 2.0.1
 Summary: Countdown timer for your terminal
 Project-URL: Homepage, https://github.com/trehn/termdown
 Project-URL: Repository, https://github.com/trehn/termdown

{termdown-2.0.0 → termdown-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "termdown"
-version = "2.0.0"
+version = "2.0.1"
 description = "Countdown timer for your terminal"
 readme = "README.md"
 license = "GPL-3.0-only"

{termdown-2.0.0 → termdown-2.0.1}/termdown/cli.py

@@ -1,18 +1,29 @@
 import os
 from argparse import ArgumentParser, RawTextHelpFormatter
 from curses import wrapper
+from difflib import get_close_matches
 from functools import wraps
 from os.path import abspath, dirname
 from sys import stderr
 
+from art import FONT_NAMES
+from art.utils import indirect_font
+
 from . import VERSION
 from .modes import clock, countdown, stopwatch
+from .ttf import ttf_to_ascii
 from .ui import Ui
-from .utils import format_seconds, normalize_text
+from .utils import format_seconds, normalize_text, parse_timestr
 
 DEFAULT_FONT = "univers"
 DEFAULT_TIME_FORMAT = "%H:%M:%S"  # --no-seconds expects this to end with :%S
 DEFAULT_DATE_FORMAT = "%Y-%m-%d"
+# font names that make art pick a font at random
+RANDOM_FONTS = {
+    f"{prefix}{suffix}"
+    for prefix in ("random", "rand", "rnd")
+    for suffix in ("", "-small", "-medium", "-large", "-xlarge", "-na")
+} | {"wizard", "wiz", "magic"}
 
 
 def _escape_percent_for_argparse_help(text):
@@ -166,7 +177,7 @@ parser.add_argument(
 parser.add_argument(
     "--no-text-magic",
     action="store_true",
-    help="Don't try to replace non-ASCII characters (use with -t)",
+    help="Don't try to replace non-ASCII characters (use with -t/-T)",
 )
 parser.add_argument(
     "-z",
@@ -216,7 +227,40 @@ def curses_ui(stdscr, mode, args):
 def main():
     args = parser.parse_args()
     if args.exec_cmd and args.voice:  # prevent passing both --exec-cmd and --voice
-        raise RuntimeError("--exec-cmd and --voice are mutually exclusive")
+        parser.error("--exec-cmd and --voice are mutually exclusive")
+
+    if args.text and not args.no_text_magic:
+        args.text = normalize_text(args.text)
+    if args.title and not args.no_text_magic:
+        args.title = normalize_text(args.title)
+
+    if not args.no_art and os.path.exists(args.font):
+        try:
+            ttf_to_ascii("", args.font, args.font_size, args.font_charset)
+        except RuntimeError as exc:
+            parser.error(str(exc))
+    elif not args.no_art:
+        if args.font.lower() in RANDOM_FONTS:
+            # pick a font once, otherwise art would pick a new one on every redraw
+            args.font = indirect_font(
+                args.font.lower(),
+                "0123456789:dhmsy" + (args.title or "") + (args.text or ""),
+            )
+        # art silently falls back to the most similar font name, so check first
+        elif args.font.lower() not in FONT_NAMES:
+            message = f"unknown font: {args.font}"
+            suggestions = get_close_matches(args.font.lower(), FONT_NAMES)
+            if suggestions:
+                message += f" (did you mean: {', '.join(suggestions)}?)"
+            parser.error(message)
+
+    if args.timespec and not args.time:
+        # Check TIME before starting curses so we can show a proper error.
+        # countdown() parses it again since durations are relative to now.
+        try:
+            parse_timestr(args.timespec)
+        except ValueError as exc:
+            parser.error(str(exc))
 
     if args.time_format is None:
         args.time_format = (
@@ -227,12 +271,9 @@ def main():
 
     if args.outfile:
         if os.path.exists(args.outfile):
-            raise RuntimeError("File already exists: {}".format(args.outfile))
+            parser.error("file already exists: {}".format(args.outfile))
         if not os.access(dirname(abspath(args.outfile)), os.W_OK):
-            raise RuntimeError("Unable to write file: {}".format(args.outfile))
-
-    if args.text and not args.no_text_magic:
-        args.text = normalize_text(args.text)
+            parser.error("unable to write file: {}".format(args.outfile))
 
     args.voice_cmd = None
     if args.voice:

termdown-2.0.1/termdown/modes.py

@@ -0,0 +1,339 @@
+import os
+from curses import beep
+from datetime import datetime, timedelta, timezone
+from math import ceil
+from queue import Empty
+from subprocess import DEVNULL, STDOUT, Popen
+from sys import exit, stdout
+from threading import Timer
+from time import monotonic, time
+
+from .events import (
+    INPUT_END,
+    INPUT_EXIT,
+    INPUT_LAP,
+    INPUT_MINUS,
+    INPUT_PAUSE,
+    INPUT_PLUS,
+    INPUT_RESET,
+    TIME_TICK,
+)
+from .ticker import Metronome
+from .utils import (
+    format_seconds,
+    format_seconds_alt,
+    format_target,
+    parse_timestr,
+)
+
+
+def _wake_up_in(seconds, ui):
+    """
+    Makes sure the mode loop runs again after the given number of seconds,
+    if that is before the next regular tick.
+    """
+    if seconds < 1:
+        timer = Timer(seconds, ui.input_queue.put, (TIME_TICK,))
+        timer.daemon = True
+        timer.start()
+
+
+def countdown(ui, args):
+    target_time = parse_timestr(args.timespec)
+    # tick whenever the number of seconds left crosses a whole number
+    ticker = Metronome(ui.input_queue, offset=target_time.timestamp())
+    ticker.start()
+    last_announced = None
+
+    while True:  # Outer loop to allow restarting countdown from scratch
+        while True:  # Active countdown loop
+            seconds_left = (target_time - datetime.now(timezone.utc)).total_seconds()
+            if seconds_left <= 0:
+                # If seconds_left is zero or negative, immediately break to handle the
+                # "finished" state. This prevents displaying "0" for an entire second
+                # while waiting for the next tick.
+                break
+
+            if args.alt_format:
+                countdown_text = format_seconds_alt(
+                    seconds_left, hide_seconds=args.no_seconds
+                )
+            else:
+                countdown_text = format_seconds(
+                    seconds_left, hide_seconds=args.no_seconds
+                )
+
+            with ui.curses_lock:
+                ui.set_window_title(countdown_text)
+                if args.outfile:
+                    with open(args.outfile, "w") as f:
+                        f.write("{}\n{}\n".format(countdown_text, seconds_left))
+                end_text = (
+                    format_target(
+                        target_time,
+                        time_format=args.time_format,
+                        date_format=args.date_format,
+                    )
+                    if args.end
+                    else None
+                )
+                color = 0
+                if ticker.is_paused:
+                    color = 3
+                elif seconds_left <= args.critical:
+                    color = 1
+                ui.draw_text(countdown_text, color=color, end=end_text)
+
+            # the number of seconds as displayed
+            whole_seconds_left = int(ceil(seconds_left))
+            annunciation = None
+            if whole_seconds_left <= args.critical:
+                annunciation = str(whole_seconds_left)
+            elif whole_seconds_left in (5, 10, 20, 30, 60):
+                annunciation = "{} {} seconds".format(
+                    args.voice_prefix, whole_seconds_left
+                )
+            elif whole_seconds_left in (300, 600, 1800):
+                annunciation = "{} {} minutes".format(
+                    args.voice_prefix, whole_seconds_left // 60
+                )
+            elif whole_seconds_left == 3600:
+                annunciation = "{} one hour".format(args.voice_prefix)
+            # don't repeat ourselves when redrawing due to keypresses
+            if whole_seconds_left != last_announced:
+                last_announced = whole_seconds_left
+                if (
+                    annunciation and args.voice_cmd
+                ):  # Only announce if there is something to say
+                    Popen(
+                        [args.voice_cmd, "-v", args.voice, annunciation.strip()],
+                        stdout=DEVNULL,
+                        stderr=STDOUT,
+                    )
+                if args.exec_cmd:
+                    # Pass annunciation even if it's empty, format() handles it.
+                    Popen(
+                        args.exec_cmd.format(
+                            whole_seconds_left, annunciation or ""
+                        ),
+                        stdout=DEVNULL,
+                        stderr=STDOUT,
+                        shell=True,
+                    )
+
+            for input_action in ui.get_input_actions():
+                if input_action == INPUT_PAUSE:
+                    duration = ticker.pause()
+                    if duration:
+                        target_time += timedelta(seconds=duration)
+                        ticker.align(target_time.timestamp())
+                elif input_action == INPUT_EXIT:
+                    exit(1)
+                elif input_action == INPUT_RESET:
+                    target_time = parse_timestr(args.timespec)
+                    ticker.align(target_time.timestamp())
+                    # don't add time paused before the reset when unpausing
+                    ticker.restart_pause()
+                elif input_action == INPUT_PLUS:
+                    target_time += timedelta(seconds=10)
+                elif input_action == INPUT_MINUS:
+                    target_time -= timedelta(seconds=10)
+                elif input_action == INPUT_END:
+                    args.end = not args.end
+
+        # After the active countdown loop, handle the "time is up" state.
+
+        if not args.no_bell:
+            with ui.curses_lock:
+                beep()
+
+        if args.outfile:
+            with open(args.outfile, "w") as f:
+                f.write("{}\n{}\n".format(args.text if args.text else "DONE", 0))
+
+        if args.blink or args.text:
+            base_color = 1 if args.blink else 0
+            flip = True
+            if not ticker.is_paused:  # we might have reached zero while paused
+                ticker.pause()  # Pause ticker during blinking phase
+            while True:
+                if args.quit_after and (
+                    datetime.now(timezone.utc) - target_time
+                ).total_seconds() > float(args.quit_after):
+                    return
+                with ui.curses_lock:
+                    ui.set_window_title("/" if flip else "\\")
+                    if args.text:
+                        ui.draw_text(args.text, color=base_color if flip else 4)
+                    else:
+                        ui.draw_text("", color=base_color if flip else 4)
+                if args.blink:
+                    flip = not flip
+                try:
+                    input_action = ui.input_queue.get(True, 0.5)
+                except Empty:
+                    input_action = None
+                if input_action == INPUT_EXIT:
+                    return
+                elif input_action == INPUT_RESET:
+                    target_time = parse_timestr(args.timespec)
+                    ticker.align(target_time.timestamp())
+                    ticker.pause()  # resume
+                    break  # Break out of the blinking loop to restart the main countdown
+        else:
+            break
+
+
+def clock(ui, args):
+    time_started = monotonic()
+    seconds_elapsed = 0
+    offset = timedelta(0)
+    ticker = Metronome(ui.input_queue)
+    ticker.start()
+    while True:
+        seconds_elapsed = monotonic() - time_started
+        if args.quit_after:
+            seconds_until_quit = float(args.quit_after) - seconds_elapsed
+            if seconds_until_quit <= 0:
+                return
+            # ticks happen on full seconds of the clock, not since we started
+            _wake_up_in(seconds_until_quit, ui)
+        clock_text = (datetime.now() + offset).strftime(args.time_format)
+        with ui.curses_lock:
+            ui.set_window_title(clock_text)
+
+            if args.outfile:
+                with open(args.outfile, "w") as f:
+                    f.write("{}\n{}\n".format(clock_text, seconds_elapsed))
+
+            ui.draw_text(clock_text, color=3 if ticker.is_paused else 0)
+
+        for input_action in ui.get_input_actions():
+            if input_action == INPUT_EXIT:
+                return
+            if input_action == INPUT_PLUS:
+                offset += timedelta(seconds=10)
+            elif input_action == INPUT_MINUS:
+                offset -= timedelta(seconds=10)
+            elif input_action == INPUT_PAUSE:
+                ticker.pause()
+            elif input_action == INPUT_RESET:
+                offset = timedelta(0)
+
+
+def stopwatch(ui, args):
+    time_started = monotonic()
+    ticker = Metronome(ui.input_queue, offset=time() % 1.0)
+    ticker.start()
+    time_paused = None
+    seconds_elapsed = 0
+    last_announced = None
+    laps = []
+
+    def now():
+        # while paused, time stands still at the moment we paused
+        return monotonic() if time_paused is None else time_paused
+
+    def align_ticker():
+        # tick whenever the number of seconds elapsed crosses a whole number
+        ticker.align(time() - (now() - time_started))
+
+    def format_elapsed(seconds):
+        formatter = format_seconds_alt if args.alt_format else format_seconds
+        return formatter(round(seconds), hide_seconds=args.no_seconds)
+
+    def write_outfile(seconds):
+        if args.outfile:
+            with open(args.outfile, "w") as f:
+                f.write("{}\n{}\n".format(format_elapsed(seconds), seconds))
+
+    def finish(seconds):
+        # leave the final time in the outfile, not the one last displayed
+        write_outfile(seconds)
+        return seconds, laps
+
+    while True:
+        seconds_elapsed = now() - time_started
+
+        if args.quit_after:
+            # laps restart seconds_elapsed, but not the stopwatch as a whole
+            seconds_until_quit = float(args.quit_after) - sum(laps) - seconds_elapsed
+            if seconds_until_quit <= 0:
+                return finish(seconds_elapsed)
+            if not ticker.is_paused:
+                # after laps, ticks no longer line up with the total time
+                _wake_up_in(seconds_until_quit, ui)
+
+        stopwatch_text = format_elapsed(seconds_elapsed)
+        with ui.curses_lock:
+            if not args.no_window_title:
+                os.write(
+                    stdout.fileno(),
+                    "\033]2;{0}\007".format(stopwatch_text).encode(),
+                )
+            write_outfile(seconds_elapsed)
+            ui.draw_text(stopwatch_text, color=3 if ticker.is_paused else 0)
+
+        whole_seconds_elapsed = int(seconds_elapsed)
+        annunciation = None
+        if 1 <= whole_seconds_elapsed <= args.critical:
+            annunciation = str(whole_seconds_elapsed)
+        elif whole_seconds_elapsed in (5, 10, 20, 30, 40, 50, 60):
+            annunciation = "{} {} seconds".format(
+                args.voice_prefix, whole_seconds_elapsed
+            )
+        elif whole_seconds_elapsed in (120, 180, 300, 600, 1800):
+            annunciation = "{} {} minutes".format(
+                args.voice_prefix, whole_seconds_elapsed // 60
+            )
+        elif whole_seconds_elapsed == 3600:
+            annunciation = "{} one hour".format(args.voice_prefix)
+        elif whole_seconds_elapsed % 3600 == 0 and whole_seconds_elapsed > 0:
+            annunciation = "{} {} hours".format(
+                args.voice_prefix, whole_seconds_elapsed // 3600
+            )
+
+        # don't repeat ourselves when redrawing due to keypresses
+        if whole_seconds_elapsed != last_announced:
+            last_announced = whole_seconds_elapsed
+            if annunciation and args.voice_cmd:
+                Popen(
+                    [args.voice_cmd, "-v", args.voice, annunciation.strip()],
+                    stdout=DEVNULL,
+                    stderr=STDOUT,
+                )
+            if args.exec_cmd:
+                Popen(
+                    args.exec_cmd.format(whole_seconds_elapsed, annunciation or ""),
+                    stdout=DEVNULL,
+                    stderr=STDOUT,
+                    shell=True,
+                )
+
+        for input_action in ui.get_input_actions():
+            if input_action == INPUT_PLUS:
+                time_started -= 10
+            elif input_action == INPUT_MINUS:
+                time_started += 10
+            elif input_action == INPUT_PAUSE:
+                duration = ticker.pause()
+                if duration:  # unpaused
+                    time_started += duration
+                    time_paused = None
+                    align_ticker()
+                else:
+                    time_paused = monotonic()
+            elif input_action == INPUT_EXIT:
+                return finish(now() - time_started)
+            elif input_action == INPUT_RESET:
+                laps = []
+                # If paused, this rebases the start to the pause instant so the
+                # display resets to 0 instead of going negative by the time spent
+                # paused before the reset.
+                time_started = now()
+                align_ticker()
+            elif input_action == INPUT_LAP:
+                lap_time = now()
+                laps.append(lap_time - time_started)
+                time_started = lap_time
+                align_ticker()

termdown-2.0.1/termdown/ticker.py

@@ -0,0 +1,64 @@
+from threading import Event, Thread
+from time import monotonic, time
+
+from .events import TIME_TICK
+
+
+class Metronome:
+    """
+    Will put a TIME_TICK event into the given queue every second, at the
+    moments when the fractional part of time() equals offset.
+    """
+
+    def __init__(self, queue, offset=0.0):
+        self._offset = offset % 1.0
+        self._queue = queue
+        self._realigned = Event()
+        self._thread = Thread(target=self._run, daemon=True)
+        self._pause_time = None
+
+    def _run(self):
+        while True:
+            # Sleep until the next tick, plus a small margin so we never wake
+            # up just before it (which would e.g. make a countdown display the
+            # previous second for another full second).
+            sleep_time = (self._offset - time()) % 1.0 + 0.002
+            if self._realigned.wait(sleep_time):
+                # offset changed while we were sleeping, start over
+                self._realigned.clear()
+                continue
+            if not self.is_paused:
+                self._queue.put(TIME_TICK)
+
+    def start(self):
+        self._thread.start()
+
+    def align(self, offset):
+        """
+        Make future ticks happen when the fractional part of time() equals
+        offset.
+        """
+        self._offset = offset % 1.0
+        self._realigned.set()
+
+    def pause(self):
+        """
+        Toggles pause. Returns the duration of the pause when unpausing.
+        """
+        if self.is_paused:  # unpause
+            duration = monotonic() - self._pause_time
+            self._pause_time = None
+            return duration
+        else:  # pause
+            self._pause_time = monotonic()
+
+    def restart_pause(self):
+        """
+        If paused, forget about the time spent paused so far.
+        """
+        if self.is_paused:
+            self._pause_time = monotonic()
+
+    @property
+    def is_paused(self):
+        return self._pause_time is not None

{termdown-2.0.0 → termdown-2.0.1}/termdown/ttf.py

@@ -5,7 +5,7 @@ def ttf_to_ascii(text, font_path, font_size, char_set):
     try:
         font = ImageFont.truetype(font_path, font_size)
     except IOError:
-        raise RuntimeError("Error: Could not load font from {font_path}")
+        raise RuntimeError(f"could not load font from {font_path}")
 
     # Figure out text dimensions
     dummy_img = Image.new("L", (1, 1))

{termdown-2.0.0 → termdown-2.0.1}/termdown/ui.py

@@ -1,6 +1,6 @@
 import curses
 import os
-from queue import Queue
+from queue import Empty, Queue
 from sys import stdout
 from threading import Lock, Thread
 from time import sleep
@@ -17,7 +17,7 @@ from .events import (
     INPUT_RESET,
 )
 from .ttf import ttf_to_ascii
-from .utils import pad_to_size
+from .utils import pad_to_size, trim_block
 
 
 class Ui:
@@ -70,6 +70,11 @@ class Ui:
                 art_title = text2art(title, font=self._args.font)
                 art_text = text2art(text, font=self._args.font)
                 art_end = text2art(end, font=self._args.font)
+            # fonts often add blank space around the text, which would make us
+            # fall back to smaller variants earlier than necessary
+            art_title = trim_block(art_title)
+            art_text = trim_block(art_text)
+            art_end = trim_block(art_end)
             variants = [
                 (art_title + "\n\n\n\n" + art_text + "\n\n\n\n" + art_end).strip("\n"),
                 (art_title + "\n\n" + art_text + "\n\n" + art_end).strip("\n"),
@@ -79,6 +84,14 @@ class Ui:
 
         y, x = self.stdscr.getmaxyx()
         for variant in variants:
+            variant_lines = variant.split("\n")
+            if (
+                len(variant_lines) > y
+                or max(len(line) for line in variant_lines) > x
+            ):
+                # insstr() silently truncates lines that are too wide,
+                # so we have to check ourselves whether this variant fits
+                continue
             lines = pad_to_size(variant, x, y).rstrip("\n").split("\n")
             self.stdscr.erase()
             try:
@@ -106,23 +119,45 @@ class Ui:
 
     def _input_thread_body(self):
         while True:
-            try:
-                with self.curses_lock:
-                    key = self.stdscr.getkey()
-            except Exception:
-                key = None
-            if key in ("q", "Q"):
-                self.input_queue.put(INPUT_EXIT)
-            elif key == " ":
-                self.input_queue.put(INPUT_PAUSE)
-            elif key in ("e", "E"):
-                self.input_queue.put(INPUT_END)
-            elif key in ("r", "R"):
-                self.input_queue.put(INPUT_RESET)
-            elif key in ("l", "L"):
-                self.input_queue.put(INPUT_LAP)
-            elif key == "+":
-                self.input_queue.put(INPUT_PLUS)
-            elif key == "-":
-                self.input_queue.put(INPUT_MINUS)
+            keys = []
+            with self.curses_lock:
+                # Read every pending key at once so held keys (autorepeat)
+                # don't pile up in the terminal's input buffer.
+                while True:
+                    try:
+                        keys.append(self.stdscr.getkey())
+                    except Exception:
+                        break
+            for key in keys:
+                self._handle_key(key)
             sleep(0.01)
+
+    def get_input_actions(self):
+        """
+        Blocks until at least one input action is available, then returns it
+        along with all other actions that are already queued. This lets the
+        caller apply a burst of events (e.g. from holding down a key) before
+        redrawing just once.
+        """
+        actions = [self.input_queue.get()]
+        while True:
+            try:
+                actions.append(self.input_queue.get_nowait())
+            except Empty:
+                return actions
+
+    def _handle_key(self, key):
+        if key in ("q", "Q"):
+            self.input_queue.put(INPUT_EXIT)
+        elif key == " ":
+            self.input_queue.put(INPUT_PAUSE)
+        elif key in ("e", "E"):
+            self.input_queue.put(INPUT_END)
+        elif key in ("r", "R"):
+            self.input_queue.put(INPUT_RESET)
+        elif key in ("l", "L"):
+            self.input_queue.put(INPUT_LAP)
+        elif key == "+":
+            self.input_queue.put(INPUT_PLUS)
+        elif key == "-":
+            self.input_queue.put(INPUT_MINUS)

{termdown-2.0.0 → termdown-2.0.1}/termdown/utils.py

@@ -16,17 +16,11 @@ NORMALIZE_TEXT_MAP = {
     "ß": "ss",
 }
 TIMEDELTA_REGEX = re.compile(
-    r"((?P<years>\d+)y ?)?"
-    r"((?P<days>\d+)d ?)?"
-    r"((?P<hours>\d+)h ?)?"
-    r"((?P<minutes>\d+)m ?)?"
-    r"((?P<seconds>\d+)s ?)?"
-)
-DATE_COMPONENT_REGEX = re.compile(
-    r"\d{4}|"  # year
-    r"jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|"
-    r"\d{1,2}[/\-]\d{1,2}",  # day/month with separator
-    re.IGNORECASE,
+    r"((?P<years>\d+)y\s*)?"
+    r"((?P<days>\d+)d\s*)?"
+    r"((?P<hours>\d+)h\s*)?"
+    r"((?P<minutes>\d+)m\s*)?"
+    r"((?P<seconds>\d+)s\s*)?"
 )
 
 
@@ -101,6 +95,23 @@ def normalize_text(input_str):
     )
 
 
+def trim_block(text):
+    """
+    Removes blank lines and columns around a block of text such as ASCII art.
+    All lines keep the same width so the block stays aligned when centered.
+    """
+    lines = [line.rstrip() for line in text.split("\n")]
+    while lines and not lines[0]:
+        lines.pop(0)
+    while lines and not lines[-1]:
+        lines.pop()
+    if not lines:
+        return ""
+    indent = min(len(line) - len(line.lstrip()) for line in lines if line)
+    width = max(len(line) for line in lines) - indent
+    return "\n".join(line[indent:].ljust(width) for line in lines)
+
+
 def pad_to_size(text, x, y):
     """
     Adds whitespace to text to center it within a frame of the given
@@ -130,38 +141,68 @@ def parse_timestr(timestr):
     """
     timedelta_secs = parse_timedelta(timestr)
 
-    if timedelta_secs:
-        target = datetime.now(timezone.utc) + timedelta(seconds=timedelta_secs)
-    elif timestr.isdigit():
-        target = datetime.now(timezone.utc) + timedelta(seconds=int(timestr))
-    else:
-        try:
-            target = parse(timestr)
-        except Exception:
-            # unfortunately, dateutil doesn't raise the best exceptions
-            raise ValueError("Unable to parse '{}'".format(timestr))
-        if target.tzinfo is None:
-            target = target.replace(tzinfo=tz.tzlocal())
-        target = target.astimezone(timezone.utc)
-
-        if (
-            target <= datetime.now(timezone.utc) and
-            not DATE_COMPONENT_REGEX.search(timestr)
+    if timedelta_secs is not None:
+        return datetime.now(timezone.utc) + timedelta(seconds=timedelta_secs)
+    if timestr.isdigit():
+        return datetime.now(timezone.utc) + timedelta(seconds=int(timestr))
+
+    today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+    try:
+        target = _parse_datetime(timestr, today)
+        if target <= datetime.now(timezone.utc) and not _contains_date(
+            timestr, today, target
         ):
             # User only gave us a time and it's in the past - probably
             # means that time tomorrow.
-            target += timedelta(days=1)
+            target = _parse_datetime(timestr, today + timedelta(days=1))
+    except Exception:
+        # unfortunately, dateutil doesn't raise the best exceptions
+        raise ValueError("Unable to parse '{}'".format(timestr))
+    return target.astimezone(timezone.utc)
+
 
+def _parse_datetime(timestr, default):
+    """
+    Parses timestr, filling in missing components from default. Returns a
+    timezone-aware datetime, assuming local time if no timezone is given.
+    """
+    target = parse(timestr, default=default)
+    if target.tzinfo is None:
+        target = target.replace(tzinfo=tz.tzlocal())
     return target
 
 
+def _contains_date(timestr, default, parsed):
+    """
+    Returns True if timestr specifies (part of) a date or a weekday, i.e.
+    if parsing it doesn't just use the date from the given default.
+    """
+    if parsed.date() != default.date():
+        return True
+    # Parse again with a default that differs in year, month, day and weekday.
+    for day in (1, 2, 3):
+        other = datetime(default.year - 1, default.month % 12 + 1, day)
+        if day != default.day and other.weekday() != default.weekday():
+            break
+    try:
+        return parse(timestr, default=other).date() != other.date()
+    except ValueError:
+        # e.g. Feb 29 in a non-leap year, so there definitely is a date
+        return True
+
+
 def parse_timedelta(deltastr):
     """
-    Parse a string describing a period of time.
+    Parse a string describing a period of time. Returns None if deltastr
+    doesn't look like one.
     """
+    deltastr = deltastr.strip()
     matches = TIMEDELTA_REGEX.match(deltastr)
-    if not matches:
+    if not matches.group(0):
         return None
+    if matches.end() != len(deltastr):
+        # e.g. "1h30", don't silently ignore the rest
+        raise ValueError("Unable to parse '{}'".format(deltastr))
     components = {}
     for name, value in matches.groupdict().items():
         if value:

termdown-2.0.0/termdown/modes.py

@@ -1,287 +0,0 @@
-import os
-from curses import beep
-from datetime import datetime, timedelta, timezone
-from math import ceil
-from queue import Empty
-from subprocess import DEVNULL, STDOUT, Popen
-from sys import exit, stdout
-from time import monotonic, time
-
-from .events import (
-    INPUT_END,
-    INPUT_EXIT,
-    INPUT_LAP,
-    INPUT_MINUS,
-    INPUT_PAUSE,
-    INPUT_PLUS,
-    INPUT_RESET,
-)
-from .ticker import Metronome
-from .utils import (
-    format_seconds,
-    format_seconds_alt,
-    format_target,
-    parse_timestr,
-)
-
-
-def countdown(ui, args):
-    target_time = parse_timestr(args.timespec)
-    offset = (target_time.microsecond / 1_000_000)
-    ticker = Metronome(ui.input_queue, offset=offset)
-    ticker.start()
-
-    while True:  # Outer loop to allow restarting countdown from scratch
-        while True:  # Active countdown loop
-            seconds_left = (target_time - datetime.now(timezone.utc)).total_seconds()
-            if seconds_left <= 0:
-                # If seconds_left is zero or negative, immediately break to handle the
-                # "finished" state. This prevents displaying "0" for an entire second
-                # while waiting for the next tick.
-                break
-
-            if args.alt_format:
-                countdown_text = format_seconds_alt(
-                    seconds_left, hide_seconds=args.no_seconds
-                )
-            else:
-                countdown_text = format_seconds(
-                    seconds_left, hide_seconds=args.no_seconds
-                )
-
-            with ui.curses_lock:
-                ui.set_window_title(countdown_text)
-                if args.outfile:
-                    with open(args.outfile, "w") as f:
-                        f.write("{}\n{}\n".format(countdown_text, seconds_left))
-                end_text = (
-                    format_target(
-                        target_time,
-                        time_format=args.time_format,
-                        date_format=args.date_format,
-                    )
-                    if args.end
-                    else None
-                )
-                color = 0
-                if ticker.is_paused:
-                    color = 3
-                elif seconds_left <= args.critical:
-                    color = 1
-                ui.draw_text(countdown_text, color=color, end=end_text)
-
-            annunciation = None
-            if seconds_left <= args.critical:
-                annunciation = str(int(ceil(seconds_left)))  # Announce whole seconds
-            elif int(ceil(seconds_left)) in (5, 10, 20, 30, 60):
-                annunciation = "{} {} seconds".format(
-                    args.voice_prefix, int(ceil(seconds_left))
-                )
-            elif int(ceil(seconds_left)) in (300, 600, 1800):
-                annunciation = "{} {} minutes".format(
-                    args.voice_prefix, int(seconds_left / 60)
-                )
-            elif int(ceil(seconds_left)) == 3600:
-                annunciation = "{} one hour".format(args.voice_prefix)
-            if annunciation or args.exec_cmd:
-                if (
-                    annunciation and args.voice_cmd
-                ):  # Only announce if there is something to say
-                    Popen(
-                        [args.voice_cmd, "-v", args.voice, annunciation.strip()],
-                        stdout=DEVNULL,
-                        stderr=STDOUT,
-                    )
-                if args.exec_cmd:
-                    # Pass annunciation even if it's empty, format() handles it.
-                    Popen(
-                        args.exec_cmd.format(seconds_left, annunciation or ""),
-                        stdout=DEVNULL,
-                        stderr=STDOUT,
-                        shell=True,
-                    )
-
-            input_action = ui.input_queue.get()
-            if input_action == INPUT_PAUSE:
-                duration = ticker.pause()
-                if duration:
-                    target_time += timedelta(seconds=duration)
-            elif input_action == INPUT_EXIT:
-                exit(1)
-            elif input_action == INPUT_RESET:
-                target_time = parse_timestr(args.timespec)
-                # Continue the inner loop, seconds_left will be re-evaluated
-                continue
-            elif input_action == INPUT_PLUS:
-                target_time += timedelta(seconds=10)
-            elif input_action == INPUT_MINUS:
-                target_time -= timedelta(seconds=10)
-            elif input_action == INPUT_END:
-                args.end = not args.end
-                continue
-
-        # After the active countdown loop, handle the "time is up" state.
-
-        if not args.no_bell:
-            with ui.curses_lock:
-                beep()
-
-        if args.outfile:
-            with open(args.outfile, "w") as f:
-                f.write("{}\n{}\n".format(args.text if args.text else "DONE", 0))
-
-        if args.blink or args.text:
-            base_color = 1 if args.blink else 0
-            flip = True
-            ticker.pause()  # Pause ticker during blinking phase
-            while True:
-                if args.quit_after and (
-                    datetime.now(timezone.utc) - target_time
-                ).total_seconds() > float(args.quit_after):
-                    return
-                with ui.curses_lock:
-                    ui.set_window_title("/" if flip else "\\")
-                    if args.text:
-                        ui.draw_text(args.text, color=base_color if flip else 4)
-                    else:
-                        ui.draw_text("", color=base_color if flip else 4)
-                if args.blink:
-                    flip = not flip
-                try:
-                    input_action = ui.input_queue.get(True, 0.5)
-                except Empty:
-                    input_action = None
-                if input_action == INPUT_EXIT:
-                    return
-                elif input_action == INPUT_RESET:
-                    target_time = parse_timestr(args.timespec)
-                    ticker.pause()  # resume
-                    break  # Break out of the blinking loop to restart the main countdown
-        else:
-            break
-
-
-def clock(ui, args):
-    time_started = monotonic()
-    seconds_elapsed = 0
-    offset = timedelta(0)
-    ticker = Metronome(ui.input_queue)
-    ticker.start()
-    while True:
-        seconds_elapsed = monotonic() - time_started
-        if args.quit_after and seconds_elapsed >= float(args.quit_after):
-            return
-        clock_text = (datetime.now() + offset).strftime(args.time_format)
-        with ui.curses_lock:
-            ui.set_window_title(clock_text)
-
-            if args.outfile:
-                with open(args.outfile, "w") as f:
-                    f.write("{}\n{}\n".format(clock_text, seconds_elapsed))
-
-            ui.draw_text(clock_text, color=3 if ticker.is_paused else 0)
-
-        input_action = ui.input_queue.get()
-        if input_action == INPUT_EXIT:
-            break
-        if input_action == INPUT_PLUS:
-            offset += timedelta(seconds=10)
-        elif input_action == INPUT_MINUS:
-            offset -= timedelta(seconds=10)
-        elif input_action == INPUT_PAUSE:
-            ticker.pause()
-        elif input_action == INPUT_RESET:
-            offset = timedelta(0)
-
-
-def stopwatch(ui, args):
-    time_started = monotonic()
-    ticker = Metronome(ui.input_queue, offset=time() % 1.0)
-    ticker.start()
-    time_paused = None
-    seconds_elapsed = 0
-    laps = []
-    while True:
-        if not time_paused:
-            seconds_elapsed = monotonic() - time_started
-        else:
-            seconds_elapsed = time_paused - time_started
-
-        if args.quit_after and seconds_elapsed >= float(args.quit_after):
-            return seconds_elapsed, laps
-
-        if args.alt_format:
-            stopwatch_text = format_seconds_alt(
-                round(seconds_elapsed), hide_seconds=args.no_seconds
-            )
-        else:
-            stopwatch_text = format_seconds(
-                round(seconds_elapsed), hide_seconds=args.no_seconds
-            )
-        with ui.curses_lock:
-            if not args.no_window_title:
-                os.write(
-                    stdout.fileno(),
-                    "\033]2;{0}\007".format(stopwatch_text).encode(),
-                )
-            if args.outfile:
-                with open(args.outfile, "w") as f:
-                    f.write("{}\n{}\n".format(stopwatch_text, seconds_elapsed))
-
-            ui.draw_text(stopwatch_text, color=3 if ticker.is_paused else 0)
-
-        annunciation = None
-        if int(seconds_elapsed) <= args.critical and seconds_elapsed >= 1:
-            annunciation = str(int(seconds_elapsed))
-        elif int(seconds_elapsed) in (5, 10, 20, 30, 40, 50, 60):
-            annunciation = "{} {} seconds".format(
-                args.voice_prefix, int(seconds_elapsed)
-            )
-        elif int(seconds_elapsed) in (120, 180, 300, 600, 1800):
-            annunciation = "{} {} minutes".format(
-                args.voice_prefix, int(seconds_elapsed / 60)
-            )
-        elif int(seconds_elapsed) == 3600:
-            annunciation = "{} one hour".format(args.voice_prefix)
-        elif int(seconds_elapsed) % 3600 == 0 and seconds_elapsed > 1:
-            annunciation = "{} {} hours".format(
-                args.voice_prefix, int(seconds_elapsed / 3600)
-            )
-
-        if annunciation and args.voice_cmd:
-            Popen(
-                [args.voice_cmd, "-v", args.voice, annunciation.strip()],
-                stdout=DEVNULL,
-                stderr=STDOUT,
-            )
-        if args.exec_cmd:
-            Popen(
-                args.exec_cmd.format(seconds_elapsed, annunciation or ""),
-                stdout=DEVNULL,
-                stderr=STDOUT,
-                shell=True,
-            )
-
-        input_action = ui.input_queue.get()
-        if input_action == INPUT_PLUS:
-            time_started -= 10
-        elif input_action == INPUT_MINUS:
-            time_started += 10
-        elif input_action == INPUT_PAUSE:
-            duration = ticker.pause()
-            if duration:  # unpaused
-                time_started += duration
-                time_paused = None
-            else:
-                time_paused = monotonic()
-        elif input_action == INPUT_EXIT:
-            break
-        elif input_action == INPUT_RESET:
-            laps = []
-            time_started = monotonic()
-        elif input_action == INPUT_LAP:
-            lap_time = monotonic()
-            laps.append(lap_time - time_started)
-            time_started = lap_time
-
-    return (monotonic() - time_started, laps)

termdown-2.0.0/termdown/ticker.py

@@ -1,52 +0,0 @@
-from math import ceil
-from threading import Thread
-from time import monotonic, sleep, time
-
-from .events import TIME_TICK
-
-
-class Metronome:
-    """
-    Will put a TIME_TICK event into the given queue every full second, delayed by offset.
-    """
-
-    def __init__(self, queue, offset=0):
-        self._offset = offset
-        self._queue = queue
-        self._thread = Thread(target=self._run, daemon=True)
-        self._pause_time = None
-
-    def _run(self):
-        while True:
-            # Calculate the time to sleep until the next full second
-            current_time = time()
-            target_time = ceil(current_time) + self._offset
-            sleep_time = target_time - current_time
-
-            # If sleep_time is very small (e.g., we're just before the second),
-            # we should wait for the next second.
-            if sleep_time < 0.001:  # Small buffer to avoid missing the second
-                sleep_time += 1.0
-
-            sleep(sleep_time)
-            if not self.is_paused:
-                self._queue.put(TIME_TICK)
-
-    def start(self):
-        self._thread.start()
-
-    def pause(self):
-        if self.is_paused:  # unpause
-            duration = monotonic() - self._pause_time
-            self._pause_time = None
-            if self._offset is not None:
-                # If we're not running in clock mode, change the offset so the
-                # next tick will be 1s from now.
-                self._offset = time() % 1.0
-            return duration
-        else:  # pause
-            self._pause_time = monotonic()
-
-    @property
-    def is_paused(self):
-        return self._pause_time is not None