Skip to content
Mostly Right

mostlyright.discover

mostlyright.discover(query=None, , domain=None, kind=None, availability=None, license=None, point_in_time_fidelity=None, **_extra)

Section titled “mostlyright.discover(query=None, , domain=None, kind=None, availability=None, license=None, point_in_time_fidelity=None, **_extra)”

Search the registration-metadata catalog across domains.

Example

Section titled “Example”
>>> import mostlyright as mr
>>> hits = mr.discover(query="nyc")
>>> hits["kind"].iloc[0]
'station'
  • Parameters:
    • query (str | None) – Optional free-text query. Known station aliases in the query (e.g. "nyc") resolve to the settlement stations (kind "station" rows, carrying the cross-venue note); the remaining tokens score the registered data sources (kind "source" rows). City lookups go here: discover(query="nyc").
    • domain (str | None) – Structured filter — the domain slug ("weather" …).
    • kind (Optional[Literal['station', 'source']]) – Structured filter — "station" or "source" (the row discriminant).
    • availability (Union[Literal['python', 'typescript'], list[Literal['python', 'typescript']], None]) – Structured filter — "python" / "typescript" (or a list).
    • license (str | None) – Structured filter — the source license string.
    • point_in_time_fidelity (str | None) – Structured filter — the PIT fidelity value.
    • _extra (Any)
  • Return type: DataFrame
  • Returns: ONE discriminated pd.DataFrame. Every row carries a kind discriminant ("station" | "source") as the LEADING column, then the shared id/name/domain identity, then the kind-specific nullable columns — station geo (country/latitude/longitude/timezone from the bundled catalog) and source metadata (point_in_time_fidelity/ availability) — plus note/usage/score. No option changes the return type. Deterministically ordered (score desc, then id asc). Zero-arg discover() lists the registered sources. A guaranteed-miss free-text query returns an empty-but-shaped frame whose df.attrs["message"] guides back.
  • Raises:
    • ContractError – an invalid kind / availability selector (carries a difflib did-you-mean).
    • EntityNotFoundError – an alias in query could not be resolved (carries a deterministic nearest-match suggestion).
    • SourceUnavailableError – pandas is not installed.
    • TypeError – the removed city= selector (or another unknown filter) was passed — use query= instead.