Skip to content

mostlyright.discover

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

Section titled “mostlyright.discover(query=None, , domain=None, kind=None, availability=None, license=None, point_in_time_fidelity=None, live=False, **_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 (Literal['station', 'source', 'market'] | None) – Structured filter — "station", "source", or "market" (the row discriminant). "market" rows need live=True.
    • availability (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.
    • live (bool) – Also search the prediction-market venues and return their matches as kind="market" rows. Off by default: the default path makes no network call, and this is the explicit opt-in that does. Needs a query — a live search with nothing to search for would sweep both venues’ full universes, so it raises instead. The venues are called directly (no venue account; their addresses resolve through the keyed manifest catalog), narrowed, and nothing is cached. The read is bounded per venue (page and row ceilings), and the frame says so: df.attrs["live_search_bounded"] is True, df.attrs["venues_truncated"] names any venue whose ceiling bound, and df.attrs["degraded_venues"] names any venue that could not be read at all.
    • _extra (Any)
  • Return type: DataFrame
  • Returns: One pd.DataFrame. Every row carries a kind discriminant ("station" | "source" | "market") as the first 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, or live=True was passed without the markets distribution installed (the message names the pip install).
    • TypeError – the removed city= selector (or another unknown filter) was passed — use query= instead.