primarysource 0.1.0__py3-none-any.whl

primarysource/index.py

@@ -0,0 +1,446 @@
+"""The keyword index every collection shares: SQLite FTS5, ranked by BM25 (PLAN.md §3, §5.7).
+
+One database per collection. Its shape:
+
+- `documents`: one row per document (id, title, declared unit, section count).
+- `sections`: one row per section, in reading order, with the section's units joined into a body.
+- `sections_fts`: an external-content FTS5 table over `sections` (document title, section title, body), kept in
+  step by triggers, tokenized `porter unicode61` so `encoded` finds `encoding` and `resume` finds `résumé`.
+
+How it is opened is the point of most of this module:
+
+- **Readers** (`open_read`) open `?mode=ro` and never create or migrate anything, so a shared server can run on a
+  read-only volume and can never damage the index it serves.
+- **Writers** (`open_write`) use WAL and a busy timeout, and `index_document` holds `BEGIN IMMEDIATE` around each
+  document, so two writers queue for the lock up front instead of failing half-way through.
+- **Both** check `PRAGMA user_version` against `SCHEMA_VERSION` and refuse a mismatch with a `LibError` whose
+  hint is the collection's rebuild command. There are no migrations: an index is derived data, rebuilt from the
+  corpus.
+- **A rebuild** (`rebuild`) writes a temporary file in the same directory and `os.replace`s it over the old index,
+  so a reader sees the old index or the new one, never a half-built one.
+
+Search (`search`) quotes every user term (`fts_query`), so FTS5 syntax in a question cannot raise. It asks for
+every term first; only when nothing has them all does it ask for any term, and says so with `relaxed`.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sqlite3
+import tempfile
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from primarysource.errors import LibError
+from primarysource.model import Document
+
+SCHEMA_VERSION = 1
+BUSY_TIMEOUT_MS = 15_000
+
+# Statements, not one script: `executescript` commits first, and the schema is created inside the writer's
+# `BEGIN IMMEDIATE` so two processes creating the same new index cannot both do it.
+_SCHEMA = (
+    "CREATE TABLE documents("
+    "doc_id TEXT PRIMARY KEY, title TEXT NOT NULL, unit TEXT NOT NULL, sections INTEGER NOT NULL)",
+    "CREATE TABLE sections("
+    "id INTEGER PRIMARY KEY, doc_id TEXT NOT NULL, section_id TEXT NOT NULL, ord INTEGER NOT NULL, "
+    "depth INTEGER NOT NULL, doc_title TEXT NOT NULL, title TEXT NOT NULL, body TEXT NOT NULL)",
+    "CREATE INDEX sections_doc ON sections(doc_id, ord)",
+    "CREATE VIRTUAL TABLE sections_fts USING fts5("
+    "doc_title, title, body, content='sections', content_rowid='id', tokenize='porter unicode61')",
+    "CREATE TRIGGER sections_ai AFTER INSERT ON sections BEGIN "
+    "INSERT INTO sections_fts(rowid, doc_title, title, body) VALUES (new.id, new.doc_title, new.title, new.body); "
+    "END",
+    "CREATE TRIGGER sections_ad AFTER DELETE ON sections BEGIN "
+    "INSERT INTO sections_fts(sections_fts, rowid, doc_title, title, body) "
+    "VALUES ('delete', old.id, old.doc_title, old.title, old.body); "
+    "END",
+    "CREATE TRIGGER sections_au AFTER UPDATE ON sections BEGIN "
+    "INSERT INTO sections_fts(sections_fts, rowid, doc_title, title, body) "
+    "VALUES ('delete', old.id, old.doc_title, old.title, old.body); "
+    "INSERT INTO sections_fts(rowid, doc_title, title, body) VALUES (new.id, new.doc_title, new.title, new.body); "
+    "END",
+    f"PRAGMA user_version = {SCHEMA_VERSION}",
+)
+
+
+# --- opening ---------------------------------------------------------------------------------------------------
+
+
+def _remedy(rebuild_command: str) -> str:
+    return f"run: {rebuild_command}"
+
+
+def _check_version(conn: sqlite3.Connection, path: Path, rebuild_command: str) -> None:
+    """Refuse an index built by another schema version, or a file that is not an index at all."""
+    try:
+        version = conn.execute("PRAGMA user_version").fetchone()[0]
+    except sqlite3.DatabaseError as error:
+        raise LibError(f"{path} is not a readable index: {error}", _remedy(rebuild_command)) from error
+    if version != SCHEMA_VERSION:
+        raise LibError(
+            f"the index at {path} has schema version {version}; this primarysource reads version {SCHEMA_VERSION}",
+            _remedy(rebuild_command),
+        )
+
+
+def open_read(path: Path, *, rebuild_command: str, busy_timeout_ms: int = BUSY_TIMEOUT_MS) -> sqlite3.Connection:
+    """A query connection: `?mode=ro`, no schema setup, version checked.
+
+    The file must already exist; a missing index is an error naming `rebuild_command`, never an empty database
+    created on the spot. A reader still waits up to `busy_timeout_ms` for a writer.
+    """
+    if not path.is_file():
+        raise LibError(f"no index at {path}", _remedy(rebuild_command))
+    try:
+        conn = sqlite3.connect(
+            f"{path.resolve().as_uri()}?mode=ro", uri=True, timeout=busy_timeout_ms / 1000, isolation_level=None
+        )
+    except sqlite3.Error as error:
+        raise LibError(f"cannot open the index at {path}: {error}", _remedy(rebuild_command)) from error
+    try:
+        conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
+        _check_version(conn, path, rebuild_command)
+    except BaseException:
+        conn.close()
+        raise
+    return conn
+
+
+def _has_tables(conn: sqlite3.Connection) -> bool:
+    return conn.execute("SELECT 1 FROM sqlite_master LIMIT 1").fetchone() is not None
+
+
+def _connect_write(path: Path, busy_timeout_ms: int) -> sqlite3.Connection:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # isolation_level=None: transactions are begun and ended here, explicitly, never implicitly by the driver.
+    conn = sqlite3.connect(path, timeout=busy_timeout_ms / 1000, isolation_level=None)
+    conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
+    return conn
+
+
+def open_write(path: Path, *, rebuild_command: str, busy_timeout_ms: int = BUSY_TIMEOUT_MS) -> sqlite3.Connection:
+    """A writer connection: WAL, a busy timeout, and the schema created if the file is new.
+
+    A file that is neither new nor at `SCHEMA_VERSION` is refused with a hint naming `rebuild_command`.
+    """
+    conn = _connect_write(path, busy_timeout_ms)
+    try:
+        try:
+            conn.execute("PRAGMA journal_mode = WAL")
+            conn.execute("BEGIN IMMEDIATE")
+        except sqlite3.DatabaseError as error:
+            raise LibError(f"{path} is not a writable index: {error}", _remedy(rebuild_command)) from error
+        try:
+            version = conn.execute("PRAGMA user_version").fetchone()[0]
+            if version == 0 and not _has_tables(conn):
+                for statement in _SCHEMA:
+                    conn.execute(statement)
+            else:
+                _check_version(conn, path, rebuild_command)
+            conn.execute("COMMIT")
+        except BaseException:
+            conn.execute("ROLLBACK")
+            raise
+    except BaseException:
+        conn.close()
+        raise
+    return conn
+
+
+# --- writing ---------------------------------------------------------------------------------------------------
+
+
+def _write_document(conn: sqlite3.Connection, document: Document) -> int:
+    conn.execute("DELETE FROM sections WHERE doc_id = ?", (document.id,))
+    conn.execute("DELETE FROM documents WHERE doc_id = ?", (document.id,))
+    conn.executemany(
+        "INSERT INTO sections(doc_id, section_id, ord, depth, doc_title, title, body) VALUES (?, ?, ?, ?, ?, ?, ?)",
+        [
+            (document.id, section.id, ord_, section.depth, document.title, section.title, "\n\n".join(section.units))
+            for ord_, section in enumerate(document.sections)
+        ],
+    )
+    conn.execute(
+        "INSERT INTO documents(doc_id, title, unit, sections) VALUES (?, ?, ?, ?)",
+        (document.id, document.title, str(document.unit), len(document.sections)),
+    )
+    return len(document.sections)
+
+
+def index_document(conn: sqlite3.Connection, document: Document) -> int:
+    """Replace one document's sections; returns how many were written.
+
+    Runs under `BEGIN IMMEDIATE`, so the write lock is taken before anything is read and a second writer waits
+    (up to the busy timeout) at the start instead of colliding in the middle. A failure rolls the whole document
+    back. Called inside a transaction the caller already holds, it joins that transaction and leaves the commit to
+    the caller.
+    """
+    own = not conn.in_transaction
+    if own:
+        conn.execute("BEGIN IMMEDIATE")
+    try:
+        written = _write_document(conn, document)
+        if own:
+            conn.execute("COMMIT")
+    except BaseException:
+        if own:
+            conn.execute("ROLLBACK")
+        raise
+    return written
+
+
+def remove_document(conn: sqlite3.Connection, doc_id: str) -> bool:
+    """Drop one document; True if it was there."""
+    own = not conn.in_transaction
+    if own:
+        conn.execute("BEGIN IMMEDIATE")
+    try:
+        conn.execute("DELETE FROM sections WHERE doc_id = ?", (doc_id,))
+        removed = conn.execute("DELETE FROM documents WHERE doc_id = ?", (doc_id,)).rowcount > 0
+        if own:
+            conn.execute("COMMIT")
+    except BaseException:
+        if own:
+            conn.execute("ROLLBACK")
+        raise
+    return removed
+
+
+def _quiesce(path: Path, rebuild_command: str, busy_timeout_ms: int) -> None:
+    """Empty the old index's WAL before it is replaced, or refuse.
+
+    A `-wal` file belongs to a database by name, not by content: frames left in `<index>-wal` would be replayed
+    onto the new file the next time a writer opens it. So the old WAL is checkpointed and truncated first, and if
+    a reader's open transaction prevents that, the rebuild stops with the old index untouched.
+    """
+    if not path.is_file():
+        return
+    try:
+        conn = sqlite3.connect(path, timeout=busy_timeout_ms / 1000, isolation_level=None)
+    except sqlite3.Error:
+        return
+    try:
+        conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}")
+        busy, _, _ = conn.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
+    except sqlite3.DatabaseError:
+        return  # not a database: nothing of it can be replayed, so it may simply be replaced
+    finally:
+        conn.close()
+    if busy:
+        raise LibError(
+            f"the index at {path} is being read, so its write-ahead log cannot be emptied before the rebuild",
+            f"retry when it is idle, or stop the servers reading it and run: {rebuild_command}",
+        )
+
+
+def rebuild(
+    path: Path,
+    documents: Iterable[Document],
+    *,
+    rebuild_command: str,
+    busy_timeout_ms: int = BUSY_TIMEOUT_MS,
+) -> int:
+    """Build a fresh index from `documents` and swap it in atomically; returns the number of sections.
+
+    The new index is written to a temporary file beside `path` and moved over it with `os.replace`, so readers see
+    the old index or the new one and never a partial one. If building fails, the old index is left as it was and
+    the temporary file is removed. The new file is published in rollback-journal mode, so a `mode=ro` reader on a
+    read-only volume can open it without creating `-wal`/`-shm` files; the next `open_write` switches it to WAL.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle, name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    os.close(handle)
+    temporary = Path(name)
+    try:
+        conn = _connect_write(temporary, busy_timeout_ms)
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            for statement in _SCHEMA:
+                conn.execute(statement)
+            written = sum(_write_document(conn, document) for document in documents)
+            conn.execute("INSERT INTO sections_fts(sections_fts) VALUES ('optimize')")
+            conn.execute("COMMIT")
+        finally:
+            conn.close()
+        _quiesce(path, rebuild_command, busy_timeout_ms)
+        try:
+            os.replace(temporary, path)
+        except PermissionError as error:
+            raise LibError(
+                f"cannot replace the index at {path} while another process has it open: {error}",
+                f"stop the servers reading it, then run: {rebuild_command}",
+            ) from error
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        Path(f"{temporary}-journal").unlink(missing_ok=True)
+        raise
+    return written
+
+
+# --- querying --------------------------------------------------------------------------------------------------
+
+# Filler that must not be a required term: "how is the value encoded" should not demand a section containing
+# "how", "is" and "the". A query made only of filler is still searched as typed. `and` and `or` typed as operators
+# are filler too; `not` is kept, because in a specification it is the word that matters.
+_FILLER = frozenset(
+    [
+        "a",
+        "an",
+        "the",
+        "of",
+        "for",
+        "to",
+        "in",
+        "on",
+        "at",
+        "by",
+        "with",
+        "from",
+        "as",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "do",
+        "does",
+        "did",
+        "and",
+        "or",
+        "what",
+        "which",
+        "who",
+        "whom",
+        "how",
+        "when",
+        "where",
+        "why",
+        "that",
+        "this",
+        "these",
+        "those",
+        "it",
+        "its",
+    ]
+)
+_WORD = re.compile(r"\w")
+
+
+def query_terms(raw: str) -> tuple[str, ...]:
+    """The searchable terms of `raw`: whitespace-separated tokens holding a word character, filler dropped."""
+    tokens = [token for token in raw.split() if _WORD.search(token)]
+    content = [token for token in tokens if token.strip("?.,;:!()\"'").lower() not in _FILLER]
+    return tuple(dict.fromkeys(content or tokens))
+
+
+def fts_query(raw: str, *, any_term: bool = False) -> str:
+    """A MATCH expression that FTS5 accepts whatever the user typed.
+
+    Every term is quoted as a phrase, with internal double quotes doubled (FTS5's own escape), so `set-of`,
+    `NEAR(`, `title:x`, `a*` and a stray `"` are searched as words instead of parsed as operators. Terms are ANDed,
+    or ORed with `any_term`. The trade is stated rather than hidden: FTS5 syntax does not work from a query box.
+    """
+    terms = query_terms(raw)
+    if not terms:
+        raise LibError("the query has no words to search for", "pass at least one word")
+    joiner = " OR " if any_term else " "
+    return joiner.join('"' + term.replace('"', '""') + '"' for term in terms)
+
+
+@dataclass(frozen=True, slots=True)
+class Hit:
+    """One matching section. `score` is higher-is-better: BM25 negated, times the collection's adjustment."""
+
+    doc_id: str
+    section_id: str
+    doc_title: str
+    title: str
+    snippet: str
+    score: float
+
+
+RankAdjust = Callable[[Hit, str], float]
+"""Given a hit and the raw query, a factor for its score: below 1 demotes, above 1 promotes (itulib demotes
+definitions and informative annexes by 0.6 unless the query asks what a term means)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Ranking:
+    """A collection's ranking: BM25 column weights and an optional adjustment of each hit.
+
+    `candidates` is how many BM25 hits beyond the requested page are fetched for `adjust` to reorder.
+    """
+
+    doc_title: float = 1.0
+    title: float = 4.0
+    body: float = 1.0
+    adjust: RankAdjust | None = None
+    candidates: int = 200
+
+    def bm25(self) -> str:
+        # Floats formatted here, never user text: the weights are part of the SQL, as bm25() requires constants.
+        return f"bm25(sections_fts, {float(self.doc_title)!r}, {float(self.title)!r}, {float(self.body)!r})"
+
+
+@dataclass(frozen=True, slots=True)
+class SearchResult:
+    """`relaxed` is true when no section held every term and these hits hold only some of them.
+
+    `next_start` is the `start` for the next page, or None at the end. No hits means nothing matched.
+    """
+
+    hits: tuple[Hit, ...]
+    relaxed: bool
+    next_start: int | None
+
+
+def _match(conn: sqlite3.Connection, expression: str, ranking: Ranking, fetch: int) -> list[Hit]:
+    order = ranking.bm25()
+    rows = conn.execute(
+        "SELECT s.doc_id, s.section_id, s.doc_title, s.title, "  # noqa: S608 - only formatted floats are interpolated
+        f"snippet(sections_fts, 2, '', '', ' … ', 24), {order} "
+        "FROM sections_fts JOIN sections AS s ON s.id = sections_fts.rowid "
+        f"WHERE sections_fts MATCH ? ORDER BY {order}, s.id LIMIT ?",
+        (expression, fetch),
+    ).fetchall()
+    return [Hit(row[0], row[1], row[2], row[3], row[4] or row[3], -row[5]) for row in rows]
+
+
+def search(
+    conn: sqlite3.Connection,
+    query: str,
+    *,
+    ranking: Ranking | None = None,
+    limit: int = 8,
+    start: int = 0,
+) -> SearchResult:
+    """The best sections for `query`, best first, `limit` from `start`.
+
+    Every term is required first. If no section holds them all and there is more than one term, any term will do
+    and the result says `relaxed`. `ranking.adjust`, when given, rescales each candidate and the candidates are
+    re-sorted before the page is cut.
+    """
+    ranking = ranking or Ranking()
+    fetch = start + limit + ranking.candidates
+    strict = fts_query(query)
+    hits = _match(conn, strict, ranking, fetch)
+    relaxed = False
+    if not hits:
+        loose = fts_query(query, any_term=True)
+        if loose != strict:
+            hits = _match(conn, loose, ranking, fetch)
+            relaxed = bool(hits)
+    if ranking.adjust is not None:
+        adjust = ranking.adjust
+        hits = [
+            Hit(hit.doc_id, hit.section_id, hit.doc_title, hit.title, hit.snippet, hit.score * adjust(hit, query))
+            for hit in hits
+        ]
+        hits.sort(key=lambda hit: -hit.score)  # stable: equal scores keep BM25 order
+    page = tuple(hits[start : start + limit])
+    more = len(hits) > start + limit
+    return SearchResult(page, relaxed, start + len(page) if more else None)

primarysource/iso/__init__.py

@@ -0,0 +1,51 @@
+"""ISO standards from the owner's own purchased PDFs.
+
+Placement is a personal volume: the files are the buyer's single-user copies, dropped into the collection's
+home (`$PRIMARYSOURCE_ISO_HOME`, else `$PRIMARYSOURCE_HOME/iso`) and imported with `primarysource iso import`.
+Nothing here fetches and nothing is copied into an image. The PDF itself is not copied either: the import stores
+the extracted text and a record of the source (sha256, size, mtime), and builds the core FTS5 index. Reading a
+PDF needs `pypdf` (the `[iso]` extra) at import time only; serving reads the stored extraction. `docs/iso.md` is
+the user-facing description.
+"""
+
+from __future__ import annotations
+
+from primarysource.iso.designation import DOC as ISO_DOC
+from primarysource.model import Unit
+from primarysource.refs import Ref, RefGrammar
+from primarysource.registry import Collection
+
+ISO_SECTION = r"[0-9A-Za-z][0-9A-Za-z.\-]*"
+"""A clause as the PDF bookmarks number it (`6.5.2`, `A`, `A.1`) or the slug of an unnumbered bookmark."""
+
+
+class _Refs:
+    """The collection's ref parser: `library.parse_ref` (which also takes the `iso:` prefix and a printed
+    designation), imported on first use so the collection loads without its reader."""
+
+    _grammar = RefGrammar(ISO_DOC, ISO_SECTION)
+
+    def parse(self, text: str) -> Ref:
+        from primarysource.iso.library import parse_ref
+
+        return parse_ref(text)
+
+    def format(self, ref: Ref) -> str:
+        return self._grammar.format(ref)
+
+
+ISO = Collection(
+    name="iso",
+    title="ISO standards from the owner's own purchased PDFs",
+    prefix="iso_",
+    unit=Unit.SENTENCE,
+    grammar=_Refs(),
+    server="primarysource.iso.server:server",
+    cli="primarysource.iso.cli:main",
+    identify="primarysource.iso.identify:identify",
+)
+"""Refs: `iso:9899@2024§6.5.2¶3`. The document is `<number>@<year>` (the newest imported year when omitted); a
+printed designation such as `ISO/IEC 9899:2024§6.5.2` is accepted too. `¶n` is the nth sentence of the clause's
+span, because a PDF gives sentences, not paragraphs."""
+
+__all__ = ["ISO", "ISO_DOC", "ISO_SECTION"]

primarysource/iso/cli.py

@@ -0,0 +1,98 @@
+"""`primarysource iso ...`: the collection's own commands.
+
+primarysource iso import [FILE] [--designation "ISO/IEC 9899:2024"]   # no FILE: every PDF in the iso home
+primarysource iso index
+primarysource iso docs
+primarysource iso outline <doc> [--start N] [--limit N]
+primarysource iso read <ref> [--max-tokens N]
+primarysource iso search <query> [--doc DOC] [--limit N] [--start N]
+primarysource iso cite <ref>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from primarysource.errors import LibError
+from primarysource.fsutil import bulk_lock
+from primarysource.iso import importer, library
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="primarysource iso", description="ISO standards from your own PDFs")
+    commands = parser.add_subparsers(dest="command", required=True)
+    imp = commands.add_parser("import", help="extract and index your PDFs (default: every PDF in the iso home)")
+    imp.add_argument(
+        "file", nargs="?", type=Path, help="one PDF; without it, every new or changed PDF in the iso home"
+    )
+    imp.add_argument("--designation", help="as printed on the cover, e.g. 'ISO/IEC 9899:2024'")
+    commands.add_parser("index", help="rebuild the search index from what is imported")
+    commands.add_parser("docs", help="what is imported")
+    out = commands.add_parser("outline", help="a standard's clauses with refs")
+    out.add_argument("doc")
+    out.add_argument("--start", type=int, default=0)
+    out.add_argument("--limit", type=int, default=200)
+    read = commands.add_parser("read", help="read by ref")
+    read.add_argument("ref")
+    read.add_argument("--max-tokens", type=int, default=2000)
+    search = commands.add_parser("search", help="find clauses containing words")
+    search.add_argument("query")
+    search.add_argument("--doc")
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--start", type=int, default=0)
+    commands.add_parser("cite", help="the citation for a ref").add_argument("ref")
+    return parser
+
+
+def _out(text: str) -> int:
+    sys.stdout.write(text if text.endswith("\n") else text + "\n")
+    return 0
+
+
+def _line(result: importer.ImportResult) -> str:
+    line = (
+        f"imported iso:{result.doc} ({result.designation}): {result.sections} sections, "
+        f"{result.headings_found} headings found ({result.segmenter})"
+    )
+    return line + (f"\n  note: {result.note}" if result.note else "")
+
+
+def _import(args: argparse.Namespace, home: Path) -> int:
+    with bulk_lock(home, "import"):
+        if args.file is not None:
+            result = importer.import_file(home, args.file, args.designation)
+            return _out(_line(result))
+        if args.designation:
+            raise LibError("--designation needs a FILE", "", "primarysource iso import FILE --designation '...'")
+        done, skipped = importer.import_folder(home)
+    lines = [_line(r) for r in done]
+    lines += [f"skipped {name}: {why}" for name, why in skipped]
+    if not lines:
+        lines = [f"no new or changed PDFs in {home}"]
+    return _out("\n".join(lines))
+
+
+def main(argv: Sequence[str]) -> int:
+    args = _parser().parse_args(list(argv))
+    home = library.default_home()
+    try:
+        if args.command == "import":
+            return _import(args, home)
+        if args.command == "index":
+            with bulk_lock(home, "import"):
+                return _out(f"indexed {importer.rebuild_index(home)} sections")
+        if args.command == "docs":
+            return _out(library.docs())
+        if args.command == "outline":
+            return _out(library.outline(args.doc, start=args.start, limit=args.limit))
+        if args.command == "read":
+            return _out(library.read(args.ref, max_tokens=args.max_tokens))
+        if args.command == "search":
+            return _out(library.search(args.query, doc=args.doc, limit=args.limit, start=args.start))
+        return _out(library.cite(args.ref))
+    except LibError as exc:
+        print(exc.as_text(), file=sys.stderr)
+        return 1

