Runtime and provider

CatalogRuntime

Owns one lazily-opened registry for the lifetime of an app.

ensure_open is idempotent — the first call runs the provider, every subsequent call returns the cached handle. Not thread-safe on the very first open; callers warm it during single-threaded lifespan startup (or accept that two concurrent cold requests may both open, last wins), matching the previous _state-dict semantics.

splices is the canonical-surface SpliceRegistry the structure route runs on its serialised JSON (default: empty → the runner still applies its built-in URN injection). The consumer installs its registry here; it is uniform across the parent app and its shared mounts (a forwarder's add-on splices are layered separately by it).

is_open property

is_open: bool

True once ensure_open has run and the registry is live.

registry property

registry: EditionRegistry

The registry (opening it if needed).

meta_conn property

meta_conn: DuckDBPyConnection

The shared read-only metadata.duckdb connection (opening if needed).

manifest property

manifest: object | None

The opaque build manifest supplied by the provider (opening if needed).

build_id property

build_id: str

Build id of the open edition, or "" if not open (does NOT force open).

Non-forcing on purpose: ETag / cache-key callers want "the identity if the registry is up, else skip" — the empty string is the skip signal, mirroring the old get_manifest() is None guard.

built_at property

built_at: str

ISO-8601 build timestamp of the open edition, or "" if not open (non-forcing).

token property

token: str

What every cache and the ETag key on, or "" if not open (non-forcing).

The provider's token if it set one, else the sdmxlib edition manifest's edition id (new for every edition), else build_id.

effective_token property

effective_token: str

token with the annotator's fingerprint folded in, or "" if not open (non-forcing).

What the structure cache, the splices and the ETag key on (GH-2). Equal to token while the annotator has no fingerprint, so ETags stay byte-identical for a consumer that never sets one. The folding mirrors sdmxlib's effective_token for overlays: a sha256 over the lines v3, the token and the fingerprint. AvailabilityKey keeps the bare token: annotations cannot change availability.

last_modified property

last_modified: str

ISO-8601 Last-Modified source, or "" if not open (non-forcing).

Follows token: when the token is the sdmxlib manifest's, so is the timestamp. A provider's built_at can stay put across a new edition that minted a new token, and an If-Modified-Since would then 304 a stale body that the ETag correctly misses.

With an annotator fingerprint it is the later of that and the moment this process first saw the current fingerprint, so an annotation change moves it too. A restart counts as a change: clients refetch once rather than risk a 304 for annotations they never saw.

ensure_open

ensure_open() -> OpenedCatalog

Open the registry on first use; return the cached handle thereafter.

close

close() -> None

Release the opened registry, if any; the runtime can be re-opened after.

CatalogProvider

Bases: Protocol

Opens an OpenedCatalog. Implemented by the consumer.

Called once per CatalogRuntime lifetime (lazily, on first use or at lifespan startup). Implementations own all storage-backend concerns — edition layout, credentials, connection tuning — and must return a registry the generic routes can query plus a DuckDB connection for the custom-SQL data paths.

open

open() -> OpenedCatalog

Open (or re-open) the registry and return the live handle.

OpenedCatalog

A live registry plus its meta connection and build manifest.

Returned by CatalogProvider.open. close runs the provider-supplied teardown (e.g. closing a statcatlib Catalog); it is a no-op when the provider passes none.

close

close() -> None

Run the provider's teardown callback, if any.