bindings: what a book says about itself, and what the register says back

book-pipeline reaches for colophon and bibfetch on every book it repairs.
Shelling out would mean a process per book per tool across five thousand
books, and parsing back the JSON it is about to parse anyway.

bibfetch's fetch loop lived in main.rs, so binding it meant either
lifting it or writing a second one. A second implementation of 'which
register answers about this kind of identifier, and in what order' would
drift from the first, and the copy nobody runs from a terminal would
drift silently. It is now bibfetch::ask, and the command line calls it
too — verified by running the CLI before and after and diffing.

fetch_identifier releases the GIL around the request. It is the only
function here that opens a socket, and holding the interpreter for the
length of an HTTP call would stop every other thread in it.

bibfetch is optional and only the python feature turns it on: its HTTP
client does not build for wasm32, and an unconditional dependency would
have taken the JavaScript package down with it.

crates/bindings/python/catena/__init__.py

@@ -20,6 +20,7 @@ from ._catena import (
     compose_subjects,
     count_tokens,
     cue_windows,
+    fetch_identifier,
     find_citations,
     fuse_hits,
     identify,
@@ -33,12 +34,14 @@ from ._catena import (
     pack_cues,
     parse_identifier,
     parse_subtitles,
+    read_colophon,
     record_problems,
     record_severity,
     same_work,
     scrub,
     segment_cues,
     series_of,
+    shelve,
     split_collection,
     suggest_author,
     title_case,
@@ -56,6 +59,7 @@ __all__ = [
     "compose_subjects",
     "count_tokens",
     "cue_windows",
+    "fetch_identifier",
     "find_citations",
     "fuse_hits",
     "identify",
@@ -69,12 +73,14 @@ __all__ = [
     "pack_cues",
     "parse_identifier",
     "parse_subtitles",
+    "read_colophon",
     "record_problems",
     "record_severity",
     "same_work",
     "scrub",
     "segment_cues",
     "series_of",
+    "shelve",
     "split_collection",
     "suggest_author",
     "title_case",

crates/bindings/python/catena/__init__.pyi

@@ -75,3 +75,30 @@ def valid_isbn(text: str) -> bool: ...
 def isbn_from_text(text: str) -> str | None: ...
 def isbn_from_filename(name: str) -> str | None: ...
 def same_work(ours: str, theirs: str) -> bool: ...
+
+def read_colophon(
+    text: str, pages: int = ..., shelf: str | None = ...
+) -> dict[str, Any]:
+    """What a book prints about itself in its opening pages.
+
+    `shelf` is a closed list of headings to file the printed subjects onto,
+    one per line, optionally `Heading = term, term`.
+    """
+    ...
+
+def shelve(shelf: str, subjects: list[str]) -> tuple[list[str], list[str]]:
+    """File subject headings onto a shelf. Returns (shelved, unshelved)."""
+    ...
+
+def fetch_identifier(
+    id: str,
+    kind: str = ...,
+    polite: str | None = ...,
+    timeout: int = ...,
+    attempts: int = ...,
+) -> dict[str, Any] | None:
+    """Ask the register that assigns an identifier what it knows about one.
+
+    Blocks on the network. `None` when no register answers about that kind.
+    """
+    ...