backpack-backbone 0.2.0__tar.gz

backpack_backbone-0.2.0/LICENSE

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

backpack_backbone-0.2.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: backpack-backbone
+Version: 0.2.0
+Summary: Shared code for the back* tools: terminal UI, prompt widgets, live views, logging, dates, settings plumbing and small file helpers, implemented once.
+License: MIT
+Project-URL: Homepage, https://github.com/RedEraRrow/backbone
+Project-URL: Issues, https://github.com/RedEraRrow/backbone/issues
+Classifier: Environment :: Console :: Curses
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# backbone
+
+Everything the back* tools share, written once: colours, margins, box
+drawing, meters, prompt widgets and a live-view loop, so a list in one tool
+looks and behaves like a list in another, plus the plumbing underneath (logging,
+dates, CLI output, atomic files, background processes, notifications). backtrack
+and backcrack both build on it, and a new tool should too: anything that isn't
+specific to one tool's job belongs here.
+
+Python, stdlib only - no third-party packages at all. Requires Python 3.10+.
+
+This is a library, not a tool. It has no entry points of its own; something
+else imports it.
+
+## Install
+
+On PyPI as `backpack-backbone` (the import name is still `backbone`).
+backtrack and backcrack depend on it, so installing either one pulls it in;
+there's no reason to install it on its own unless you're building a tool.
+
+To work on it, install this checkout editable before the tools, so edits here
+take effect immediately with no reinstall:
+
+    pip3 install -e .
+
+pip then sees the requirement already satisfied and leaves it.
+
+`backbone.deps` is how a tool says what it needs besides Python: each tool's
+`doctor` command reports it, and `deps.require` stops a tool at startup with
+how to install anything it can't run without.
+
+## What's in it
+
+**`ui`** - the visual layer. `Colors` (honours `NO_COLOR=1`), the global
+`MARGIN_H` / `MARGIN_V` inset every frame is drawn inside, `wrap_margins`,
+`rule`, `bar`, `header_box`, `sparkline`, `spinner`, `rate_of_change`, and
+the `SPIN` / `PARTS` / `SPARK` glyph sets. Also the ANSI-aware text
+measuring (`visual_len`, `truncate_text`, `clip_ansi`, `strip_ansi`) that
+makes any of that survive colour codes and wide characters, and small
+formatters: `plural`, `human_gb`, `dir_size_kb`. The accent colour is chosen
+with `set_accent` (an `ACCENT_PRESETS` key or `#RRGGBB`); a tool calls it once
+at startup from its own settings, and `accent_code` / `accent_label` let a
+settings screen check and name a value.
+
+`from backbone import ...` exposes only a subset of `ui` (`Colors`, the
+margins and glyph sets, `spinner`, `content_width`, `rule`, `bar`,
+`header_box`, `wrap_margins`); import anything else from its module, e.g.
+`from backbone.ui import human_gb`.
+
+**`prompt`** - the widgets. `select` (single or multi), `confirm`, `text`,
+`path`, `live_select`, `list_edit`, plus specialised editors for tag-style
+values: `calendar_select`, `datetime_edit`, `time_edit`,
+`fraction_edit`, `number_edit`, `rating_edit`, `equaliser_edit`, `rva2_edit`,
+`system_editor_edit`. All resize-aware, all mouse-aware, all rendered through
+the same painter.
+
+**`prompt.core`** - the primitives underneath: the screen-diff painter, key
+reading, the `Choice` and `Column` types, the footer hint bar (`hint`) and its
+click mapping, and `run_dashboard`.
+
+**`nav`** - `NAV_STACK`, the app-wide breadcrumb, and `QuitToTerminal`, which
+derives from `BaseException` specifically so an editor's `except Exception`
+can't swallow a quit.
+
+**`datetime_parse`** - one date and time parser for everything that reads a
+hand-typed date, keeping whatever precision was given and saying why when it
+can't read something.
+
+**`app`** - who is running. A tool calls `app.configure("name", config_dir)`
+once at startup (from its config module); the log file and the hints toggle
+are kept in that folder, named after the tool.
+
+**`log`** - the diagnostics log, `<config_dir>/<name>.log`, off until the
+tool calls `log.configure(True)`. `from backbone.log import log` to write to
+it, and `with quietly():` to carry on past an error on purpose while still
+logging it.
+
+**`output`** - a CLI's one output path: `table`, `record`, `event`, `note`,
+`fail`, drawn as human text on a terminal or JSON / NDJSON with `--json`, and
+the exit codes that go with them.
+
+**`files`** - `write_text_atomic`, `backup_copy`, `log_line` (a daemon's
+timestamped line, printed and appended to its log), `disk_free`,
+`count_entries`.
+
+**`procs`** - a tool's own background processes: `spawn_module` starts one (`python -m`)
+detached, `find_processes` / `stop_processes` find or SIGTERM them by name
+however they were started (directly, through `python3`, or through a launcher
+command given as `launcher=`), `ps_listing` for the raw process table.
+
+**`notify`** - `ntfy(server, topic, title, message)` pushes to a phone in the
+background, doing nothing without a topic; `chime()` plays a sound at the
+machine.
+
+**`timefmt`**, **`numbering`**, **`keyboard`**, **`terminal_input`** - clock
+and SRT timestamps; arabic, roman or written-out numbers; the keyboard layout
+family (for typo scoring); raw key reads and escape decoding.
+
+**`prompt.timezone`** - a full-screen world-map timezone picker.
+
+## Live views
+
+`run_dashboard(render, interval=..., on_key=...)` drives a tick-driven view
+through the same `_Widget` machinery every prompt widget uses, rather than each
+tool hand-rolling a redraw loop:
+
+    from backbone.prompt.core import run_dashboard
+
+    def render() -> list:
+        return ["  line one", "  line two"]
+
+    run_dashboard(render, interval=1.0, quit_key="q")
+
+`render()` returns the whole frame as a list of lines, each carrying its own
+left indent, and only runs once per `interval`. Keypresses and resizes are
+checked every 50ms regardless, so a resize repaints and a `q` quits at once
+instead of waiting out the data-refresh cadence. `on_key` handles anything
+other than the quit key and is free to open a `select()` or `confirm()` of its
+own; the dashboard repaints from scratch when it returns.
+
+When stdin isn't a terminal (run from a script, or with input redirected),
+it falls back to a plain sleep loop and never reads keys, so such a view has
+to be stopped from outside.
+
+## Terminal size
+
+Everything reads `get_terminal_width()`, one cached value invalidated by
+SIGWINCH, rather than calling out to the OS per line. `consume_resize()` tells
+a loop a resize has landed since it last asked, which is the signal to clear
+and repaint rather than diff.
+
+`content_width()` is that width minus the margins, with no artificial floor:
+content is always sized against the real terminal, however narrow, so a hard
+clip later can't cut an oversized frame apart mid-border.
+
+## Status bar and background work
+
+`set_status(task_id, message)` registers running background work, which shows
+in the status line as a pulsing beacon until the id is cleared. `show_status`
+is the transient one-line toast. `set_footer_provider(fn)` registers a
+persistent box drawn above the status line, such as backtrack's now-playing
+bar; register nothing and no box is drawn. `prompt` also has optional hooks
+for a host app's playback keys and player view (`set_transport_handler`,
+`set_player_opener`), unused unless registered.
+
+## Self-checks
+
+Two modules check their own pure logic, no terminal needed:
+
+    python3 -m backbone.ui
+    python3 -m backbone.prompt.core
+
+Both print an OK line. They cover the parts that run without a terminal:
+sizing, measuring, truncation, table widths, hint parsing. Raw mode,
+key reading and screen painting need a real tty and are not covered.
+
+The tests in `tests/` each run on their own:
+
+    for f in tests/test_*.py; do python3 "$f"; done

