Skip to content

Python API

Signatures and descriptions below are generated from Python source at build time. This reference covers the public workflow and the objects it returns; internal transports and provider implementation helpers are intentionally omitted. See fetch and analyze for complete workflows.

Discovery and queries

usdata.search 

search(text: str | None = None, *, include_planned: bool = False, **kwargs: Any) -> list[SearchResult]

Search the curated registry. Keyword arguments match build_query.

usdata.get 

get(dataset_id: str) -> Dataset

Look up a dataset by provider:name id.

usdata.build_query 

build_query(text: str | None = None, *, provider: str | None = None, location: str | None = None, bbox: BBox | tuple[float, float, float, float] | None = None, lat: float | None = None, lon: float | None = None, radius_km: float = 50.0, start: str | date | datetime | None = None, end: str | date | datetime | None = None, variables: list[str] | None = None, **params: Any) -> Query

Normalize user-facing arguments into a Query.

Exactly one of location, bbox, or lat/lon may set the spatial filter.

usdata.Registry

An in-memory collection of datasets addressable by id and searchable by keyword.

bundled classmethod 

bundled() -> Registry

The registry shipped inside the package.

from_yaml classmethod 

from_yaml(path: Path) -> Registry

Load a registry from YAML with top-level providers, domains, datasets.

search 

search(query: Query, *, include_planned: bool = False) -> list[SearchResult]

Rank datasets by keyword match, filtered by provider, space, and time.

Planned datasets are left out unless include_planned is set; stubs are always included because their adapters are being built.

get 

get(dataset_id: str) -> Dataset

Return the dataset with this id or raise DatasetNotFound.

providers 

providers() -> set[str]

The set of provider ids present in the registry.

domains 

domains() -> list[DomainInfo]

All declared domains in declaration order.

Fetching and opening

usdata.fetch.fetch 

fetch(dataset: Dataset, query: Query, *, root: Path | None = None, force: bool = False) -> list[FetchedAsset]

Resolve and fetch a query, sharing one adapter and closing its owned resources.

usdata.fetch.FetchedAsset

Bases: BaseModel

One asset on disk with its provenance and whether the cache satisfied it.

asset instance-attribute 

asset: Asset

path instance-attribute 

path: Path

provenance instance-attribute 

provenance: Provenance

from_cache instance-attribute 

from_cache: bool

open 

open(*, reader: str | None = None, dtype: dict[str, str] | None = None, parse_dates: list[str] | None = None, usecols: list[str] | None = None, nrows: int | None = None, sweep: int | list[int] | None = None) -> Any

Open local data with an optional pandas, radar, or netcdf reader.

ERDDAP units are kept in frame.attrs["units"] and source provenance in frame.attrs["usdata"]. NEXRAD returns a xarray DataTree with provenance in radar.attrs["usdata"]. NetCDF4 returns a loaded xarray Dataset with matching provenance in its attributes. See usdata.readers.open_asset for options. Use sweep=0 or sweep=[0, 2] to load selected zero-based radar sweeps. Cached files and provenance sidecars are never changed.

Reproducible inputs

usdata.pull.pull 

pull(manifest_path: Path, *, root: Path | None = None, force: bool = False, registry: Registry | None = None) -> PullResult

Restore from the lockfile if one exists, otherwise resolve and create it.

usdata.pull.verify 

verify(manifest_path: Path, *, root: Path | None = None) -> list[Drift]

Check manifest consistency, then compare cached files against the lockfile.

usdata.pull.PullResult

Bases: BaseModel

What a pull did.

lockfile instance-attribute 

lockfile: Lockfile

lockfile_path instance-attribute 

lockfile_path: Path

fetched instance-attribute 

fetched: list[FetchedAsset]

from_lockfile instance-attribute 

from_lockfile: bool

usdata.pull.Drift

Bases: BaseModel

One lockfile entry whose local copy is missing or altered.

asset_id instance-attribute 

asset_id: str

dataset_id instance-attribute 

dataset_id: str

path instance-attribute 

path: Path

problem instance-attribute 

problem: str

usdata.manifest.Manifest

Bases: BaseModel

A declarative list of inputs a project needs: usdata pull fetches them.

name instance-attribute 

