API Reference¶
Reference for the public cfs API, generated from the source.
Facade (one-shot API)¶
cfs.api.fetch
async
¶
fetch(product_or_slug: str, bbox: BoundingBox | Sequence[float], time_range: TimeRange | Sequence[datetime | str], variables: Sequence[CanonicalVar | str] | None = None, config: dict | None = None) -> tuple[xr.Dataset, FetchResult]
Acquire + subset a forcing product to a canonical gridded dataset, in one call.
Runs the full connector lifecycle: discover() the registry, resolve the
connector from the identifier, open it as an async context manager (with
the optional provider-specific config dict), and fetch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
product_or_slug
|
str
|
A full product ID |
required |
bbox
|
BoundingBox | Sequence[float]
|
A :class: |
required |
time_range
|
TimeRange | Sequence[datetime | str]
|
A :class: |
required |
variables
|
Sequence[CanonicalVar | str] | None
|
Canonical variables to return —
:class: |
None
|
config
|
dict | None
|
Optional provider-specific connector configuration dict
(e.g. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[Dataset, FetchResult]
|
|
cfs.api.fetch_sync ¶
fetch_sync(product_or_slug: str, bbox: BoundingBox | Sequence[float], time_range: TimeRange | Sequence[datetime | str], variables: Sequence[CanonicalVar | str] | None = None, config: dict | None = None) -> tuple[xr.Dataset, FetchResult]
Synchronous wrapper around :func:fetch via asyncio.run.
For plain scripts and synchronous embedders. Raises a clear
RuntimeError when called from inside a running event loop — in async
code, await cfs.fetch(...) directly instead.
cfs.api.configure ¶
Override CFS runtime settings after import (cache dir, timeouts, guardrails…).
CFS settings are env-driven (CFS_* variables, see
:class:~cfs.core.config.Settings) and cached on first use. This hook lets
an embedder set them programmatically: each keyword must be a Settings
field name; its value is written to the corresponding CFS_<FIELD>
environment variable (lists become comma-separated, booleans
true/false), and the get_settings() cache is cleared so the
override takes effect everywhere settings are read (connectors read them
at call time, never at import time). Pass None to drop a previous
override and fall back to the environment/default.
Returns:
| Type | Description |
|---|---|
Settings
|
The new effective :class: Example:: |
Registry¶
cfs.core.registry.discover ¶
Import all connector modules to trigger registration.
cfs.core.registry.register ¶
Decorator to register a connector class under a provider slug.
Connector base class¶
cfs.connectors.base.BaseForcingConnector ¶
Bases: ABC
Interface every forcing provider connector must implement.
list_products
abstractmethod
async
¶
Return the catalog of forcing products this provider offers.
fetch
abstractmethod
async
¶
fetch(product_id: str, bbox: BoundingBox, time_range: TimeRange, variables: list[CanonicalVar] | None = None) -> tuple[xr.Dataset, FetchResult]
Acquire and subset a product to a canonical gridded dataset.
Returns (dataset, result) where dataset carries canonical
variable names/units (see :mod:cfs.core.vocabulary) over the requested
bbox and time range, and result is the :class:FetchResult
describing its provenance and shape.
Request / result models¶
cfs.core.models.BoundingBox ¶
Bases: BaseModel
Geographic bounding box in EPSG:4326, longitudes in [-180, 180].
cfs.core.models.TimeRange ¶
Bases: BaseModel
cfs.core.models.FetchResult ¶
Bases: BaseModel
Metadata describing the xarray.Dataset a fetch produced.
The dataset is returned alongside this object (not serialized into it). This captures provenance and shape so a caller can log/inspect without loading the cube.
Catalog models¶
cfs.core.models.ForcingProduct ¶
Bases: BaseModel
A meteorological forcing product offered by a provider.
cfs.core.models.ProductVariable ¶
Bases: BaseModel
A canonical variable a product can deliver, plus its native source name.
cfs.core.models.TemporalExtent ¶
Bases: BaseModel
Canonical vocabulary¶
cfs.core.vocabulary.CanonicalVar ¶
Bases: StrEnum
Canonical forcing variable names (CF-aligned standard names).
cfs.core.vocabulary.CanonicalSpec ¶
Bases: BaseModel
The canonical definition of one forcing variable.
Harmonization¶
cfs.subset.canonical.VariableMapping
dataclass
¶
One native variable's mapping to the canonical schema.
The transform is applied in order: optional reset-aware de-accumulation
(for running totals like ERA5-Land precip/radiation), then the linear
canonical = source * scale + offset to the canonical units defined in
:data:cfs.core.vocabulary.CANONICAL.
cfs.subset.canonical.harmonize ¶
harmonize(ds: Any, mappings: list[VariableMapping], requested: list[CanonicalVar] | None = None, *, lat_name: str = 'latitude', lon_name: str = 'longitude', time_name: str = 'time') -> Any
Return a new dataset with canonical variable names, units, and metadata.
Only variables present in ds and (if given) in requested are kept.
Stays lazy: arithmetic on dask-backed arrays does not trigger compute.