mostlyright.live

mostlyright.live

mostlyright.live — single-source ticker surface.

live.stream() is an async generator that polls a SINGLE source (AWC or IEM) on a polite-floor cadence and yields the most-recent observation per tick. live.latest() is a one-shot version of the same fetch path.

This is intentionally distinct from mostlyright.research():

| research() | live.stream() / latest() |

|----------------|

———————-

|--------------------------|

| Role | DATABASE (training) | TICKER (real-time) | | Sources | AWC + IEM + GHCNh + CLI (fused) | ONE of AWC | IEM | | Cache writes | yes (parquet) | no | | QC | yes (Phase 3.4) | no | | Loop semantics | none (point-in-time) | async generator |

See docs/live-streaming.md for usage patterns.

exception mostlyright.live.LiveStreamError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyRightError

Base class for mostlyright.live.stream / live.latest failures.

Live-streaming errors are deliberately a separate sub-tree from SourceUnavailableError because the recovery path differs — for a live stream, the caller is in a polling loop and “no data yet” is the COMMON case, not an exception. NoLiveDataError is only raised by the one-shot mostlyright.live.latest() surface; mostlyright.live.stream() swallows empty-tick errors and waits for the next polite-floor cycle.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code : str = ‘LIVE_STREAM_ERROR’

Subclass override — the stable string enum surfaced via error_code.

error_code : str

message : str

request_id : str | None

source : str | None

exception mostlyright.live.NoLiveDataError(message=”, , station, source, request_id=None, error_code=None)

Bases: LiveStreamError

mostlyright.live.latest() returned no observations for the station.

Carries the resolved ICAO station and the canonical source identity tag ("awc.live" / "iem.live") so caller logs can branch by source without re-parsing the message.

• Parameters:
  • message (str)
  • station (str)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code : str = ‘NO_LIVE_DATA’

Subclass override — the stable string enum surfaced via error_code.

error_code : str

message : str

request_id : str | None

source : str | None

station : str

async mostlyright.live.latest(station, , source=None)

Return the most-recent observation row for station from a SINGLE source.

• Parameters:
  • station (str) – ICAO ("KNYC") or 3-letter US ID ("NYC").
  • source (str | None) – One of "awc" (default) or "iem". Case-insensitive.
• Return type: dict[str, Any]
• Returns: Observation dict with source field set to "awc.live" or "iem.live".
• Raises:
  • ValueError – When source is not in SUPPORTED_SOURCES.
  • NoLiveDataError – When the upstream returned no observations.

async mostlyright.live.stream(station, , source=None, poll_seconds=None)

Yield fresh observations for station from a SINGLE source.

The loop:

1. Validate source + poll_seconds (raises ValueError BEFORE first poll).
2. Poll once.
3. If the most-recent observation’s observed_at differs from the last one yielded, yield it. Otherwise skip (dedup).
4. await asyncio.sleep(poll_seconds).
5. Loop.

Empty responses (network error, fetcher returned []) DO NOT abort the stream — they’re treated as “nothing fresh yet” and the loop continues after the polite-floor sleep. To get a single-shot failure path, use latest().

• Parameters:
  • station (str) – ICAO ("KNYC") or 3-letter US ID ("NYC").
  • source (str | None) – One of "awc" (default) or "iem".
  • poll_seconds (float | None) – Override the polite-floor cadence. Must be >= the per-source floor (AWC=30, IEM=60). When None, uses the floor.
• Yields: One observation dict per fresh tick. source field is "awc.live" or "iem.live".
• Raises: ValueError – When source is unsupported or poll_seconds is below the polite floor (raised BEFORE the first poll).
• Return type: AsyncIterator[dict[str, Any]]

mostlyright.live.validate_source(source)

Normalize and validate a source kwarg.

• Parameters: source (str | None) – Caller-supplied source string. None → defaults to first entry in SUPPORTED_SOURCES (AWC). Case-insensitive.
• Return type: str
• Returns: The normalized lowercase source name (one of SUPPORTED_SOURCES).
• Raises: ValueError – When the source is not in SUPPORTED_SOURCES.