primarysource 0.1.0__py3-none-any.whl

primarysource/usbids/parse.py

@@ -0,0 +1,283 @@
+"""A bounded parser for the `usb.ids` format, and the ref spelling of its entries.
+
+The file is line-oriented. A `#` line is a comment (the first ones carry `# Version:` and `# Date:`), a blank line
+is nothing, and every other line is `<id>  <name>` (two spaces) indented by zero to two tabs. At column zero a
+line is either a vendor (`1d6b  Linux Foundation`) or a section record led by an upper-case tag (`C 09  Hub`). One
+tab is a child of the last column-zero entry (a device of a vendor, a subclass of a class, a usage of a usage
+page, a dialect of a language), two tabs a child of the last one-tab entry (an interface of a device, a protocol
+of a subclass). The sections the file has today, from its own `# Syntax:` comments:
+
+    (none)  vendor > device > interface     C     class > subclass > protocol
+    AT      audio terminal type             HID   HID descriptor type
+    R       HID item type                   BIAS  physical descriptor bias
+    PHY     physical descriptor item type   HUT   usage page > usage
+    L       language > dialect              HCC   HID country code (decimal)
+    VT      video terminal type
+
+Nothing here reads a file or the network. `parse` takes bytes and `Limits`, never trusts a line, and reports a
+line it cannot place as a `Problem` instead of guessing: the real file parses with none. Ids are lower-cased,
+names are kept as written, less surrounding space (a line that is not valid UTF-8 is read as Latin-1
+and counted), and a repeated id keeps its first entry and is reported.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from primarysource.errors import LibError
+
+SECTION_REF = {
+    "vendor": "vendor",
+    "class": "class",
+    "at": "at",
+    "hid": "hid",
+    "item": "item",
+    "bias": "bias",
+    "phy": "phy",
+    "hut": "hut",
+    "lang": "lang",
+    "hcc": "hcc",
+    "vt": "vt",
+}
+"""The first path part of a non-vendor ref, by section name. A vendor ref has no section part: `usbids:1d6b`."""
+
+TAGS = {
+    "C": "class",
+    "AT": "at",
+    "HID": "hid",
+    "R": "item",
+    "BIAS": "bias",
+    "PHY": "phy",
+    "HUT": "hut",
+    "L": "lang",
+    "HCC": "hcc",
+    "VT": "vt",
+}
+"""The file's tag for each section."""
+
+LEVELS = {
+    "vendor": ("vendor", "device", "interface"),
+    "class": ("class", "subclass", "protocol"),
+    "at": ("terminal type",),
+    "hid": ("descriptor type",),
+    "item": ("item type",),
+    "bias": ("bias",),
+    "phy": ("item type",),
+    "hut": ("usage page", "usage"),
+    "lang": ("language", "dialect"),
+    "hcc": ("country code",),
+    "vt": ("terminal type",),
+}
+"""What each indentation level of a section is called, for `usbids_lookup` output."""
+
+_HEX2 = r"[0-9a-f]{2}"
+_HEX4 = r"[0-9a-f]{4}"
+ID_PATTERNS: dict[str, tuple[str, ...]] = {
+    "vendor": (_HEX4, _HEX4, r"[0-9a-f]{2,4}"),
+    "class": (_HEX2, _HEX2, _HEX2),
+    "at": (_HEX4,),
+    "hid": (_HEX2,),
+    "item": (_HEX2,),
+    "bias": (r"[0-9a-f]{1,2}",),
+    "phy": (_HEX2,),
+    "hut": (_HEX2, r"[0-9a-f]{3,4}"),
+    "lang": (_HEX4, _HEX2),
+    "hcc": (r"[0-9]{2}",),
+    "vt": (_HEX4,),
+}
+"""The shape of the id at each level. `hcc` is decimal (the file says HID country codes are 00 to 35)."""
+
+_ID = {section: tuple(re.compile(p) for p in patterns) for section, patterns in ID_PATTERNS.items()}
+_LINE = re.compile(r"(?P<tabs>\t{0,3})(?:(?P<tag>[A-Z]{1,4}) )?(?P<id>[0-9A-Za-z]{1,8})  +(?P<name>\S.*)")
+_VERSION = re.compile(r"#\s*Version:\s*(\S+)")
+_DATE = re.compile(r"#\s*Date:\s*(.+?)\s*$")
+_CONTROL = re.compile(r"[\x00-\x08\x0a-\x1f\x7f]")
+
+
+@dataclass(frozen=True, slots=True)
+class Limits:
+    """Ceilings on what a parse accepts. The real file measures 730,605 bytes, 25,705 lines, the longest line
+    160 characters."""
+
+    data_bytes: int = 8_000_000
+    lines: int = 200_000
+    line_chars: int = 512
+    entries: int = 200_000
+    problems: int = 1_000
+    """Problems are counted without limit but only this many are kept."""
+
+
+@dataclass(frozen=True, slots=True)
+class Entry:
+    """One record: `section`, the ids from the top down (`("1d6b", "0002")`), the name and its 1-based line."""
+
+    section: str
+    key: tuple[str, ...]
+    name: str
+    line: int
+
+    @property
+    def ref(self) -> str:
+        return format_ref(self.section, self.key)
+
+    @property
+    def level_name(self) -> str:
+        return LEVELS[self.section][len(self.key) - 1]
+
+
+@dataclass(frozen=True, slots=True)
+class Problem:
+    line: int
+    reason: str
+
+
+@dataclass(slots=True)
+class UsbIds:
+    """A parsed file: entries in file order, the children of each, and what was wrong."""
+
+    entries: dict[tuple[str, tuple[str, ...]], Entry] = field(default_factory=dict)
+    children: dict[tuple[str, tuple[str, ...]], list[Entry]] = field(default_factory=dict)
+    version: str = ""
+    date: str = ""
+    problems: list[Problem] = field(default_factory=list)
+    problem_count: int = 0
+    latin1_lines: int = 0
+    """Lines that were not valid UTF-8 and were read as Latin-1."""
+
+    def get(self, section: str, key: tuple[str, ...]) -> Entry | None:
+        return self.entries.get((section, key))
+
+    def kids(self, entry: Entry) -> list[Entry]:
+        return self.children.get((entry.section, entry.key), [])
+
+    def counts(self) -> dict[str, int]:
+        """Entries per kind in first-seen order: `vendor`, `device`, `class`, `subclass`, `protocol`, `usage page`,
+        `usage`, `language`, `dialect`, and one count under the section's own name (`at`, `hid`, `item`, `bias`,
+        `phy`, `hcc`, `vt`) for the single-level tables."""
+        out: dict[str, int] = {}
+        for entry in self.entries.values():
+            label = entry.level_name if entry.section in ("vendor", "class", "hut", "lang") else entry.section
+            out[label] = out.get(label, 0) + 1
+        return out
+
+
+def parse(data: bytes, limits: Limits | None = None) -> UsbIds:
+    """Parse `usb.ids` bytes. Raises `LibError` for input that is not this format at all (too large,
+    NUL bytes, too many lines or entries); a bad line inside an otherwise sound file is a `Problem`."""
+    limits = limits or Limits()
+    if len(data) > limits.data_bytes:
+        raise LibError(f"usb.ids input is {len(data):,} bytes, over the {limits.data_bytes:,} limit", "")
+    if b"\x00" in data:
+        raise LibError("usb.ids input contains NUL bytes: this is not the text file", "")
+    raw_lines = data.removeprefix(b"\xef\xbb\xbf").split(b"\n")
+    if len(raw_lines) > limits.lines:
+        raise LibError(f"usb.ids input has over {limits.lines:,} lines", "")
+    ids = UsbIds()
+
+    def problem(number: int, reason: str) -> None:
+        ids.problem_count += 1
+        if len(ids.problems) < limits.problems:
+            ids.problems.append(Problem(number, reason))
+
+    parents: list[Entry | None] = [None, None, None]
+    for number, raw_bytes in enumerate(raw_lines, 1):
+        try:
+            raw = raw_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            # The published file is UTF-8 with a few Latin-1 bytes (an acute accent written as 0xB4)
+            raw = raw_bytes.decode("latin-1")
+            ids.latin1_lines += 1
+        line = raw.rstrip(" \t\r")
+        if not line:
+            continue
+        if line.startswith("#"):
+            if not ids.version and (m := _VERSION.match(line)):
+                ids.version = m[1]
+            elif not ids.date and (m := _DATE.match(line)):
+                ids.date = m[1]
+            continue
+        if len(line) > limits.line_chars:
+            problem(number, f"line over {limits.line_chars} characters")
+            continue
+        if _CONTROL.search(line):
+            problem(number, "control character")
+            continue
+        match = _LINE.fullmatch(line)
+        if match is None:
+            problem(number, "not '<id>  <name>'")
+            continue
+        level = len(match["tabs"])
+        tag = match["tag"]
+        if level > 2 or (level > 0 and tag):
+            problem(number, "indentation or tag not allowed here")
+            continue
+        if level == 0:
+            if tag is None:
+                section = "vendor"
+            elif tag in TAGS:
+                section = TAGS[tag]
+            else:
+                problem(number, f"unknown section tag {tag!r}")
+                parents[:] = [None, None, None]
+                continue
+            parent_key: tuple[str, ...] = ()
+        else:
+            parent = parents[level - 1]
+            if parent is None:
+                problem(number, "indented line with no parent")
+                continue
+            section, parent_key = parent.section, parent.key
+        patterns = _ID[section]
+        if level >= len(patterns):
+            problem(number, f"a {section} section has no level {level}")
+            continue
+        entry_id = match["id"].lower()
+        if patterns[level].fullmatch(entry_id) is None:
+            problem(number, f"{entry_id!r} is not a valid {LEVELS[section][level]} id")
+            continue
+        entry = Entry(section, (*parent_key, entry_id), match["name"], number)
+        index = (entry.section, entry.key)
+        if index in ids.entries:
+            problem(number, f"duplicate {entry.ref}")
+            parents[level:] = [None] * (3 - level)
+            continue
+        if len(ids.entries) >= limits.entries:
+            raise LibError(f"usb.ids input has over {limits.entries:,} entries", "")
+        ids.entries[index] = entry
+        if level > 0:
+            ids.children.setdefault((section, parent_key), []).append(entry)
+        parents[level:] = [entry] + [None] * (2 - level)
+    return ids
+
+
+_VENDOR_REF = re.compile(r"(?P<v>[0-9a-f]{4})(?::(?P<d>[0-9a-f]{4})(?::(?P<i>[0-9a-f]{2,4}))?)?")
+_SECTION_REF = re.compile(r"(?P<s>[a-z]+)(?P<path>(?:/[0-9a-f]{1,4}){1,3})")
+
+
+def format_ref(section: str, key: tuple[str, ...]) -> str:
+    """`usbids:1d6b:0002` for the vendor section, `usbids:class/09/00` for the others."""
+    if section == "vendor":
+        return "usbids:" + ":".join(key)
+    return f"usbids:{section}/" + "/".join(key)
+
+
+def parse_ref(text: str) -> tuple[str, tuple[str, ...]]:
+    """`usbids:1d6b:0002`, `1d6b:0002`, `usbids:class/09/00/02` -> (section, ids). Raises `LibError` on anything
+    else: a string that names nothing is refused, never guessed at."""
+    cleaned = text.strip().lower()
+    if len(cleaned) > 64:
+        raise LibError("not a usbids ref: too long", "")
+    cleaned = cleaned.removeprefix("usbids:")
+    if (m := _VENDOR_REF.fullmatch(cleaned)) is not None:
+        return "vendor", tuple(g for g in (m["v"], m["d"], m["i"]) if g)
+    if (m := _SECTION_REF.fullmatch(cleaned)) is not None and m["s"] in SECTION_REF and m["s"] != "vendor":
+        key = tuple(m["path"].split("/")[1:])
+        patterns = _ID[m["s"]]
+        if len(key) <= len(patterns) and all(p.fullmatch(k) for p, k in zip(patterns, key, strict=False)):
+            return m["s"], key
+    names = ", ".join(sorted(set(SECTION_REF) - {"vendor"}))
+    raise LibError(
+        f"not a usbids ref: {text!r}",
+        f"expected usbids:<vid>[:<pid>] (hex) or usbids:<section>/<id>[/<id>...] with section one of {names}",
+    )