name: str

version class-attribute instance-attribute 

version: str = '1.0'

sources class-attribute instance-attribute 

sources: list[SourceSpec] = Field(min_length=1)

load classmethod 

load(path: Path) -> Manifest

Parse a manifest YAML file.

validate_against 

validate_against(registry: Registry | None = None) -> list[str]

Return the dataset ids referenced by this manifest that the registry lacks.

usdata.manifest.SourceSpec

Bases: BaseModel

One entry under sources: in a manifest.

dataset instance-attribute 

dataset: str

allow_empty class-attribute instance-attribute 

allow_empty: bool = False

location class-attribute instance-attribute 

location: str | None = None

bbox class-attribute instance-attribute 

bbox: BBox | None = None

start class-attribute instance-attribute 

start: str | date | datetime | None = None

end class-attribute instance-attribute 

end: str | date | datetime | None = None

variables class-attribute instance-attribute 

variables: list[str] = Field(default_factory=list)

params class-attribute instance-attribute 

params: dict[str, Any] = Field(default_factory=dict)

to_query 

to_query() -> Query

Build the Query this source resolves to.

usdata.manifest.Lockfile

Bases: BaseModel

Exactly what a manifest resolved to, with checksums, so it can be reproduced.

manifest instance-attribute 

manifest: str

manifest_checksum class-attribute instance-attribute 

manifest_checksum: str = Field(description='sha256 of the manifest file when it was resolved')

generated_at instance-attribute 

generated_at: datetime

usdata_version instance-attribute 

usdata_version: str

assets class-attribute instance-attribute 

assets: list[LockedAsset] = Field(default_factory=list)

load classmethod 

load(path: Path) -> Lockfile

Read a lockfile written by save.

save 

save(path: Path) -> None

Write the lockfile as indented JSON.

usdata.manifest.LockedAsset

Bases: BaseModel

One resolved asset and the provenance of the copy that was fetched.

asset instance-attribute 

asset: Asset

provenance instance-attribute 

provenance: Provenance

Temporal selection

usdata.select_by_time 

select_by_time(candidates: Iterable[Asset], *, target: datetime, tolerance: timedelta, direction: Literal['nearest', 'at_or_before']) -> TemporalSelection

Select an asset by start time using an explicit tolerance and direction.

nearest admits starts on either side of target; at_or_before admits only starts no later than target. The tolerance boundary is inclusive. Equal distances break ties lexically by asset ID, then dataset ID. Duplicate (dataset_id, id) identities and missing/naive starts raise ValueError, even for candidates that would not win. All supplied candidates are validated.

Target is normalized to UTC for comparison and in the result. The signed offset is asset start minus target, in seconds. If no candidate qualifies, the result has no asset/offset and eligible_count=0. Inputs are not modified. Matching by start does not establish acquisition completion or availability.

usdata.TemporalSelection

Bases: BaseModel

A start-time selection and its explicit policy; not source provenance.

No match has asset=None, offset_seconds=None, and zero eligible candidates. Counts refer to the supplied candidates, not a remote catalog.

target instance-attribute 

target: datetime

tolerance instance-attribute 

tolerance: timedelta

direction instance-attribute 

direction: Literal['nearest', 'at_or_before']

asset instance-attribute 

asset: Asset | None

offset_seconds instance-attribute 

offset_seconds: float | None

candidate_count class-attribute instance-attribute 

candidate_count: int = Field(ge=0)

eligible_count class-attribute instance-attribute 

eligible_count: int = Field(ge=0)

Shared types

usdata.Asset

Bases: BaseModel

A single retrievable object (file, granule, or subset request) from a dataset.

id instance-attribute 

id: str

dataset_id instance-attribute 

dataset_id: str

href instance-attribute 

href: str

protocol instance-attribute 

protocol: Protocol

media_type class-attribute instance-attribute 

media_type: str | None = None

size class-attribute instance-attribute 

size: int | None = Field(default=None, ge=0)

checksum class-attribute instance-attribute 

checksum: str | None = Field(default=None, description="'<algo>:<hex>', e.g. 'sha256:ab12...'")

time class-attribute instance-attribute 

time: TimeRange | None = None

bbox class-attribute instance-attribute 