primarysource/iso/designation.py

@@ -0,0 +1,95 @@
+"""ISO designations, as printed (`ISO/IEC 9899:2024`, `ISO 8601-1:2019/Amd 1:2022`, `ISO/IEC TR 24772-1:2019`) and
+as the ISO store names its files (`ISO_IEC_9899_2024(en).pdf`).
+
+The collection's document id is `<number>@<year>` (`9899@2024`, `8601-1@2019`), with `+amd1-2022` or `+cor1-2022`
+for an amendment or a corrigendum. It is not the designation itself, because `:` already means a line range in a
+ref and `/` is not a safe file name.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from primarysource.errors import LibError
+
+_PATTERN = re.compile(
+    r"(?P<pub>ISO(?:[/_ ]IEC)?(?:[/_ ]IEEE)?)"
+    r"(?:[/_ ](?P<kind>TS|TR|PAS|Guide))?"
+    r"[/_ ]+(?P<number>\d{1,5}(?:-\d{1,3})*)"
+    r"[_:\- ](?P<year>(?:19|20)\d{2})"
+    r"(?:\s*[/_ ]\s*(?P<supp>Amd|Cor)[_ .]*(?P<sn>\d{1,2})[_:\- ](?P<syear>(?:19|20)\d{2}))?",
+    re.IGNORECASE,
+)
+
+DOC = r"\d{1,5}(?:-\d{1,3})*(?:@(?:19|20)\d{2}(?:\+(?:amd|cor)\d{1,2}-(?:19|20)\d{2})?)?"
+"""A document id in a ref: `9899`, `9899@2024`, `27001@2022+amd1-2024`."""
+
+_DOC = re.compile(r"(?P<number>\d{1,5}(?:-\d{1,3})*)(?:@(?P<rest>.+))?")
+
+
+@dataclass(frozen=True, slots=True)
+class Designation:
+    publisher: str
+    kind: str
+    number: str
+    year: int
+    supplement: str = ""
+    """`Amd 1:2022` or `Cor 1:2022`, or empty for the standard itself."""
+
+    @property
+    def label(self) -> str:
+        """The designation as ISO prints it: `ISO/IEC TR 24772-1:2019/Amd 1:2022`."""
+        head = self.publisher + (f" {self.kind}" if self.kind else "")
+        tail = f"/{self.supplement}" if self.supplement else ""
+        return f"{head} {self.number}:{self.year}{tail}"
+
+    @property
+    def doc(self) -> str:
+        """The id refs use: `9899@2024`, `27001@2022+amd1-2024`."""
+        suffix = ""
+        if self.supplement:
+            kind, _, rest = self.supplement.partition(" ")
+            number, _, year = rest.partition(":")
+            suffix = f"+{kind.lower()}{number}-{year}"
+        return f"{self.number}@{self.year}{suffix}"
+
+    @property
+    def key(self) -> str:
+        """The doc id as a file name: `9899_2024`, `27001_2022_amd1-2024`."""
+        return self.doc.replace("@", "_").replace("+", "_")
+
+
+def _from_match(match: re.Match[str]) -> Designation:
+    publisher = "/".join(part.upper() for part in re.split(r"[/_ ]", match["pub"]))
+    kind = match["kind"] or ""
+    kind = "Guide" if kind.lower() == "guide" else kind.upper()
+    supplement = ""
+    if match["supp"]:
+        supplement = f"{match['supp'].capitalize()} {int(match['sn'])}:{match['syear']}"
+    return Designation(publisher, kind, match["number"], int(match["year"]), supplement)
+
+
+def parse(text: str) -> Designation:
+    """A designation as printed (`ISO/IEC 9899:2024`), or a `LibError` that shows the expected form."""
+    match = _PATTERN.fullmatch(text.strip())
+    if match is None:
+        raise LibError(
+            f"not an ISO designation: {text!r}",
+            "write it as printed on the cover, e.g. 'ISO/IEC 9899:2024' or 'ISO 8601-1:2019/Amd 1:2022'",
+        )
+    return _from_match(match)
+
+
+def from_filename(name: str) -> Designation | None:
+    """The designation an ISO store file name carries (`ISO_IEC_9899_2024(en).pdf`), or None."""
+    match = _PATTERN.search(name)
+    return _from_match(match) if match else None
+
+
+def split_doc(token: str) -> tuple[str, str | None]:
+    """A ref's document token as (number, the part after `@` or None): `9899@2024` is ('9899', '2024')."""
+    match = _DOC.fullmatch(token.strip())
+    if match is None or not re.fullmatch(DOC, token.strip()):
+        raise LibError(f"not an ISO document: {token!r}", "use the number and year, e.g. 9899@2024, or just 9899")
+    return match["number"], match["rest"]