mostlyright.weather.catalog

mostlyright.weather.catalog

Weather catalog: adapter registry + WeatherAdapter Protocol.

Each adapter wraps a Phase 1 parser (_iem / _awc / _climate / _ghcnh) and emits a canonical-schema DataFrame with overlay columns (source, retrieved_at, knowledge_time, event_time). Adapters declare SUPPORTED_SOURCES at class level and self-register with the module-level _REGISTRY at import time.

get_adapter(source_id) is the canonical dispatch — given a source ID ("iem.archive", "awc.live", "cli.archive", "ghcnh.archive") it returns a fresh adapter instance.

The registry is eagerly populated when mostlyright.weather.catalog is imported. The four canonical adapter modules import this module first to get the _REGISTRY dict, then register_adapter() appends each.

Functions

get_adapter(source)	Return a fresh adapter instance for source.
list_sources()	Return the sorted list of registered source IDs.
register_adapter(source_id, adapter_cls)	Register an adapter class against a source ID.

Classes

WeatherAdapter(*args, **kwargs)	Protocol every weather catalog adapter satisfies.

class mostlyright.weather.catalog.WeatherAdapter(*args, **kwargs)

Bases: Protocol

Protocol every weather catalog adapter satisfies.

SUPPORTED_SOURCES : ClassVar[list[str]]

fetch_observations(source, station, from_date, to_date)

Fetch observations from source for the given station + window.

The returned DataFrame conforms to schema.observation.v1 and carries df.attrs["source"] = source.

• Return type: DataFrame
• Parameters:
  • source (str)
  • station (str)
  • from_date (str)
  • to_date (str)

mostlyright.weather.catalog.get_adapter(source)

Return a fresh adapter instance for source.

• Raises: DataAvailabilityError – source is not registered. The error carries reason="model_unavailable" so cross-SDK consumers can branch on e.reason rather than string-matching the message. DataAvailabilityError is a subclass of MostlyRightError, so code catching the broader base class continues to work.
• Return type: WeatherAdapter
• Parameters: source (str)

mostlyright.weather.catalog.list_sources()

Return the sorted list of registered source IDs.

• Return type: list[str]

mostlyright.weather.catalog.register_adapter(source_id, adapter_cls)

Register an adapter class against a source ID.

Idempotent — re-registering the same class is a no-op. Conflicting re-registration raises ValueError so adapters never silently shadow each other.

• Return type: None
• Parameters:
  • source_id (str)
  • adapter_cls (type [WeatherAdapter ])

Modules

awc	AWC catalog adapter (CATALOG-02).
cli	NWS CLI settlement adapter (CATALOG-03).
earnings	Earnings catalog adapter (Phase 27, 27-06).
ghcnh	GHCNh catalog adapter (CATALOG-04).
iem	IEM catalog adapter (CATALOG-01).