backpack_backbone-0.2.0/README.md

@@ -0,0 +1,159 @@
+# backbone
+
+Everything the back* tools share, written once: colours, margins, box
+drawing, meters, prompt widgets and a live-view loop, so a list in one tool
+looks and behaves like a list in another, plus the plumbing underneath (logging,
+dates, CLI output, atomic files, background processes, notifications). backtrack
+and backcrack both build on it, and a new tool should too: anything that isn't
+specific to one tool's job belongs here.
+
+Python, stdlib only - no third-party packages at all. Requires Python 3.10+.
+
+This is a library, not a tool. It has no entry points of its own; something
+else imports it.
+
+## Install
+
+On PyPI as `backpack-backbone` (the import name is still `backbone`).
+backtrack and backcrack depend on it, so installing either one pulls it in;
+there's no reason to install it on its own unless you're building a tool.
+
+To work on it, install this checkout editable before the tools, so edits here
+take effect immediately with no reinstall:
+
+    pip3 install -e .
+
+pip then sees the requirement already satisfied and leaves it.
+
+`backbone.deps` is how a tool says what it needs besides Python: each tool's
+`doctor` command reports it, and `deps.require` stops a tool at startup with
+how to install anything it can't run without.
+
+## What's in it
+
+**`ui`** - the visual layer. `Colors` (honours `NO_COLOR=1`), the global
+`MARGIN_H` / `MARGIN_V` inset every frame is drawn inside, `wrap_margins`,
+`rule`, `bar`, `header_box`, `sparkline`, `spinner`, `rate_of_change`, and
+the `SPIN` / `PARTS` / `SPARK` glyph sets. Also the ANSI-aware text
+measuring (`visual_len`, `truncate_text`, `clip_ansi`, `strip_ansi`) that
+makes any of that survive colour codes and wide characters, and small
+formatters: `plural`, `human_gb`, `dir_size_kb`. The accent colour is chosen
+with `set_accent` (an `ACCENT_PRESETS` key or `#RRGGBB`); a tool calls it once
+at startup from its own settings, and `accent_code` / `accent_label` let a
+settings screen check and name a value.
+
+`from backbone import ...` exposes only a subset of `ui` (`Colors`, the
+margins and glyph sets, `spinner`, `content_width`, `rule`, `bar`,
+`header_box`, `wrap_margins`); import anything else from its module, e.g.
+`from backbone.ui import human_gb`.
+
+**`prompt`** - the widgets. `select` (single or multi), `confirm`, `text`,
+`path`, `live_select`, `list_edit`, plus specialised editors for tag-style
+values: `calendar_select`, `datetime_edit`, `time_edit`,
+`fraction_edit`, `number_edit`, `rating_edit`, `equaliser_edit`, `rva2_edit`,
+`system_editor_edit`. All resize-aware, all mouse-aware, all rendered through
+the same painter.
+
+**`prompt.core`** - the primitives underneath: the screen-diff painter, key
+reading, the `Choice` and `Column` types, the footer hint bar (`hint`) and its
+click mapping, and `run_dashboard`.
+
+**`nav`** - `NAV_STACK`, the app-wide breadcrumb, and `QuitToTerminal`, which
+derives from `BaseException` specifically so an editor's `except Exception`
+can't swallow a quit.
+
+**`datetime_parse`** - one date and time parser for everything that reads a
+hand-typed date, keeping whatever precision was given and saying why when it
+can't read something.
+
+**`app`** - who is running. A tool calls `app.configure("name", config_dir)`
+once at startup (from its config module); the log file and the hints toggle
+are kept in that folder, named after the tool.
+
+**`log`** - the diagnostics log, `<config_dir>/<name>.log`, off until the
+tool calls `log.configure(True)`. `from backbone.log import log` to write to
+it, and `with quietly():` to carry on past an error on purpose while still
+logging it.
+
+**`output`** - a CLI's one output path: `table`, `record`, `event`, `note`,
+`fail`, drawn as human text on a terminal or JSON / NDJSON with `--json`, and
+the exit codes that go with them.
+
+**`files`** - `write_text_atomic`, `backup_copy`, `log_line` (a daemon's
+timestamped line, printed and appended to its log), `disk_free`,
+`count_entries`.
+
+**`procs`** - a tool's own background processes: `spawn_module` starts one (`python -m`)
+detached, `find_processes` / `stop_processes` find or SIGTERM them by name
+however they were started (directly, through `python3`, or through a launcher
+command given as `launcher=`), `ps_listing` for the raw process table.
+
+**`notify`** - `ntfy(server, topic, title, message)` pushes to a phone in the
+background, doing nothing without a topic; `chime()` plays a sound at the
+machine.
+
+**`timefmt`**, **`numbering`**, **`keyboard`**, **`terminal_input`** - clock
+and SRT timestamps; arabic, roman or written-out numbers; the keyboard layout
+family (for typo scoring); raw key reads and escape decoding.
+
+**`prompt.timezone`** - a full-screen world-map timezone picker.
+
+## Live views
+
+`run_dashboard(render, interval=..., on_key=...)` drives a tick-driven view
+through the same `_Widget` machinery every prompt widget uses, rather than each
+tool hand-rolling a redraw loop:
+
+    from backbone.prompt.core import run_dashboard
+
+    def render() -> list:
+        return ["  line one", "  line two"]
+
+    run_dashboard(render, interval=1.0, quit_key="q")
+
+`render()` returns the whole frame as a list of lines, each carrying its own
+left indent, and only runs once per `interval`. Keypresses and resizes are
+checked every 50ms regardless, so a resize repaints and a `q` quits at once
+instead of waiting out the data-refresh cadence. `on_key` handles anything
+other than the quit key and is free to open a `select()` or `confirm()` of its
+own; the dashboard repaints from scratch when it returns.
+
+When stdin isn't a terminal (run from a script, or with input redirected),
+it falls back to a plain sleep loop and never reads keys, so such a view has
+to be stopped from outside.
+
+## Terminal size
+
+Everything reads `get_terminal_width()`, one cached value invalidated by
+SIGWINCH, rather than calling out to the OS per line. `consume_resize()` tells
+a loop a resize has landed since it last asked, which is the signal to clear
+and repaint rather than diff.
+
+`content_width()` is that width minus the margins, with no artificial floor:
+content is always sized against the real terminal, however narrow, so a hard
+clip later can't cut an oversized frame apart mid-border.
+
+## Status bar and background work
+
+`set_status(task_id, message)` registers running background work, which shows
+in the status line as a pulsing beacon until the id is cleared. `show_status`
+is the transient one-line toast. `set_footer_provider(fn)` registers a
+persistent box drawn above the status line, such as backtrack's now-playing
+bar; register nothing and no box is drawn. `prompt` also has optional hooks
+for a host app's playback keys and player view (`set_transport_handler`,
+`set_player_opener`), unused unless registered.
+
+## Self-checks
+
+Two modules check their own pure logic, no terminal needed:
+
+    python3 -m backbone.ui
+    python3 -m backbone.prompt.core
+
+Both print an OK line. They cover the parts that run without a terminal:
+sizing, measuring, truncation, table widths, hint parsing. Raw mode,
+key reading and screen painting need a real tty and are not covered.
+
+The tests in `tests/` each run on their own:
+
+    for f in tests/test_*.py; do python3 "$f"; done

