eegdash.dataset.snapshot module

Single data-access seam for the docs build.

One server chart-data call (rows + montages + metadata, all shaped server-side) with disk-cache and package-CSV fallbacks, self-reporting provenance via DatasetSnapshot.source.

class eegdash.dataset.snapshot.DatasetSnapshot(*, rows: DataFrame, aggregations: dict[str, Any], montages: Mapping[str, Mapping[str, Any]], source: Literal['live', 'cached', 'package-csv'], fetched_at: datetime, api_errors: list[str] | None = None, manifest: dict[str, Any] | None = None, metadata: Mapping[str, Mapping[str, Any]] | None = None)

Bases: object

A frozen view of the dataset catalog for one docs build.

Build with build(), read via the accessors; provenance on source / fetched_at / api_errors.

aggregations() → dict[str, Any]

Server-side totals; empty on a fallback (cached / package-csv) build.

api_errors: list[str] = []

classmethod build(api_base: str = 'https://data.eegdash.org/api', database: str = 'eegdash', *, limit: int | None = None, force_refresh: bool = False) → DatasetSnapshot

Fetch / cache / fallback in one call, memoised per process.

Order: live chart-data → disk cache → package CSV (each failure recorded on api_errors). limit defaults to EEGDASH_DOC_LIMIT or 1000; force_refresh skips both caches.

property dataset_count: int

fetched_at: datetime | None = None

manifest: dict[str, Any] = {}

metadata(dataset_id: str) → Mapping[str, Any] | None

Server metadata dict for one dataset (case-insensitive), or None.

Live builds only; cached / package-csv builds carry none.

montage(dataset_id: str) → Mapping[str, Any] | None

Top montage dict for one dataset (case-insensitive), or None.

rows() → DataFrame

Per-dataset records as a DataFrame (a copy, so callers can’t leak state).

property schema_version: str | None

Server schema_version from the manifest, or None.

source: Literal['live', 'cached', 'package-csv'] = 'package-csv'