Skip to content
Mostly Right

Migration

v0.14.1 → v1.2

v1.2 is fully byte-equivalent to v0.14.1’s client.pairs() on the 5 canonical parity fixtures — that’s the hard gate every release passes. Most code keeps working unchanged. This page lists the rename and the legitimate breakage.

TL;DR — the diff

Section titled “TL;DR — the diff”
Surfacev0.14.1v1.2
Package nametradewindsmostlyrightmd (Python) / mostlyright (TS meta)
Importfrom tradewinds import Clientfrom mostlyright import research
Main callClient().pairs(station, from, to)research(station, from, to)
Cache directory~/.tradewinds/cache/~/.mostlyright/cache/
Env varTRADEWINDS_CACHE_DIRMOSTLYRIGHT_CACHE_DIR
Asyncawait client.pairs(...)df = research(...) (sync — async still available via live.*)
TS packagen/amostlyright + @mostlyrightmd/* scoped

Output frame is byte-equivalent. Same columns, same dtypes, same row order, same null handling.

Python migration

Section titled “Python migration”

Install

Section titled “Install”
Terminal window
pip uninstall tradewinds
pip install mostlyrightmd

Import + first call

Section titled “Import + first call”
from tradewinds import Client


client = Client()
df = await client.pairs("KNYC", "2025-01-06", "2025-01-12")

No more Client object

Section titled “No more Client object”

The v0.14.1 Client carried per-instance state for cache path, HTTP timeouts, etc. v1.x exposes those as call-site kwargs or module-level overrides:

v0.14.1
client = Client(cache_dir="/custom/cache", timeout=60)


# v1.2 — env var
import os
os.environ["MOSTLYRIGHT_CACHE_DIR"] = "/custom/cache"
from mostlyright import research
df = research("KNYC", "2025-01-06", "2025-01-12")

For per-call overrides, use the kwargs documented in the Research API guide.

Async

Section titled “Async”

v0.14.1 was async-first; v1.x defaults to sync because backtest/notebook workflows dominate. Async is still available for live streaming:

import asyncio
import mostlyright


async def main():
    async for row in mostlyright.live.stream("KNYC"):
        print(row)


asyncio.run(main())

If you need parallel research calls, use asyncio.to_thread:

import asyncio
from mostlyright import research


async def main():
    dfs = await asyncio.gather(*[
        asyncio.to_thread(research, s, "2025-01-06", "2025-01-12")
        for s in ["KNYC", "KORD", "KLAX"]
    ])

Cache directory migration

Section titled “Cache directory migration”

Move your existing cache:

Terminal window
mv ~/.tradewinds ~/.mostlyright

Or set the env var:

Terminal window
export MOSTLYRIGHT_CACHE_DIR=~/.tradewinds/cache

Both work. The on-disk format (parquet, per-month layout) is unchanged from v0.14.1 — your existing cache reads without re-fetching.

See Cache directory migration for the full env-var compatibility table.

TypeScript SDK is new

Section titled “TypeScript SDK is new”

v0.14.1 had no TS SDK. v1.2 ships parity:

Terminal window
# Pick one:
npm install mostlyright           # meta — includes everything
npm install @mostlyrightmd/core   # just the join
npm install @mostlyrightmd/weather @mostlyrightmd/core  # weather + core
import { research } from "mostlyright";
const rows = await research("KNYC", "2025-01-06", "2025-01-12");

The TS API mirrors Python — see the TypeScript quickstart.

v1.2 additions (not in v0.14.1)

Section titled “v1.2 additions (not in v0.14.1)”

These are net-new — your v0.14.1 code doesn’t break, but you can opt in:

  • research(include_forecast=True) — Phase 17 wired forecasts end-to-end. Was NotImplementedError in v0.14.1.
  • research(forecast_models=["hrrr","gfs"]) — per-NWP-model forecast fan-out.
  • research(qc=True) — Phase-3.x QC engine.
  • research(source="iem") — single-source provenance pinning (with SourceMismatchError).
  • research(sources=["awc","iem"]) — LIVE_V1 multi-source subset.
  • research(backend="polars") — Phase 6 Polars backend (Python only).
  • research(return_type="wrapper") — Phase 6 TradewindsResult wrapper.
  • live.stream() / live.latest() — Phase 11 live ticker.
  • obs() — Phase 7 ingest-planner.
  • daily_extremes() — international per-day rollups.
  • forecast_nwp() — Phase 17 gridded NWP, 24 models.
  • DataAvailabilityError — Phase 21 typed exception for data-availability paths.

v1.2 breakage list

Section titled “v1.2 breakage list”

The ones you have to fix:

  1. Package name. tradewinds → mostlyrightmd. There’s no pip install tradewinds shim.
  2. Client class removed. Client().pairs() → research(). Construction kwargs become module env vars / call kwargs.
  3. Async signature. await client.pairs(...) → research(...) (sync). Wrap in asyncio.to_thread if you need async.
  4. Cache path. ~/.tradewinds/cache/ → ~/.mostlyright/cache/. mv is enough; format unchanged.

That’s the full list. The output shape, dtypes, and per-row contracts are unchanged — your downstream code that consumed the v0.14.1 DataFrame keeps working.

Verifying byte-equivalence

Section titled “Verifying byte-equivalence”

If you have a v0.14.1 backtest and want to confirm v1.2 produces identical output:

# Generate from v0.14.1
import pickle
from tradewinds import Client  # in a v0.14.1 venv
old = await Client().pairs("KNYC", "2025-01-06", "2025-01-12")
pickle.dump(old, open("/tmp/v014.pkl", "wb"))


# Generate from v1.2
import pickle, pandas as pd
from mostlyright import research  # in a v1.2 venv
new = research("KNYC", "2025-01-06", "2025-01-12")
old = pickle.load(open("/tmp/v014.pkl", "rb"))
pd.testing.assert_frame_equal(old, new)  # exact equality

The 5 canonical parity fixtures are checked in CI on every release.

See also

Section titled “See also”