pypomodo 0.3.1__py3-none-any.whl

pypomo/__init__.py

@@ -0,0 +1,4 @@
+"""A small terminal timer."""
+from .cli import main
+
+__all__ = ['main']

pypomo/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pypomo/cli.py

@@ -0,0 +1,193 @@
+"""argparse entry point."""
+import argparse
+import sys
+import textwrap
+from dataclasses import replace
+from datetime import datetime, timedelta
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .config import NAME_RE, Config, default_config_path, load_config
+from .durations import DURATION_RE, parse_duration
+from .events import Events, JsonLines, Phase
+from .hooks import HookRunner
+from .keys import keyboard
+from .output import flush, silence_broken_pipe, write
+from .pomodoro import Pomodoro, run_pomodoro
+from .signals import Terminated, cancellation_handlers
+from .timer import format_duration, run_timer
+
+
+class ArgumentParser(argparse.ArgumentParser):
+    def _print_message(self, message, file=None):
+        if file is sys.stdout:
+            if message:
+                write(message, end='')
+        else:
+            super()._print_message(message, file)
+
+
+DURATIONS_HELP = 'Durations combine d, h, m, and s in that order: 25m, 1h30m, 1h 30m, or 2d.'
+DISTRIBUTION = 'pypomodo'  # The PyPI name; the command and package are pypomo.
+KEYS_HELP = ('While a timer runs in a terminal, press p or Space to pause and resume, '
+             'or q to cancel.')
+
+
+def end_time(seconds: int, now: datetime | None = None) -> str:
+    """Local clock time `seconds` from now, to the nearest minute; dated when not today."""
+    now = now or datetime.now()
+    end = now + timedelta(seconds=seconds)
+    end = (end + timedelta(seconds=30)).replace(second=0, microsecond=0)
+    return end.strftime('%H:%M' if end.date() == now.date() else '%Y-%m-%d %H:%M')
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        with cancellation_handlers():
+            try:
+                return _main(argv)
+            finally:
+                # Keep buffered output failures inside the broken-pipe boundary.
+                flush()
+    except BrokenPipeError:
+        silence_broken_pipe()
+        return 141
+    except Terminated as exc:
+        return 128 + exc.signum
+    except KeyboardInterrupt:
+        return 130
+
+
+def _main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parse_args(parser, argv)
+    try:
+        config = load_config(args.config or default_config_path(), required=args.config is not None)
+        if args.list:
+            list_timers(config)
+            return 0
+        target = resolve(args.timer, config)
+    except ValueError as exc:
+        parser.error(str(exc))
+    if isinstance(target, Pomodoro) and args.auto_start is not None:
+        target = replace(target, auto_start=args.auto_start)
+    if args.preview:
+        preview(args.timer, target)
+        return 0
+    pretty = replace(config.pretty, enabled=args.pretty) if args.pretty is not None else config.pretty
+    hooks = hook_runner(args, config)
+    jsonl = args.format == 'jsonl'
+    events = Events([listener for listener in (hooks, JsonLines(args.timer) if jsonl else None) if listener])
+    events = events or None
+    with keyboard() as keys:
+        if isinstance(target, Pomodoro):
+            run_pomodoro(target, args.timer, live=args.live, pretty=pretty, silent=args.silent, keys=keys,
+                         events=events, display=not jsonl)
+        else:
+            on_event = events.handler(Phase(args.timer, 'timer', target)) if events else None
+            run_timer(target, args.timer, live=args.live, pretty=pretty, silent=args.silent, keys=keys,
+                      on_event=on_event, display=not jsonl)
+    return 0
+
+
+def build_parser() -> ArgumentParser:
+    parser = ArgumentParser(
+        description='Start a duration or named timer (e.g. 15m, 1h30m, pomo).',
+        epilog='\n\n'.join(textwrap.fill(text, 79) for text in (DURATIONS_HELP, KEYS_HELP)),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument('timer', nargs='?', help='duration, timer name, pomo, or NAME.pomo')
+    parser.add_argument('--config', type=Path, help='TOML or JSON config path (default: XDG config directory or ~/.config/pypomo)')
+    parser.add_argument('--list', action='store_true', help='list available timers and Pomodoro routines')
+    parser.add_argument('--live', action='store_true', help='update one line even when output is piped')
+    parser.add_argument('--silent', action='store_true', help='suppress the completion bell')
+    parser.add_argument('--preview', action='store_true', help='show phases and total duration without starting a timer')
+    parser.add_argument('--pretty', action=argparse.BooleanOptionalAction, default=None,
+                        help='enable styled output (or --no-pretty to disable it)')
+    parser.add_argument('--hook', action='append', default=[], metavar='CMD',
+                        help='run CMD through the shell on every timer event (repeatable)')
+    parser.add_argument('--no-hooks', action='store_true', help='ignore hooks from the config file')
+    parser.add_argument('--format', choices=('text', 'jsonl'), default='text',
+                        help='text: the countdown display (default); jsonl: one JSON object per '
+                             'event on stdout, with no display')
+    parser.add_argument('--auto-start', action=argparse.BooleanOptionalAction, default=None,
+                        help='start each Pomodoro phase automatically (or --no-auto-start '
+                             'to wait for Enter between phases)')
+    try:
+        package_version = version(DISTRIBUTION)
+    except PackageNotFoundError:
+        package_version = 'unknown (source checkout)'
+    parser.add_argument('--version', action='version', version=f'pypomo {package_version}')
+    return parser
+
+
+def parse_args(parser: ArgumentParser, argv: list[str] | None) -> argparse.Namespace:
+    """Parse and cross-check arguments, joining an unquoted spaced duration such as 1h 30m."""
+    args, extras = parser.parse_known_args(argv)
+    if extras:
+        if any(value.startswith('-') and value[1:2].isdigit() for value in extras):
+            parser.error('Duration must be greater than zero.')
+        if not (args.timer and DURATION_RE.fullmatch(args.timer)
+                and all(DURATION_RE.fullmatch(value) for value in extras)):
+            parser.error(f"unrecognized arguments: {' '.join(extras)}")
+        args.timer = ' '.join([args.timer, *extras])
+    if args.timer is None and not args.list:
+        parser.error('provide a duration or timer name, or use --list')
+    if args.timer is not None and args.list:
+        parser.error('use --list without a timer')
+    if args.preview and args.list:
+        parser.error('use --preview with a timer or routine, not --list')
+    if args.format == 'jsonl':
+        for flag, used in (('--list', args.list), ('--preview', args.preview), ('--live', args.live)):
+            if used:
+                parser.error(f'--format jsonl is for running timers; it cannot be used with {flag}')
+    return args
+
+
+def resolve(name: str, config: Config) -> Pomodoro | int:
+    """Return the routine or the number of seconds that `name` refers to."""
+    if name == 'pomo':
+        return config.pomo
+    if name.endswith('.pomo'):
+        routine = config.pomodoros.get(name[:-5])
+        if routine is None:
+            raise ValueError(f'Unknown Pomodoro routine {name!r}. Use --list to see available routines.')
+        return routine
+    if name in config.timers:
+        return config.timers[name]
+    if NAME_RE.fullmatch(name):
+        raise ValueError(f'Unknown timer {name!r}. Use --list to see available timers.')
+    return parse_duration(name, config.default_units)
+
+
+def list_timers(config: Config) -> None:
+    for name, seconds in sorted(config.timers.items()):
+        write(f'{name}: {format_duration(seconds)}')
+    routines = {'pomo': config.pomo, **{f'{name}.pomo': value for name, value in config.pomodoros.items()}}
+    for name, routine in sorted(routines.items()):
+        write(f'{name}: {routine.rounds} focus rounds · focus {format_duration(routine.focus)}'
+              f' · short break {format_duration(routine.short_break)}'
+              f' · long break {format_duration(routine.long_break)}'
+              + ('' if routine.auto_start else ' · waits between phases'))
+
+
+def preview(name: str, target: Pomodoro | int) -> None:
+    if isinstance(target, Pomodoro):
+        total = 0
+        for phase, duration, round_number in target.phases():
+            write(f'{name} · {phase} {round_number}/{target.rounds}: {format_duration(duration)}')
+            total += duration
+    else:
+        total = target
+        write(f'{name}: {format_duration(target)}')
+    write(f'Total: {format_duration(total)}')
+    waits = isinstance(target, Pomodoro) and not target.auto_start
+    write(f"Ends: {end_time(total)} if started now{', plus time waiting between phases' if waits else ''}")
+
+
+def hook_runner(args: argparse.Namespace, config: Config) -> HookRunner | None:
+    """Configured hooks (unless --no-hooks) plus --hook commands, which run on every event."""
+    commands = {} if args.no_hooks else dict(config.hooks)
+    if args.hook:
+        commands['any'] = commands.get('any', []) + args.hook
+    return HookRunner(commands, args.timer) if commands else None

pypomo/config.py

@@ -0,0 +1,87 @@
+"""Optional TOML or JSON configuration."""
+import json
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .durations import DEFAULT_UNITS, UNITS_MESSAGE, parse_duration
+from .hooks import Command, parse_hooks
+from .pomodoro import Pomodoro, parse_pomodoro
+from .pretty import Pretty, parse_pretty
+
+NAME_RE = re.compile(r'[A-Za-z][A-Za-z0-9_-]*')
+
+
+@dataclass
+class Config:
+    default_units: str | None = None
+    timers: dict[str, int] = field(default_factory=dict)
+    pretty: Pretty = field(default_factory=Pretty)
+    pomo: Pomodoro = field(default_factory=Pomodoro)
+    pomodoros: dict[str, Pomodoro] = field(default_factory=dict)
+    hooks: dict[str, list[Command]] = field(default_factory=dict)
+
+
+def default_config_path() -> Path:
+    xdg = os.environ.get('XDG_CONFIG_HOME')
+    base = Path(xdg) if xdg and Path(xdg).is_absolute() else Path.home() / '.config'
+    directory = base / 'pypomo'
+    toml = directory / 'config.toml'
+    legacy = directory / 'config.json'
+    return toml if toml.exists() or not legacy.exists() else legacy
+
+
+def load_config(path: Path, *, required: bool = False) -> Config:
+    config = Config()
+    try:
+        content = path.read_text(encoding='utf-8-sig')
+        if path.suffix.lower() == '.toml':
+            data = tomllib.loads(content)
+        elif path.suffix.lower() == '.json':
+            data = json.loads(content)
+        else:
+            raise ValueError('Config file must use .toml or .json.')
+    except FileNotFoundError:
+        if not required:
+            return config
+        raise ValueError(f'Config file not found: {path}') from None
+    except (OSError, ValueError) as exc:
+        raise ValueError(f'Cannot read config {path}: {exc}') from exc
+    if not isinstance(data, dict):
+        raise ValueError('Config must be an object/table.')
+    unknown = data.keys() - {'default_units', 'timers', 'pretty', 'pomo', 'pomodoros', 'hooks'}
+    if unknown:
+        raise ValueError(f"Unknown config settings: {', '.join(sorted(unknown))}")
+    if 'default_units' in data:
+        unit = data['default_units']
+        if not isinstance(unit, str) or unit not in DEFAULT_UNITS:
+            raise ValueError(UNITS_MESSAGE)
+        config.default_units = unit
+    config.pretty = parse_pretty(data.get('pretty', {}))
+    config.hooks = parse_hooks(data.get('hooks', {}))
+    timers = data.get('timers', {})
+    if not isinstance(timers, dict):
+        raise ValueError('timers must map names to duration strings.')
+    for name, duration in timers.items():
+        if not NAME_RE.fullmatch(name):
+            raise ValueError(f'Invalid timer name {name!r}: start with a letter; use letters, digits, _ or -.')
+        if not isinstance(duration, str):
+            raise ValueError(f'Timer {name!r} must contain a duration string.')
+        try:
+            config.timers[name] = parse_duration(duration, config.default_units)
+        except ValueError as exc:
+            raise ValueError(f'Timer {name!r}: {exc}') from exc
+    legacy_focus = config.timers.pop('pomo', config.pomo.focus)
+    config.pomo = parse_pomodoro(data.get('pomo', {}), Pomodoro(focus=legacy_focus),
+                                 config.default_units, 'pomo')
+    routines = data.get('pomodoros', {})
+    if not isinstance(routines, dict):
+        raise ValueError('pomodoros must map names to routine settings.')
+    for name, settings in routines.items():
+        if not NAME_RE.fullmatch(name):
+            raise ValueError(f'Invalid Pomodoro name {name!r}: start with a letter; use letters, digits, _ or -.')
+        config.pomodoros[name] = parse_pomodoro(settings, config.pomo, config.default_units,
+                                               f'pomodoros.{name}')
+    return config

pypomo/durations.py

@@ -0,0 +1,41 @@
+"""Duration parsing shared by CLI and configuration."""
+import re
+
+UNITS = {'s': 1, 'm': 60, 'h': 3600, 'd': 86400}
+MAX_SECONDS = 365 * 86400
+DURATION_RE = re.compile(r'(?:[0-9]+[dhms])+')
+SPACED_RE = re.compile(r'(?:[0-9]+[dhms])+(?: +(?:[0-9]+[dhms])+)+')
+DEFAULT_UNITS = {'s': 's', 'seconds': 's', 'm': 'm', 'minutes': 'm', 'h': 'h', 'hours': 'h',
+                 'd': 'd', 'days': 'd'}
+UNITS_MESSAGE = 'default_units must be seconds, minutes, hours, days, s, m, h, or d.'
+SPACED_MESSAGE = 'Spaces are allowed only between units, as in 1h 30m.'
+
+
+def parse_duration(value: str, default_units: str | None = None) -> int:
+    if any(char.isspace() for char in value):
+        if not SPACED_RE.fullmatch(value):
+            raise ValueError(SPACED_MESSAGE)
+        value = value.replace(' ', '')
+    if re.fullmatch(r'[0-9]+', value):
+        if default_units is None:
+            raise ValueError('Missing units: use 15s, 15m, 15h, or 15d, or configure default_units.')
+        if default_units not in DEFAULT_UNITS:
+            raise ValueError(UNITS_MESSAGE)
+        value += DEFAULT_UNITS[default_units]
+    if not DURATION_RE.fullmatch(value):
+        raise ValueError('Invalid duration: use whole numbers with d, h, m, or s (e.g. 1h30m15s).')
+    total, previous = 0, UNITS['d'] + 1
+    for amount, unit in re.findall(r'([0-9]+)([dhms])', value):
+        multiplier = UNITS[unit]
+        if multiplier >= previous:
+            raise ValueError('Duration units must appear once each, in order: d, h, m, s.')
+        amount = amount.lstrip('0') or '0'
+        if len(amount) > len(str(MAX_SECONDS)):
+            raise ValueError('Duration too long: maximum is 365 days (365d).')
+        total += int(amount) * multiplier
+        if total > MAX_SECONDS:
+            raise ValueError('Duration too long: maximum is 365 days (365d).')
+        previous = multiplier
+    if total <= 0:
+        raise ValueError('Duration must be greater than zero.')
+    return total

pypomo/events.py

@@ -0,0 +1,69 @@
+"""Timer events and the listeners that receive them (hooks and JSON lines)."""
+import json
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+
+from .output import write
+
+EVENTS = ('start', 'end', 'pause', 'resume', 'cancel', 'wait')
+
+# Called by a running timer with an event name and the whole seconds remaining.
+EventHandler = Callable[[str, int], None]
+
+
+@dataclass(frozen=True)
+class Phase:
+    """What listeners are told about the timer or routine phase behind an event."""
+    label: str
+    phase: str
+    duration: int
+    round: int | None = None
+    rounds: int | None = None
+    last: bool = True
+
+
+# Receives the event name, its phase, and the whole seconds remaining.
+Listener = Callable[[str, Phase, int], None]
+
+
+class Events:
+    """Fans each timer event out to every listener."""
+
+    def __init__(self, listeners: Sequence[Listener]):
+        self.listeners = list(listeners)
+
+    def __bool__(self) -> bool:
+        return bool(self.listeners)
+
+    def handler(self, phase: Phase) -> EventHandler:
+        def emit(event: str, remaining: int) -> None:
+            for listener in self.listeners:
+                listener(event, phase, remaining)
+        return emit
+
+
+def event_record(event: str, timer: str, phase: Phase, remaining: int,
+                 now: datetime | None = None) -> dict[str, object]:
+    return {
+        'event': event,
+        'timer': timer,
+        'label': phase.label,
+        'phase': phase.phase,
+        'round': phase.round,
+        'rounds': phase.rounds,
+        'duration': phase.duration,
+        'remaining': remaining,
+        'last': phase.last,
+        'time': (now or datetime.now().astimezone()).isoformat(timespec='seconds'),
+    }
+
+
+class JsonLines:
+    """Writes one ASCII JSON object per event to stdout, flushed immediately."""
+
+    def __init__(self, timer: str):
+        self.timer = timer
+
+    def __call__(self, event: str, phase: Phase, remaining: int) -> None:
+        write(json.dumps(event_record(event, self.timer, phase, remaining)))

pypomo/hooks.py

@@ -0,0 +1,91 @@
+"""Run user commands on timer events, without waiting for them."""
+import os
+import subprocess
+import sys
+from collections.abc import Mapping
+
+from .events import EVENTS, Phase
+
+HOOK_KEYS = (*EVENTS, 'any')
+
+Command = str | list[str]
+
+
+def parse_hooks(data: object) -> dict[str, list[Command]]:
+    """Validate a [hooks] table: event name -> shell string or argv list."""
+    if not isinstance(data, dict):
+        raise ValueError('hooks must be an object/table.')
+    unknown = data.keys() - set(HOOK_KEYS)
+    if unknown:
+        raise ValueError(f"Unknown hooks: {', '.join(sorted(unknown))}. "
+                         f"Use {', '.join(HOOK_KEYS)}.")
+    result: dict[str, list[Command]] = {}
+    for event, command in data.items():
+        if isinstance(command, str) and command.strip():
+            result[event] = [command]
+        elif (isinstance(command, list) and command
+              and all(isinstance(part, str) for part in command) and command[0]):
+            result[event] = [list(command)]
+        else:
+            raise ValueError(f'hooks.{event} must be a command string or a nonempty list of '
+                             f'strings; got {command!r}.')
+    return result
+
+
+class HookRunner:
+    """Starts configured commands in the background and never lets them stop the timer.
+
+    String commands run through the system shell; lists run directly. Commands
+    get PYPOMO_* environment variables, no stdin, and discarded stdout; stderr is
+    inherited so their errors stay visible. Each runs in its own session, so
+    Ctrl+C or a closing terminal does not interrupt a hook already running.
+    """
+
+    def __init__(self, commands: Mapping[str, list[Command]], timer: str):
+        self.commands = {event: list(items) for event, items in commands.items() if items}
+        self.timer = timer
+        self.running: list[subprocess.Popen[bytes]] = []
+        self.failed: set[str] = set()
+
+    def __bool__(self) -> bool:
+        return bool(self.commands)
+
+    def __call__(self, event: str, phase: Phase, remaining: int) -> None:
+        self.emit(event, phase, remaining)
+
+    def emit(self, event: str, phase: Phase, remaining: int) -> None:
+        commands = self.commands.get(event, []) + self.commands.get('any', [])
+        if not commands:
+            return
+        env = dict(os.environ,
+                   PYPOMO_EVENT=event,
+                   PYPOMO_TIMER=self.timer,
+                   PYPOMO_LABEL=phase.label,
+                   PYPOMO_PHASE=phase.phase,
+                   PYPOMO_ROUND='' if phase.round is None else str(phase.round),
+                   PYPOMO_ROUNDS='' if phase.rounds is None else str(phase.rounds),
+                   PYPOMO_DURATION=str(phase.duration),
+                   PYPOMO_REMAINING=str(remaining),
+                   PYPOMO_LAST='1' if phase.last else '0')
+        self.running = [process for process in self.running if process.poll() is None]
+        for command in commands:
+            self._start(command, env)
+
+    def _start(self, command: Command, env: dict[str, str]) -> None:
+        options: dict[str, object] = {}
+        if sys.platform == 'win32':
+            options['creationflags'] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            options['start_new_session'] = True
+        try:
+            self.running.append(subprocess.Popen(
+                command, shell=isinstance(command, str), env=env,
+                stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, **options))
+        except (OSError, ValueError) as exc:
+            name = command if isinstance(command, str) else ' '.join(command)
+            if name not in self.failed:  # Warn once per command, not on every event.
+                self.failed.add(name)
+                try:
+                    print(f'\npypomo: hook could not start: {name}: {exc}', file=sys.stderr, flush=True)
+                except (OSError, ValueError, AttributeError):
+                    pass

pypomo/keys.py

@@ -0,0 +1,127 @@
+"""Single-key terminal input for pause/resume and phase confirmation."""
+import os
+import sys
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TextIO
+
+PAUSE_KEYS = frozenset('p ')
+QUIT_KEYS = frozenset('q')
+ENTER_KEYS = frozenset('\r\n')
+
+
+class Keyboard:
+    """Reads keys without waiting for Enter. Created only by `keyboard()`."""
+
+    def read(self, timeout: float | None) -> str | None:
+        """Return one keypress, or None when `timeout` seconds pass first.
+
+        Escape sequences (arrow and function keys) are discarded.
+        """
+        raise NotImplementedError
+
+
+class _PosixKeyboard(Keyboard):
+    def __init__(self, fd: int):
+        self.fd = fd
+
+    def read(self, timeout: float | None) -> str | None:
+        import select
+
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            wait = None if deadline is None else max(0.0, deadline - time.monotonic())
+            ready, _, _ = select.select([self.fd], [], [], wait)
+            if not ready:
+                return None
+            data = os.read(self.fd, 64).decode(errors='ignore')
+            if not data:  # Terminal hung up; behave as if no key will ever arrive.
+                if timeout is not None:
+                    time.sleep(wait or 0)
+                    return None
+                raise KeyboardInterrupt
+            if not data.startswith('\x1b'):
+                return data[0]
+
+
+class _WindowsKeyboard(Keyboard):
+    def read(self, timeout: float | None) -> str | None:
+        import msvcrt
+
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            while msvcrt.kbhit():
+                key = msvcrt.getwch()
+                if key in ('\x00', '\xe0'):  # Prefix of an arrow or function key.
+                    msvcrt.getwch()
+                    continue
+                if key == '\x03':
+                    raise KeyboardInterrupt
+                return key
+            if deadline is not None and time.monotonic() >= deadline:
+                return None
+            remaining = 0.05 if deadline is None else deadline - time.monotonic()
+            time.sleep(max(0.0, min(0.05, remaining)))
+
+
+def _foreground_tty(stream: TextIO) -> int | None:
+    try:
+        fd = stream.fileno()
+        if not os.isatty(fd):
+            return None
+    except (AttributeError, OSError, ValueError):
+        return None
+    try:
+        # A background job that changes terminal modes is stopped with SIGTTOU.
+        if os.tcgetpgrp(fd) != os.getpgrp():
+            return None
+    except (AttributeError, OSError):
+        pass  # Windows, or a terminal that is not our controlling terminal.
+    return fd
+
+
+@contextmanager
+def keyboard() -> Iterator[Keyboard | None]:
+    """Yield a Keyboard when stdin is a foreground terminal, else None.
+
+    On POSIX the terminal is switched to cbreak mode (no line buffering, no
+    echo) and restored on exit. Ctrl+C and Ctrl+Z keep their usual meaning.
+    """
+    fd = None if sys.stdin is None else _foreground_tty(sys.stdin)
+    if fd is None:
+        yield None
+        return
+    if sys.platform == 'win32':
+        yield _WindowsKeyboard()
+        return
+    import signal
+    import termios
+    import threading
+    import tty
+
+    def cbreak(*_):
+        try:
+            tty.setcbreak(fd, termios.TCSANOW)
+        except termios.error:
+            pass
+
+    try:
+        saved = termios.tcgetattr(fd)
+        tty.setcbreak(fd, termios.TCSANOW)
+    except termios.error:
+        yield None
+        return
+    previous = None
+    if threading.current_thread() is threading.main_thread():
+        # The shell may restore its own terminal modes after Ctrl+Z; reapply ours on `fg`.
+        previous = signal.signal(signal.SIGCONT, cbreak)
+    try:
+        yield _PosixKeyboard(fd)
+    finally:
+        if previous is not None:
+            signal.signal(signal.SIGCONT, previous)
+        try:
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+        except termios.error:
+            pass

pypomo/output.py

@@ -0,0 +1,55 @@
+"""Small helpers shared by timer and CLI output."""
+import errno
+import os
+import stat
+import sys
+from contextlib import contextmanager
+
+
+def safe_text(text: str, fallback: str | None = None) -> str:
+    encoding = getattr(sys.stdout, 'encoding', None) or 'utf-8'
+    try:
+        text.encode(encoding)
+        return text
+    except UnicodeEncodeError:
+        if fallback is not None:
+            return fallback
+        return text.replace('·', '-').encode(encoding, errors='backslashreplace').decode(encoding)
+
+
+@contextmanager
+def _pipe_errors():
+    """Normalize the Windows CRT's EINVAL for writes to a broken pipe only."""
+    try:
+        yield
+    except OSError as exc:
+        if sys.platform == 'win32' and exc.errno == errno.EINVAL:
+            try:
+                is_pipe = stat.S_ISFIFO(os.fstat(sys.stdout.fileno()).st_mode)
+            except (AttributeError, OSError, ValueError):
+                is_pipe = False
+            if is_pipe:
+                raise BrokenPipeError(errno.EPIPE, 'Broken output pipe') from exc
+        raise
+
+
+def write(text: str, *, end: str = '\n') -> None:
+    if sys.stdout is not None:
+        with _pipe_errors():
+            print(safe_text(text), end=end, flush=True)
+
+
+def flush() -> None:
+    if sys.stdout is not None:
+        with _pipe_errors():
+            sys.stdout.flush()
+
+
+def silence_broken_pipe() -> None:
+    """Prevent a second broken-pipe error during interpreter shutdown."""
+    try:
+        descriptor = sys.stdout.fileno()
+    except (AttributeError, OSError, ValueError):
+        return
+    with open(os.devnull, 'w') as sink:
+        os.dup2(sink.fileno(), descriptor)