Skip to content
Mostly Right

Python quickstart

mostlyrightmd ships three PyPI packages — mostlyrightmd (the core join), mostlyrightmd-weather (the public-API fetchers), and mostlyrightmd-markets (optional prediction-market resolvers). The [research] extra installs everything dataset() needs, including pandas and pyarrow.

01 · Get access

Section titled “01 · Get access”

Python 3.11+. The first call writes a parquet cache to ~/.mostlyright/cache/; subsequent calls in the same window are local-only.

02 · First call

Section titled “02 · First call”
import mostlyright


df = mostlyright.dataset(
    station="KNYC",
    from_date="2025-01-06",
    to_date="2025-01-12",
)
print(df.head())

dataset() is the primary composer. research() is a fully working alias bound to the same callable, so existing code keeps working unchanged.

Output is a pandas DataFrame with one row per local-standard-time day in [from_date, to_date]. Columns include:

date, station, cli_high_f, cli_low_f, cli_report_type,
obs_high_f, obs_low_f, obs_mean_f, obs_mean_dewpoint_f,
obs_max_wind_kt, obs_max_gust_kt, obs_total_precip_in,
obs_count, market_close_utc

cli_high_f / cli_low_f come from the NWS CLI overnight final — the official daily climate record. obs_high_f / obs_low_f come from the merged METAR feed (AWC, IEM ASOS, GHCNh) using the documented dedup tiebreak.

Need the raw ingredients? The domain tables sit under the composer: obs() for observations (daily extremes or per-report rows via granularity="observation") and climate() for the standalone NWS CLI settlement labels.

from mostlyright.weather import obs, climate


per_report = obs("KNYC", "2025-01-06", "2025-01-12", granularity="observation")
cli_labels = climate("KNYC", "2025-01-06", "2025-01-12")

03 · Stations

Section titled “03 · Stations”

dataset() supports the major US settlement stations. Pass either the 3-letter NWS code or the 4-letter ICAO:

mostlyright.dataset("KNYC", "2025-01-06", "2025-01-12")  # ICAO
mostlyright.dataset("NYC",  "2025-01-06", "2025-01-12")  # NWS code
mostlyright.dataset("KLAX", "2025-01-06", "2025-01-12")
mostlyright.dataset("KORD", "2025-01-06", "2025-01-12")

Unknown codes raise ValueError with the canonical list.

04 · Cache layout

Section titled “04 · Cache layout”

Calls write to ~/.mostlyright/cache/v1/:

~/.mostlyright/cache/v1/
├── observations/{ICAO}/{YYYY}/{MM}.parquet   # per-month METAR aggregates
└── climate/{ICAO}/{YYYY}.parquet              # per-year NWS CLI

Override the root with MOSTLYRIGHT_CACHE_DIR:

Terminal window
export MOSTLYRIGHT_CACHE_DIR=/data/mostlyright

The current LST month is never cached — those observations are still arriving. Every other month is read locally after the first fetch.

05 · Live streaming

Section titled “05 · Live streaming”

dataset() is the batch research surface. For live METAR ticks (dashboards, threshold alerts, real-time monitoring), use mostlyright.live.stream():

import asyncio
import mostlyright


async def main() -> None:
    async for row in mostlyright.live.stream("KNYC"):
        print(row["observed_at"], row["temp_f"])


asyncio.run(main())

live.stream() yields one row per fresh METAR from a single source (awc by default). It never writes to the cache. See live streaming in the SDK repo for source selection, polite-floor cadence, and multi-station fan-out.

Section titled “What to read next”