mostlyright.registry

mr.registry — the author-facing catalog writer.

mr.registry.source(spec) / mr.registry.label(spec) add a validated entry to the shipped _contributors._REGISTRY, carrying a kind axis that distinguishes a feature source from a settlement label. The registry is a plain dict store that lookups read; it never builds an import path at runtime, so an id can never trigger an arbitrary import, and mypy and tree-shaking resolve every symbol statically. Registration writes the discover() catalog index and validates contracts; it does not change the import graph.

Three rules are enforced at registration time:

1. The “.label.“ id rule, in both directions. label(spec) requires .label. in spec.id; source(spec) rejects .label. in spec.id. Feature-vs-target then becomes a property that can be checked at write time instead of guessed at the call site.
2. The declared-prefix firewall, for sources only. source(spec) reads _contributors._FORBIDDEN_LABEL_PREFIXES and rejects a source whose declared prefix is a reserved label prefix (e.g. obs_) with a ContractError naming the labels-only firewall, without loosening the firewall list. The canonical weather.obs source registers under the met_ prefix; obs_* stays label-only. The firewall is scoped by kind because a label legitimately owns a label prefix (cli_) and label columns, so running a label through the source firewall would reject it. The bitemporal-field and point_in_time_fidelity validation applies to both kinds.
3. Idempotent, conflict-checked writes. Registering the same id with an identical spec is a no-op; the same id with a different spec raises, as in core.validator.register_schema.

CWOP is never registered here, and the four parity-firewall files stay untouched.

Functions

Function	Description
entries()	Return an isolated shallow copy of the catalog (id → SourceContract).
get(id)	Look up a registered contract by id without importing anything.
label(spec, *[, _builtin])	Register a settlement label (kind="label").
register_alias_resolver(domain, resolver)	Register a per-domain entity alias resolver (last write wins per domain).
resolve_entity(alias, *[, domain])	Resolve an entity alias (e.g. "nyc" → KNYC/KLGA) via domain resolvers.
source(spec, *[, _builtin])	Register a feature source (kind="source").

Exceptions

Exception	Description
EntityNotFoundError(alias, suggestion, *[, …])	An entity alias could not be resolved by any registered resolver.

exception mostlyright.registry.EntityNotFoundError(alias, suggestion, , request_id=None, error_code=None)

Bases: NoDataError

An entity alias could not be resolved by any registered resolver.

Carries a nearest-match suggestion computed by edit distance and prefix match over the static registry id set plus the resolver vocabularies, with no fuzzy matching, vector similarity, or network dependency. An identical alias always yields an identical suggestion.

• Parameters:
  • alias (str)
  • suggestion (str)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

mostlyright.registry.entries()

Return an isolated shallow copy of the catalog (id → SourceContract).

Mutating the returned dict cannot corrupt the backing store, because the copy is what the caller holds. This lookup triggers no import.

• Return type: dict[str, SourceContract]

mostlyright.registry.get(id)

Look up a registered contract by id without importing anything.

• Raises: KeyError – the id is not registered.
• Return type: SourceContract
• Parameters: id (str)

mostlyright.registry.label(spec, , _builtin=False)

Register a settlement label (kind="label").

Validates the bitemporal field list, point_in_time_fidelity, and prefix, and requires a .label. id path. The declared-prefix and label-column firewall is not applied, because a label legitimately owns a label prefix and label columns. Returns the registered spec. _builtin=True is for first-party import-time registration only — see source().

• Raises: ContractError – nonconforming spec, an id path missing .label., or a conflicting re-registration.
• Return type: SourceContract
• Parameters:
  • spec (SourceContract)
  • _builtin (bool)

mostlyright.registry.register_alias_resolver(domain, resolver)

Register a per-domain entity alias resolver (last write wins per domain).

• Return type: None
• Parameters:
  • domain (str)
  • resolver (Callable [ [str ] , dict [str , Any ] | None ])

mostlyright.registry.resolve_entity(alias, , domain=None)

Resolve an entity alias (e.g. "nyc" → KNYC/KLGA) via domain resolvers.

Routes through each registered resolver (or only domain’s resolver when given), returning the first {"domain", "entities", "note"} result. The cross-venue settlement-station warning is preserved in the note. An alias no resolver can resolve raises EntityNotFoundError carrying a deterministic nearest-match suggestion.

• Raises: EntityNotFoundError – no resolver could resolve alias.
• Return type: dict[str, Any]
• Parameters:
  • alias (str)
  • domain (str | None)

mostlyright.registry.source(spec, , _builtin=False)

Register a feature source (kind="source").

Validates the bitemporal field list, point_in_time_fidelity, and prefix, applies the source-only declared-prefix and label-column firewall, and rejects a .label. id path. Returns the registered spec. _builtin=True is for first-party import-time registration only: it skips the one-shot experimental warning so a fresh install’s first import stays silent and the warning still fires on a genuine user registration.

• Raises: ContractError – nonconforming spec, forbidden label prefix, label-shaped column, a .label. id path, or a conflicting re-registration.
• Return type: SourceContract
• Parameters:
  • spec (SourceContract)
  • _builtin (bool)