backpack_backbone-0.2.0/backbone/__init__.py

@@ -0,0 +1,30 @@
+"""backbone - shared terminal UI: colours, meters, prompt widgets, live views."""
+from .ui import (
+    Colors,
+    MARGIN_H,
+    MARGIN_V,
+    SPIN,
+    PARTS,
+    SPARK,
+    spinner,
+    content_width,
+    rule,
+    bar,
+    header_box,
+    wrap_margins,
+)
+
+__all__ = [
+    "Colors",
+    "MARGIN_H",
+    "MARGIN_V",
+    "SPIN",
+    "PARTS",
+    "SPARK",
+    "spinner",
+    "content_width",
+    "rule",
+    "bar",
+    "header_box",
+    "wrap_margins",
+]

backpack_backbone-0.2.0/backbone/app.py

@@ -0,0 +1,26 @@
+"""Which program is running, so shared code can find its files: a name and a
+config folder, set once at startup by the host program (its config module)."""
+import os
+from pathlib import Path
+
+
+def _default_dir(name: str) -> Path:
+    """The platform's usual config folder for `name`."""
+    if os.name == "nt":
+        base = os.getenv("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / name.capitalize()
+    xdg = os.getenv("XDG_CONFIG_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".config") / name
+
+
+name = "backbone"
+config_dir = _default_dir(name)
+
+
+def configure(app_name: str, app_config_dir=None) -> None:
+    """Name the running program and its config folder (the platform default for
+    that name when not given). The diagnostics log and the saved hints switch
+    live there."""
+    global name, config_dir
+    name = app_name
+    config_dir = Path(app_config_dir) if app_config_dir else _default_dir(app_name)

backpack_backbone-0.2.0/backbone/datetime_parse.py

@@ -0,0 +1,224 @@
+"""One parser for every hand-typed date: the calendar, the date/time editor,
+the schedule table, filename values.
+
+Everything goes through :func:`parse_datetime`.  It accepts what a person
+plausibly types, keeps whatever precision was given, and says *why* when it can't
+read something so the caller can show that rather than a bare failure.
+
+Accepted, all with ``-``, ``/`` or ``.`` between the parts and zero-padding
+optional::
+
+    2008              2008-07           2008-07-02        2008-7-2
+    2008/07/02        2008.7.2          20080702
+    2008-07-02 18:30  2008-07-02T18:30  2008-07-02 18:30:45
+
+A time may follow the date after a ``T`` (either case) or a space, as ``HH:MM``
+or ``HH:MM:SS``.  A trailing timezone (``Z`` or ``±HH:MM``) is stripped: the
+tags Backtrack writes are local wall-clock timestamps.
+
+Day-first vs month-first (``02/07/2008``) is ambiguous and is resolved
+only when the caller says how, via ``dayfirst``.  Left unset, an ambiguous date
+is refused rather than guessed, because guessing wrong writes a plausible-looking
+wrong date that nobody notices.
+"""
+from __future__ import annotations
+
+import datetime
+import re
+from typing import NamedTuple, Optional
+
+__all__ = ['ParsedDateTime', 'parse_datetime', 'parse_date', 'parse_time',
+           'format_datetime', 'PRECISIONS']
+
+# Coarse → fine.  A caller can compare precisions with `PRECISIONS.index(...)`
+# to demand at least a given granularity.
+PRECISIONS = ('year', 'month', 'day', 'minute', 'second')
+
+# Year-first, any of - / . between parts, zero-padding optional.
+_YEAR_FIRST_RE = re.compile(r'^(\d{4})(?:[-/.\s](\d{1,2})(?:[-/.\s](\d{1,2}))?)?$')
+# ISO basic form, 20080702.
+_COMPACT_RE = re.compile(r'^(\d{4})(\d{2})(\d{2})$')
+# Day- or month-first, e.g. 02/07/2008, order decided by `dayfirst`.
+_YEAR_LAST_RE = re.compile(r'^(\d{1,2})[-/.\s](\d{1,2})[-/.\s](\d{4})$')
+# A trailing timezone we drop rather than try to honour.
+_TZ_RE = re.compile(r'(Z|[+-]\d{2}:?\d{2})$', re.IGNORECASE)
+
+
+class ParsedDateTime(NamedTuple):
+    """The result of reading a date/time a user typed.
+
+    ``date`` is always a real ``datetime.date`` on success (a year- or
+    month-only input is completed to the 1st so callers that just need *a* date
+    have one), and ``precision`` records how much was actually given, so a caller
+    that needs a real day (a schedule counting in days, say) can insist on it
+    instead of silently scheduling from an invented 1 January.
+
+    ``time`` is ``'HH:MM:SS'`` or None.  ``error`` is '' on success and otherwise
+    a short phrase naming what was wrong, fit to show the user directly.
+    """
+    date: Optional[datetime.date]
+    time: Optional[str]
+    precision: str
+    error: str
+
+    @property
+    def ok(self) -> bool:
+        """True if the input parsed."""
+        return not self.error
+
+
+def parse_time(raw) -> Optional[str]:
+    """Normalise ``HH``/``HH:MM``/``HH:MM:SS`` to ``'HH:MM:SS'``; None if unreadable.
+
+    Rejects out-of-range parts (``25:00``, ``18:75``) rather than rolling them
+    over, so a typo surfaces instead of quietly becoming a different time.
+    """
+    if raw is None:
+        return None
+    s = str(raw).strip()
+    if not s:
+        return None
+    parts = s.split(':')
+    if len(parts) > 3 or not all(p.strip().isdigit() for p in parts if p.strip() != ''):
+        return None
+    try:
+        h = int(parts[0])
+        m = int(parts[1]) if len(parts) > 1 and parts[1].strip() else 0
+        sec = int(parts[2]) if len(parts) > 2 and parts[2].strip() else 0
+    except (ValueError, IndexError):
+        return None
+    if 0 <= h < 24 and 0 <= m < 60 and 0 <= sec < 60:
+        return f"{h:02d}:{m:02d}:{sec:02d}"
+    return None
+
+
+def _split_date_time(s: str) -> tuple:
+    """Split a stamp into its date and time halves.
+
+    A ``T`` always separates them.  A space only does when what follows it looks
+    like a clock time (it carries a ``:``) because a space is *also* a legal
+    separator inside the date itself: ``2008 07 02`` is a date, while
+    ``2008-07-02 18:30`` is a date and a time.
+    """
+    upper = s.upper()
+    if 'T' in upper:
+        cut = upper.index('T')
+        return s[:cut].strip(), s[cut + 1:].strip()
+    if ' ' in s:
+        head, _, tail = s.rpartition(' ')
+        if ':' in tail:
+            return head.strip(), tail.strip()
+    return s.strip(), ''
+
+
+def split_stamp(raw) -> tuple:
+    """The date and time halves of a typed stamp, any trailing timezone dropped."""
+    return _split_date_time(_TZ_RE.sub('', str(raw or '').strip()).strip())
+
+
+def _read_date(part: str, dayfirst: Optional[bool]) -> tuple:
+    """Parse the date half → ``(date, precision, error)``."""
+    m = _COMPACT_RE.match(part)
+    if m:
+        y, mo, d = (int(g) for g in m.groups())
+        return _build(y, mo, d, 'day')
+
+    m = _YEAR_FIRST_RE.match(part)
+    if m:
+        year, month, day = m.groups()
+        if month is None:
+            return _build(int(year), 1, 1, 'year')
+        if day is None:
+            return _build(int(year), int(month), 1, 'month')
+        return _build(int(year), int(month), int(day), 'day')
+
+    m = _YEAR_LAST_RE.match(part)
+    if m:
+        a, b, year = (int(g) for g in m.groups())
+        # Only one ordering can be right when a part exceeds 12 (13/07/2008 has
+        # to be day-first), so try both and see how many survive.
+        day_first_ok = 1 <= b <= 12
+        month_first_ok = 1 <= a <= 12
+        if day_first_ok and month_first_ok:
+            # Genuinely ambiguous: 02/07/2008 is 2 July or 2 February depending
+            # on where you live. Honour an explicit choice, else refuse rather
+            # than pick one and be silently wrong.
+            if dayfirst is None:
+                return None, '', (f"{part!r} could be day-first or month-first: "
+                                  "write it year-first (2008-07-02)")
+            day, month = (a, b) if dayfirst else (b, a)
+        elif day_first_ok:
+            day, month = a, b
+        elif month_first_ok:
+            month, day = a, b
+        else:
+            return None, '', f"{part!r} has no valid month"
+        return _build(year, month, day, 'day')
+
+    return None, '', f"{part!r} is not a date"
+
+
+def _build(year: int, month: int, day: int, precision: str) -> tuple:
+    """Validate y/m/d into a real date, or report why it isn't one."""
+    if not 1 <= month <= 12:
+        return None, '', f"there is no month {month}"
+    try:
+        return datetime.date(year, month, day), precision, ''
+    except ValueError:
+        return None, '', (f"{year:04d}-{month:02d}-{day:02d} is not a real date")
+
+
+def parse_datetime(raw, *, dayfirst: Optional[bool] = None) -> ParsedDateTime:
+    """Read a date, optionally with a time, from something a user typed.
+
+    ``dayfirst`` resolves ``02/07/2008``: True reads it day-first, False
+    month-first, and the default (None) refuses it and says to write the date
+    year-first.  Year-first input is never ambiguous and never consults it.
+    """
+    if raw is None:
+        return ParsedDateTime(None, None, '', 'no date given')
+    date_part, time_part = split_stamp(raw)
+    if not date_part:
+        return ParsedDateTime(None, None, '', 'no date given')
+
+    date, precision, err = _read_date(date_part, dayfirst)
+    if err:
+        return ParsedDateTime(None, None, '', err)
+
+    if not time_part:
+        return ParsedDateTime(date, None, precision, '')
+
+    tod = parse_time(time_part)
+    if tod is None:
+        return ParsedDateTime(None, None, '', f"{time_part!r} is not a valid 24-hour time")
+    # A time implies a full date; without one we would be timing an invented day.
+    if precision != 'day':
+        return ParsedDateTime(None, None, '', f"{date_part!r} needs a full year-month-day "
+                                              "to carry a time")
+    return ParsedDateTime(date, tod, 'second' if tod[-2:] != '00' else 'minute', '')
+
+
+def parse_date(raw, *, dayfirst: Optional[bool] = None) -> Optional[datetime.date]:
+    """Just the date, or None if it won't parse. Any time given is ignored."""
+    return parse_datetime(raw, dayfirst=dayfirst).date
+
+
+def format_datetime(parsed: ParsedDateTime) -> str:
+    """Render a parse back out at the precision it was given."""
+    if parsed.date is None:
+        return ''
+    if parsed.precision == 'year':
+        return f"{parsed.date.year:04d}"
+    if parsed.precision == 'month':
+        return f"{parsed.date.year:04d}-{parsed.date.month:02d}"
+    if parsed.time:
+        return f"{parsed.date.isoformat()} {parsed.time}"
+    return parsed.date.isoformat()
+
+
+def parse_date_parts(raw, *, dayfirst: Optional[bool] = None) -> Optional[tuple]:
+    """``(year, month, day)`` for a typed date, or None: the shape the calendar
+    and date/time widgets work in.  A year- or month-only input completes to the
+    1st, as those widgets have always done."""
+    d = parse_datetime(raw, dayfirst=dayfirst).date
+    return (d.year, d.month, d.day) if d else None