primarysource/usbids/server.py

@@ -0,0 +1,55 @@
+"""MCP server for the usbids collection: `primarysource mcp --collection usbids`.
+
+Imported only when served, so `mcp` (the `[mcp]` extra) is needed only then. Tools carry the `usbids_` prefix,
+answer in text with the fixed footer, read the local database only (none writes or fetches), and turn a
+`LibError` into an MCP tool error whose text names the remedy.
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from primarysource import __version__
+from primarysource.scaffold import add_tools
+from primarysource.usbids import tools
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, idempotent_hint=True, destructive_hint=False, open_world_hint=False)
+
+INSTRUCTIONS = (
+    "The USB ID Database (usb.ids from the linux-usb.org USB ID Repository), imported by the user: vendor and "
+    "product ids, device classes, HID usages, languages and other lookup tables. It names things; it is not a USB "
+    "specification. Loop: usbids_search('<name>') -> usbids_lookup('<ref>'). Refs: 'usbids:1d6b' (vendor), "
+    "'usbids:1d6b:0002' (device), 'usbids:class/09/00/02' (class/subclass/protocol), 'usbids:hut/01/002' (HID "
+    "usage). usbids_classify('09', '00', '02') decodes a class code triple. The cite: footer line names the "
+    "snapshot. If the database is not imported, the error says how."
+)
+
+
+def usbids_lookup(ref: str, max_tokens: int = 2000) -> str:
+    """Read one entry by ref with its parents and children. ref: 'usbids:1d6b' (a vendor, lists its devices),
+    'usbids:1d6b:0002' (a device), 'usbids:class/09' (a class, lists subclasses), 'usbids:hut/01' (a HID usage
+    page), 'usbids:1d6b¶40' (that listing from its 40th line). A 'next: <ref>' footer line is the ref that reads
+    the next page: pass it back as ref."""
+    return tools.lookup(ref, max_tokens=max_tokens)
+
+
+def usbids_search(text: str, section: str | None = None, limit: int = 20, start: int = 0) -> str:
+    """Find entries whose name contains every word of text (a vendor's name counts for its devices). One line per
+    hit: '<ref>  <name>'. section: vendor (vendors, devices, interfaces) | class | hut | lang | at | hid | item |
+    bias | phy | hcc | vt. A 'next: start=N' footer line means call again with start=N (a 0-based offset)."""
+    return tools.search(text, section=section, limit=limit, start=start)
+
+
+def usbids_classify(base_class: str, subclass: str | None = None, protocol: str | None = None) -> str:
+    """Name a USB class code triple (hex, with or without 0x): usbids_classify('09', '00', '02')."""
+    return tools.classify(base_class, subclass=subclass, protocol=protocol)
+
+
+def usbids_sections() -> str:
+    """The imported snapshot: version, date, sha256, source, licence and entry counts per section."""
+    return tools.sections()
+
+
+server = MCPServer("primarysource-usbids", version=__version__, instructions=INSTRUCTIONS)
+add_tools(server, (usbids_lookup, usbids_search, usbids_classify, usbids_sections), annotations=READ_ONLY)

primarysource/usbids/store.py

@@ -0,0 +1,80 @@
+"""Where the imported `usb.ids` lives and how it is read back.
+
+`$PRIMARYSOURCE_HOME/usbids/usb.ids` is the file exactly as served; `manifest.json` beside it records its URL,
+sha256, size, the file's own `# Version:` and `# Date:`, when it was fetched, the server's validators and whether
+the digest was the pinned one. Reading parses once per (path, mtime, size) and refuses a file whose sha256 no
+longer matches the manifest.
+
+Placement: the database is distributable under GPL-2.0-or-later or BSD-3-Clause (docs/usbids.md), so a built image
+may carry it as a layer; the importer writes the same layout either way.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from primarysource.errors import LibError
+from primarysource.home import collection_home
+from primarysource.usbids.parse import Limits, UsbIds, parse
+
+FILE = "usb.ids"
+MANIFEST = "manifest.json"
+IMPORT = "primarysource usbids import"
+LICENCE = "GPL-2.0-or-later OR BSD-3-Clause"
+
+
+def home() -> Path:
+    return collection_home("usbids")
+
+
+def read_manifest(base: Path) -> dict[str, Any]:
+    path = base / MANIFEST
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as exc:
+        raise LibError(f"{path} is not a readable manifest", "", f"delete {path}, then {IMPORT} --force") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("file"), dict):
+        raise LibError(f"{path} is not a readable manifest", "", f"delete {path}, then {IMPORT} --force")
+    return dict(data["file"])
+
+
+@dataclass(frozen=True, slots=True)
+class Loaded:
+    ids: UsbIds
+    manifest: dict[str, Any]
+    sha256: str
+    path: Path
+
+
+@lru_cache(maxsize=4)
+def _load(path: str, mtime_ns: int, size: int) -> tuple[UsbIds, str]:
+    data = Path(path).read_bytes()
+    return parse(data, Limits()), hashlib.sha256(data).hexdigest()
+
+
+def load(base: Path | None = None) -> Loaded:
+    """The imported database, or a `LibError` that names the import command."""
+    root = base or home()
+    path = root / FILE
+    if not path.is_file():
+        raise LibError(f"usb.ids is not imported (looked in {root})", "", IMPORT)
+    stat = path.stat()
+    ids, digest = _load(str(path), stat.st_mtime_ns, stat.st_size)
+    manifest = read_manifest(root)
+    recorded = manifest.get("sha256")
+    if recorded and recorded != digest:
+        raise LibError(
+            f"{path} has sha256 {digest}, but the manifest recorded {recorded}: the file changed after import",
+            "",
+            IMPORT + " --force",
+        )
+    if not ids.entries:
+        raise LibError(f"{path} holds no usb.ids entries", "", IMPORT + " --force")
+    return Loaded(ids, manifest, digest, path)