bbox: BBox | None = None

usdata.BBox

Bases: BaseModel

Geographic bounding box in WGS84 degrees. Antimeridian crossing is not supported yet.

west class-attribute instance-attribute 

west: float = Field(ge=-180, le=180)

south class-attribute instance-attribute 

south: float = Field(ge=-90, le=90)

east class-attribute instance-attribute 

east: float = Field(ge=-180, le=180)

north class-attribute instance-attribute 

north: float = Field(ge=-90, le=90)

from_point classmethod 

from_point(lat: float, lon: float, radius_km: float = 0.0) -> BBox

Box around a point. Uses a flat-earth approximation, fine for small radii.

intersects 

intersects(other: BBox) -> bool

True if the boxes share any area, edges included.

contains_point 

contains_point(lat: float, lon: float) -> bool

True if the point lies inside or on the edge of the box.

as_tuple 

as_tuple() -> tuple[float, float, float, float]

The box as (west, south, east, north).

usdata.TimeRange

Bases: BaseModel

Half-open-agnostic time interval. Either bound may be None to mean unbounded.

start class-attribute instance-attribute 

start: datetime | None = None

end class-attribute instance-attribute 

end: datetime | None = None

overlaps 

overlaps(other: TimeRange) -> bool

True if the ranges share any instant; open bounds match everything on that side.

usdata.Dataset

Bases: BaseModel

A registry entry. One per curated dataset, identified as provider:name.

id instance-attribute 

id: str

provider instance-attribute 

provider: str

title instance-attribute 

title: str

description class-attribute instance-attribute 

description: str = ''

keywords class-attribute instance-attribute 

keywords: list[str] = Field(default_factory=list)

protocol instance-attribute 

protocol: Protocol

homepage class-attribute instance-attribute 

homepage: str | None = None

license class-attribute instance-attribute 

license: str | None = None

spatial_extent class-attribute instance-attribute 

spatial_extent: BBox | None = None

temporal_extent class-attribute instance-attribute 

temporal_extent: TimeRange | None = None

capabilities class-attribute instance-attribute 

capabilities: Capabilities = Field(default_factory=Capabilities)

domain class-attribute instance-attribute 

domain: str = Field(description='Id of a domain declared in the registry')

status instance-attribute 

status: Status

since class-attribute instance-attribute 

since: str | None = Field(default=None, description='Version an available dataset shipped in')

target class-attribute instance-attribute 

target: str | None = Field(default=None, description="Version a stub or planned dataset is aimed at, or 'later'")

adapter class-attribute instance-attribute 

adapter: str | None = Field(default=None, description="'package.module:ClassName' of the Provider; required unless planned")

version_label property 

version_label: str

'since 0.2' for shipped datasets, 'target 0.4' or 'target later' otherwise.

name property 

name: str

The dataset name without the provider prefix.

usdata.Query

Bases: BaseModel

Normalized, provider-agnostic request. Providers translate this into their own terms.

text class-attribute instance-attribute 

text: str | None = None

provider class-attribute instance-attribute 

provider: str | None = None

bbox class-attribute instance-attribute 

bbox: BBox | None = None

time class-attribute instance-attribute 

time: TimeRange | None = None

variables class-attribute instance-attribute 

variables: list[str] = Field(default_factory=list)

params class-attribute instance-attribute 

params: dict[str, Any] = Field(default_factory=dict, description='Provider-specific passthrough parameters')

usdata.Provenance

Bases: BaseModel

Everything needed to say where a local file came from and re-fetch it.

dataset_id instance-attribute 

dataset_id: str

provider instance-attribute 

provider: str

source_url instance-attribute 

source_url: str

retrieved_at instance-attribute 

retrieved_at: datetime

checksum instance-attribute 

checksum: str

size class-attribute instance-attribute 

size: int = Field(ge=0)

license class-attribute instance-attribute 

license: str | None = None

usdata_version instance-attribute 

usdata_version: str

transformations class-attribute instance-attribute 

transformations: list[str] = Field(default_factory=list)

usdata.SearchResult

Bases: BaseModel

A dataset and its keyword-match score.

dataset instance-attribute 

dataset: Dataset

score instance-attribute 

score: float