primarysource/usbids/tools.py

@@ -0,0 +1,174 @@
+"""The usbids readers: lookup, search, classify and a summary. Plain text with the core's fixed footer.
+
+Each takes the imported database from `store.load()` and never writes or fetches. A missing database is an
+error whose `action` is the import command; a ref that names nothing is a `LibError` too, with a hint, so an empty
+result always means a search matched nothing.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from primarysource import budget, cursor
+from primarysource.errors import LibError
+from primarysource.render import next_start, render
+from primarysource.usbids import store
+from primarysource.usbids.parse import SECTION_REF, Entry, UsbIds, format_ref, parse_ref
+
+MAX_QUERY = 200
+MAX_TERMS = 8
+MAX_LIMIT = 200
+_WORD = re.compile(r"[a-z0-9]+")
+_HEX2 = re.compile(r"[0-9a-fA-F]{1,2}")
+
+
+def _cite(loaded: store.Loaded, entry: Entry | None = None) -> str:
+    ids = loaded.ids
+    head = f"USB ID Database usb.ids {ids.version or 'unversioned'}" + (f" ({ids.date})" if ids.date else "")
+    return f"{head}, {entry.ref}" if entry else head
+
+
+def _line(entry: Entry) -> str:
+    return f"{entry.ref}  {entry.name}"
+
+
+def _ancestors(ids: UsbIds, entry: Entry) -> list[Entry]:
+    found: list[Entry] = []
+    for depth in range(1, len(entry.key)):
+        parent = ids.get(entry.section, entry.key[:depth])
+        if parent is not None:
+            found.append(parent)
+    return found
+
+
+def lookup(ref: str, max_tokens: int = 2000, base: Path | None = None) -> str:
+    """One entry by ref, its ancestors and its children, paged by token budget. `<ref>¶n` starts at line n of that
+    listing; the `next:` footer is the ref that reads the next page."""
+    text, line = cursor.split_para(ref)
+    section, key = parse_ref(text)
+    loaded = store.load(base)
+    ids = loaded.ids
+    entry = ids.get(section, key)
+    if entry is None:
+        parent = ids.get(section, key[:-1]) if len(key) > 1 else None
+        if parent is not None:
+            raise LibError(
+                f"{format_ref(section, key)} is not listed; its {parent.level_name} is {parent.name!r}",
+                f"usbids_lookup('{parent.ref}') lists what is under it",
+            )
+        raise LibError(
+            f"{format_ref(section, key)} is not in usb.ids {ids.version}", "usbids_search finds an entry by name"
+        )
+    units = [f"{_line(entry)}  [{entry.level_name}]"]
+    units += [f"within: {_line(a)}  [{a.level_name}]" for a in _ancestors(ids, entry)]
+    units += [f"  {_line(kid)}" for kid in ids.kids(entry)]
+    if max_tokens < 1:
+        raise LibError("max_tokens must be positive", "")
+    page = budget.page(units, cursor.first_unit(line, len(units), "lines", ref), max_tokens)
+    footer = {
+        "cite": _cite(loaded, entry),
+        "unit": "line",
+        "span": f"{page.first}-{page.last} of {page.total}",
+        "next": cursor.read_next(entry.ref, page),
+    }
+    return render("\n".join(page.units), footer)
+
+
+def search(
+    text: str,
+    section: str | None = None,
+    limit: int = 20,
+    start: int = 0,
+    base: Path | None = None,
+) -> str:
+    """Entries whose name contains every word of `text` (a vendor's name counts for its devices), best first."""
+    if section is not None and section not in SECTION_REF:
+        raise LibError(f"unknown section {section!r}", "one of " + ", ".join(sorted(SECTION_REF)))
+    if len(text) > MAX_QUERY:
+        raise LibError(f"query is over {MAX_QUERY} characters", "")
+    terms = _WORD.findall(text.lower())[:MAX_TERMS]
+    if not terms:
+        raise LibError("query has no letters or digits", "give a name or part of one, e.g. 'hub' or 'logitech'")
+    if not 1 <= limit <= MAX_LIMIT or start < 0:
+        raise LibError(f"limit must be 1 to {MAX_LIMIT} and start (0-based) 0 or more", "")
+    loaded = store.load(base)
+    ids = loaded.ids
+    hits: list[tuple[int, int, Entry, str]] = []
+    for order, entry in enumerate(ids.entries.values()):
+        if section is not None and entry.section != section:
+            continue
+        shown = entry.name
+        hay = entry.name.lower()
+        if entry.section == "vendor" and len(entry.key) > 1:
+            owner = ids.get("vendor", entry.key[:1])
+            if owner is not None:
+                hay = f"{owner.name.lower()} {hay}"
+                shown = f"{owner.name} / {entry.name}"
+        if not all(t in hay for t in terms):
+            continue
+        words = _WORD.findall(hay)
+        score = sum(3 if t in words else 2 if any(w.startswith(t) for w in words) else 1 for t in terms)
+        hits.append((-score, order, entry, shown))
+    hits.sort(key=lambda h: (h[0], h[1]))
+    window = hits[start : start + limit]
+    body = "\n".join(f"{e.ref}  {shown}" for _, _, e, shown in window) if window else f"no entry matches {text!r}"
+    footer = {"cite": _cite(loaded), "unit": "line"}
+    if window:
+        footer["span"] = f"{start + 1}-{start + len(window)} of {len(hits)}"
+    footer["next"] = next_start(start + limit if start + limit < len(hits) else None)
+    return render(body, footer)
+
+
+def _two_hex(value: str, what: str) -> str:
+    if not _HEX2.fullmatch(value.strip()):
+        raise LibError(f"{what} {value!r} is not one or two hex digits", "e.g. 09 or 0xe0")
+    return value.strip().lower().zfill(2)
+
+
+def classify(
+    base_class: str, subclass: str | None = None, protocol: str | None = None, base: Path | None = None
+) -> str:
+    """Name a class code triple as a device or interface descriptor carries it: bDeviceClass, bDeviceSubClass,
+    bDeviceProtocol. Digits may be written with or without `0x`."""
+    clean = [v.lower().removeprefix("0x") if v is not None else None for v in (base_class, subclass, protocol)]
+    if clean[1] is None and clean[2] is not None:
+        raise LibError("a protocol needs a subclass", "")
+    key: list[str] = []
+    for value, what in zip(clean, ("class", "subclass", "protocol"), strict=True):
+        if value is not None:
+            key.append(_two_hex(value, what))
+    loaded = store.load(base)
+    ids = loaded.ids
+    lines: list[str] = []
+    for depth in range(1, len(key) + 1):
+        entry = ids.get("class", tuple(key[:depth]))
+        if entry is None:
+            if depth == 1:
+                raise LibError(
+                    f"class {key[0]} is not in usb.ids {ids.version}", "usbids_search with section='class'"
+                )
+            lines.append(f"{format_ref('class', tuple(key[:depth]))}  (not listed in usb.ids)")
+            break
+        lines.append(f"{_line(entry)}  [{entry.level_name}]")
+    return render("\n".join(lines), {"cite": _cite(loaded), "unit": "line"})
+
+
+def sections(base: Path | None = None) -> str:
+    """The imported snapshot: version, date, digest, source, licence and entry counts per section."""
+    loaded = store.load(base)
+    ids = loaded.ids
+    per: dict[str, int] = {}
+    for entry in ids.entries.values():
+        per[entry.section] = per.get(entry.section, 0) + 1
+    man = loaded.manifest
+    lines = [
+        f"usb.ids {ids.version or 'unversioned'}  date {ids.date or 'unknown'}",
+        f"sha256 {loaded.sha256}  ({'pinned snapshot' if man.get('pinned') else 'not the pinned snapshot'})",
+        f"source {man.get('url', 'unknown')}  fetched {man.get('fetched', 'unknown')}",
+        f"licence {man.get('licence', store.LICENCE)}",
+        "entries per section (ref prefix):",
+    ]
+    lines += [f"  {name}: {count:,}" for name, count in per.items()]
+    lines += [f"unparsed lines at import: {ids.problem_count}"]
+    return render("\n".join(lines), {"cite": _cite(loaded), "unit": "line"})

primarysource/zim/__init__.py

@@ -0,0 +1,5 @@
+"""zim: a Kiwix library (ZIM files) as token-budgeted, citable documentation for AI agents."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

primarysource/zim/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m primarysource.zim` is the same as `primarysource zim`."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

primarysource/zim/_libzim.py

@@ -0,0 +1,37 @@
+"""The only place that imports the native binding.
+
+`libzim` is a compiled extension (it carries libzim and Xapian). It ships wheels for CPython 3.11+ on
+Windows x64, macOS (x86-64, arm64) and Linux (glibc and musl, x86-64 and aarch64), and nothing else, so on any
+other platform `import libzim` fails. Everything that does not read a ZIM (the CLI's `info`, `catalog`, `get`,
+the reference grammar, the converter) must keep working there, which is why the import is lazy and why its
+failure is a `ZimloreError` naming the remedy instead of a traceback from deep inside a tool.
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+
+from .errors import ZimloreError
+
+REMEDY = (
+    'pip install "primarysource[zim]" (libzim wheels: Windows x64, macOS, Linux glibc/musl; CPython 3.11+). On a '
+    "platform without a wheel, build libzim from source (https://github.com/openzim/python-libzim) or serve the "
+    "same files with kiwix-serve and read them in a browser"
+)
+
+
+def load(name: str) -> ModuleType:
+    """Import `libzim.<name>` (reader, search, suggestion, writer)."""
+    try:
+        return importlib.import_module(f"libzim.{name}")
+    except ImportError as error:
+        raise ZimloreError(f"the libzim binding is not available ({error})", REMEDY) from error
+
+
+def available() -> bool:
+    try:
+        load("reader")
+    except ZimloreError:
+        return False
+    return True