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. Every public function that takes a filesystem path accepts a str or any os.PathLike[str] and coerces it once on entry, so a path usdata inspect printed can be pasted straight back in. See fetch and analyze for complete workflows.

Discovery and queries

usdata.datasets

datasets(*, provider: str | None = None, domain: str | None = None, format: str | None = None, reader: str | None = None, capability: str | None = None, status: str = 'available') -> list[Dataset]

List curated registry datasets. Keyword arguments match Registry.list.

usdata.search

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

Search the curated registry. Remaining 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. A location sets both the query's bbox and its place, the state or county it named; a bbox or a lat/lon names no place.

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: str | PathLike[str]) -> Registry

Load from YAML with providers, domains, systems, and datasets.

list

list(*, provider: str | None = None, domain: str | None = None, format: str | None = None, reader: str | None = None, capability: str | None = None, status: str = 'available') -> list[Dataset]

Datasets matching every filter given, in registry order.

provider and domain match an id exactly. format matches case-insensitively anywhere in a declared format, so csv also finds gzip CSV. reader names the extra that opens the files, or 'none' for datasets delivering bytes only. capability names one of CAPABILITY_NAMES and keeps datasets declaring it true. status is 'available', 'planned', or 'all'.

search

search(query: Query, *, include_planned: bool = False, provider: str | None = None, domain: str | None = None, format: str | None = None, reader: str | None = None, capability: str | None = None, status: str | None = None) -> list[SearchResult]

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

The keyword arguments are the list filters, applied before scoring. Planned datasets are left out unless include_planned is set; status supersedes it when given. Blank or absent text is no keyword filter, as in list.

Raises:

Type	Description
ValueError	The text has no letters or digits to match, such as ?; it would otherwise match every dataset.

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(dataset: Dataset, query: Query, *, root: str | PathLike[str] | None = None, force: bool = False) -> list[FetchedAsset]

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

usdata.fetch_asset

fetch_asset(dataset: Dataset, asset: Asset, *, root: str | PathLike[str] | None = None, force: bool = False) -> FetchedAsset

Fetch one asset, reusing the cache only when its provenance still describes it.

usdata.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() -> Any

Open local data with the reader its format implies, with that reader's defaults.

CSV and ERDDAP CSV, HURDAT2, AQS daily JSON, and ACS tables return a pandas DataFrame; NetCDF4 and GRIB2 a loaded xarray Dataset; NEXRAD Level II an xarray DataTree. Provenance is kept in the result's attrs["usdata"]. A file that needs options, or whose metadata leaves its format ambiguous, is opened with the method for its format instead: open_csv, open_nexrad, open_grib2, or open_netcdf. Cached files and provenance sidecars are never changed. See usdata.readers.open_asset.

open_csv

open_csv(*, dtype: dict[str, str] | None = None, parse_dates: list[str] | None = None, usecols: list[str] | None = None, nrows: int | None = None, units_row: bool | None = None) -> pd.DataFrame

Open a CSV as a pandas DataFrame; see usdata.readers.open_csv.

units_row says whether a units row follows the header, as in ERDDAP CSV, and is inferred when None; the units go to frame.attrs["units"].

open_nexrad

open_nexrad(*, sweep: int | list[int] | None = None) -> xr.DataTree

Open a NEXRAD Level II volume as an xarray DataTree; see usdata.readers.open_nexrad.

Use sweep=0 or sweep=[0, 2] to load selected zero-based sweeps.

open_grib2

open_grib2(*, select: Mapping[str, Any] | None = None, strict: bool = False) -> xr.Dataset

Open GRIB2 messages as one xarray Dataset; see usdata.readers.open_grib2.

select={"shortName": "cape", "typeOfLevel": "surface"} chooses messages; strict=True raises instead of warning when a select value matches none of the selected messages.

open_netcdf

open_netcdf() -> xr.Dataset

Open a NetCDF4 file as an xarray Dataset; see usdata.readers.open_netcdf.

inspect

inspect() -> Summary

Summarize this file: provenance, format, and what that format holds.

CSV columns and a capped row count need no extra; NetCDF4 variables and GRIB2 messages need the same extras open does, and a missing one yields a summary with no detail and a note naming it. Like open, this reads the cached file and changes nothing. See usdata.inspect.inspect_asset.

Listing GRIB2 messages

usdata.list_messages

list_messages(dataset: Dataset, query: Query) -> list[MessageListing]

List each file a query resolves to with the fields its index describes.

Each entry's selector is a messages value that names exactly that field. A selector may stop after its level text, as CAPE:surface, to name that field at whatever step each file holds.

Parameters:

Name	Type	Description	Default
dataset	Dataset	A dataset declaring partial_fetch.	required
query	Query	The query a fetch would take, without messages.	required

Returns:

Type	Description
list[MessageListing]	One listing per file, in the order a fetch would list them.

Raises:

Type	Description
QueryError	The dataset selects no messages, the query names messages, or a file publishes no readable index.

usdata.MessageListing

Bases: BaseModel

One file a query resolved to, and every field its index describes.

asset class-attribute instance-attribute

asset: Asset = Field(description='The whole-file asset, as a fetch without messages lists it')

messages class-attribute instance-attribute

messages: list[IndexEntry] = Field(description="Every field in the object's index, in order")

usdata.models.IndexEntry

Bases: BaseModel

One field of one GRIB2 object, as the object's wgrib2 .idx sidecar describes it.

number is the GRIB2 message the field belongs to and field its position inside a message that holds several (12.2), or None for a message holding one. Fields of one message share an offset and a length. selector is the messages text that names exactly this field.

number class-attribute instance-attribute

number: int = Field(ge=1, description='One-based GRIB2 message number in the object')

offset class-attribute instance-attribute

offset: int = Field(ge=0, description='Byte offset of the message in the object')

length class-attribute instance-attribute

length: int = Field(gt=0, description='Bytes the message occupies')

short_name class-attribute instance-attribute

short_name: str = Field(description='wgrib2 short name, such as CAPE')

level class-attribute instance-attribute

level: str = Field(description="Level text, such as '2 m above ground'")

step class-attribute instance-attribute

step: str = Field(description="Step text, such as 'anl' or '1 hour fcst'")

field class-attribute instance-attribute

field: int | None = Field(default=None, ge=1, description='Position inside a message holding several fields')

extra class-attribute instance-attribute

extra: str = Field(default='', description="Further text some products add, such as 'ens std dev'")

byte_range property

byte_range: ByteRange

The inclusive byte interval this field's message occupies in the object.

selector property

selector: str

The messages selector naming exactly this field, short name through the last text.

Inspecting a file

usdata.inspect_asset

inspect_asset(fetched: FetchedAsset) -> Summary

Summarize a fetched asset: its provenance and, for its format, what is inside.

The format comes from the asset's media type, falling back to its id, so a restored asset summarizes the same way a freshly fetched one does.

Parameters:

Name	Type	Description	Default
fetched	FetchedAsset	The asset to inspect, as fetch returned it.	required

Returns:

Type	Description
Summary	A summary carrying the detail for the asset's format, or no detail and a
Summary	note naming the extra when that format's reader is not installed.

usdata.inspect_path

inspect_path(path: str | PathLike[str]) -> Summary

Summarize a cached file, reading the provenance sidecar written beside it.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	A cached file whose <name>.provenance.json sidecar exists, written as a string or as any os.PathLike.	required

Returns:

Type	Description
Summary	The summary inspect_asset builds, with the format taken from the file
Summary	name because a sidecar records no media type, and the protocol from the
Summary	registry entry of the dataset the sidecar names, for the same reason.

Raises:

Type	Description
OSError	The file or its provenance sidecar is missing or unreadable.
ValueError	The sidecar is not a provenance record.

usdata.inspect.Summary

Bases: BaseModel

What one fetched file is, where it came from, and what its format holds.

Exactly one of csv, netcdf, grib2, and nexrad is set, or none of them when the format is bytes-only, its reader is unavailable, or the bytes no longer decode; note then says why. detail returns whichever is set.

dataset_id instance-attribute

dataset_id: str

asset_id instance-attribute

asset_id: str

path instance-attribute

path: Path

size class-attribute instance-attribute

size: int = Field(ge=0, description='Bytes on disk now, not the size provenance recorded')

format instance-attribute

format: AssetFormat

retrieved_at instance-attribute

retrieved_at: AwareUTC

checksum instance-attribute

checksum: str

source_url instance-attribute

source_url: str

csv class-attribute instance-attribute

csv: CsvSummary | None = None

netcdf class-attribute instance-attribute

netcdf: NetcdfSummary | None = None

grib2 class-attribute instance-attribute

grib2: Grib2Summary | None = None

nexrad class-attribute instance-attribute

nexrad: NexradSummary | None = None

note class-attribute instance-attribute

note: str | None = Field(default=None, description='Why a recognized format yielded no detail, when it did not')

detail property

detail: CsvSummary | NetcdfSummary | Grib2Summary | NexradSummary | None

The per-format detail, or None for a bytes-only file or an unavailable reader.

usdata.inspect.CsvSummary

Bases: BaseModel

A delimited text file's header and how many data rows the scan counted.

columns class-attribute instance-attribute

columns: list[str] = Field(description='Header fields, in file order')

units class-attribute instance-attribute

units: dict[str, str] = Field(default_factory=dict, description='Units per column, from the units row an ERDDAP or IBTrACS CSV lays under its header; empty for a CSV with no such row')

row_count class-attribute instance-attribute

row_count: int = Field(ge=0, description='Data rows counted, excluding the header and any units row')

row_limit class-attribute instance-attribute

row_limit: int = Field(gt=0, description='Rows the scan reads before it stops')

truncated class-attribute instance-attribute

truncated: bool = Field(description='The scan stopped early, so row_count is a lower bound')

usdata.inspect.NetcdfSummary

Bases: BaseModel

The data variables of a NetCDF4 file's root group.

variables instance-attribute

variables: list[NetcdfVariable]

usdata.inspect.NetcdfVariable

Bases: BaseModel

One NetCDF4 data variable's shape and the metadata the file states for it.

name instance-attribute

name: str

dims class-attribute instance-attribute

dims: list[str] = Field(description='Dimension names, in array order')

shape class-attribute instance-attribute

shape: list[int] = Field(description='Length of each dimension, in array order')

units class-attribute instance-attribute

units: str | None = None

long_name class-attribute instance-attribute

long_name: str | None = None

usdata.inspect.Grib2Summary

Bases: BaseModel

Every message a GRIB2 file holds, in file order.

messages instance-attribute

messages: list[GribMessage]

variable_for

variable_for(selector: str) -> str

The variable name open() will give the message one index selector fetched.

This closes the loop a partial fetch opens: messages="CAPE:surface" asks in the index sidecar's vocabulary, and the reader answers in ecCodes', so this says which name that selector produces given every message this file holds. Only a partial fetch records selectors.

Parameters:

Name	Type	Description	Default
selector	str	A selector exactly as the provenance recorded it, such as CAPE:surface.	required

Returns:

Type	Description
str	The variable name the GRIB2 naming rule gives that message.

Raises:

Type	Description
KeyError	No message here was fetched for that selector; the message lists the selectors that were.
ValueError	That selector fetched a message holding several fields, as RAP publishes wind components, and the record was written before each field's selector was recorded, so it cannot say which field it named; the message lists their variables.

usdata.inspect.GribMessage

Bases: BaseModel

One GRIB2 message as ecCodes reports it: the keys select matches on, plus the grid.

Two numberings name the same message. file_index counts messages in the local file from zero; object_index is the number the source object's index sidecar gave it, one-based, and is set only for a partial fetch, as is selector, the index selector the message was fetched for.

file_index class-attribute instance-attribute

file_index: int = Field(ge=0, description='Zero-based message position in the local file; fields of one message share it')

object_index class-attribute instance-attribute

object_index: int | None = Field(default=None, ge=1, description='One-based message number in the source object, for a partial fetch')

selector class-attribute instance-attribute

selector: str | None = Field(default=None, description='Index selector this message was fetched for, for a partial fetch')

short_name class-attribute instance-attribute

short_name: str | None = Field(default=None, description='ecCodes shortName')

base_name class-attribute instance-attribute

base_name: str | None = Field(default=None, description="Name the reader starts this message's variable from: shortName, or where ecCodes has none, the MRMS product or parameter_<discipline>_<category>_<number>")

name class-attribute instance-attribute

name: str | None = Field(default=None, description='ecCodes name')

type_of_level class-attribute instance-attribute

type_of_level: str | None = Field(default=None, description='ecCodes typeOfLevel')

level class-attribute instance-attribute

level: str | None = Field(default=None, description='ecCodes level')

step class-attribute instance-attribute

step: str | None = Field(default=None, description='ecCodes step')

units class-attribute instance-attribute

units: str | None = Field(default=None, description='ecCodes units')

shape class-attribute instance-attribute

shape: tuple[int, int] | None = Field(default=None, description='Grid rows and columns')

usdata.inspect.NexradSummary

Bases: BaseModel

The volume coverage pattern and every sweep of a NEXRAD Level II volume, in scan order.

vcp class-attribute instance-attribute

vcp: int | None = Field(description='Volume coverage pattern number; None for a legacy volume')

sweeps instance-attribute

sweeps: list[NexradSweep]

usdata.inspect.NexradSweep

Bases: BaseModel

One sweep of a NEXRAD Level II volume, read from its metadata without decoding moments.

index is what open_nexrad(sweep=...) takes. It is not an elevation: a split cut scans one angle twice, once for reflectivity and dual-pol moments and once for velocity, and SAILS or MRLE rescan the lowest angle several times a volume, so one angle can hold many indices. Choose sweeps here by fixed_angle, moments, and start, then open them by index.

index class-attribute instance-attribute

index: int = Field(ge=0, description='Zero-based position in the volume; what open_nexrad(sweep=...) takes')

elevation_number class-attribute instance-attribute

elevation_number: int = Field(ge=1, description='The one-based VCP cut the sweep scans')

fixed_angle class-attribute instance-attribute

fixed_angle: float = Field(description="Elevation in degrees: the VCP table's angle for the cut, or the first ray's where the volume carries no VCP table")

moments class-attribute instance-attribute

moments: list[str] = Field(description="Moments open_nexrad returns for the sweep, by its names; a legacy volume's spectrum width is in the file but not decoded")

start class-attribute instance-attribute

start: AwareUTC = Field(description="When the sweep's first ray was collected")

end class-attribute instance-attribute

end: AwareUTC = Field(description='When its last ray was collected')

rays class-attribute instance-attribute

rays: int = Field(ge=0, description='Rays received')

complete class-attribute instance-attribute

complete: bool = Field(description='The sweep reached its end; open_nexrad pads one that did not')

sails class-attribute instance-attribute

sails: bool | None = Field(default=None, description='A SAILS low-level rescan; None where there is no VCP table')

mrle class-attribute instance-attribute

mrle: bool | None = Field(default=None, description='An MRLE mid-volume rescan; None where there is no VCP table')

usdata.readers.nexrad_sweeps

nexrad_sweeps(path: str | PathLike[str]) -> list[NexradSweep]

List every sweep in a local NEXRAD Level II volume without decoding any moment.

A sweep index is a position in the volume, not an elevation: split cuts scan one angle twice and SAILS rescans the lowest angle within a volume, so the same index names different angles from one volume coverage pattern to the next. Choose sweeps from this list by angle, moment, and time, then pass their indices to open_nexrad(sweep=...). FetchedAsset.inspect() returns the same list, with the volume coverage pattern, as nexrad.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	A local Level II volume, whole-file gzip or bzip2 compressed or not, written as a string or as any os.PathLike. Nothing is fetched or written.	required

Returns:

Type	Description
list[NexradSweep]	One entry per sweep in scan order.

Raises:

Type	Description
MissingReaderDependency	The radar extra is not installed.
ValueError	The file is not a readable NEXRAD Level II volume.

Reproducible inputs

usdata.pull.pull

pull(manifest_path: str | PathLike[str], *, root: str | PathLike[str] | None = None, force: bool = False, registry: Registry | None = None, update: Iterable[str] = ()) -> PullResult

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

update names assets or datasets whose pins should follow current upstream bytes; it needs an existing lockfile and is exclusive with force.

usdata.pull.plan

plan(manifest_path: str | PathLike[str], *, registry: Registry | None = None) -> Plan

List every source through its adapter and price the result; download nothing.

Validates the whole manifest first, exactly as resolve does, then makes only the requests a listing makes: an S3 listing, or the index and HEAD requests a partial-fetch source needs to work out its byte ranges.

Parameters:

Name	Type	Description	Default
manifest_path	str | PathLike[str]	Path of the manifest YAML file, as a string or any os.PathLike.	required
registry	Registry | None	Registry to resolve dataset ids against; the default one if omitted.	None

Returns:

Type	Description
Plan	A Plan holding each source's assets and the totals over them.

usdata.pull.verify

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

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

usdata.pull.compare_listing

compare_listing(manifest_path: str | PathLike[str], *, registry: Registry | None = None) -> ListingComparison

Compare a manifest's lockfile with what its sources list today; download nothing.

Every source is listed as plan lists it, select rules included, and its assets are matched to the lockfile's entries for that source by id. An asset only in the listing is added, one only in the lockfile removed, and one in both with a different href, or a different size where both give one, changed. A listing that reports no size cannot show a size change; restoring the pin checks the bytes themselves.

Parameters:

Name	Type	Description	Default
manifest_path	str | PathLike[str]	Path of the manifest YAML file, as a string or any os.PathLike.	required
registry	Registry | None	Registry to resolve dataset ids against; the default one if omitted.	None

Returns:

Type	Description
ListingComparison	A ListingComparison with one entry per manifest source.

Raises:

Type	Description
FileNotFoundError	The manifest has no lockfile yet.
ManifestChanged	The manifest changed since its lockfile was written.

usdata.pull.PullResult

Bases: BaseModel

What a pull did.

fetched keeps manifest order, and within a source the assets are ordered by start time and then id; by_source holds the same objects grouped by source key, which is a source's name when it has one and its one-based position otherwise, in the same order. one is for a source that can only ever resolve to one asset.

lockfile instance-attribute

lockfile: Lockfile

lockfile_path instance-attribute

lockfile_path: Path

fetched class-attribute instance-attribute

fetched: list[FetchedAsset] = Field(description='Every asset, in manifest order, then by start time and id within a source')

from_lockfile instance-attribute

from_lockfile: bool

updated class-attribute instance-attribute

updated: list[str] = Field(default_factory=list, description='Ids of assets whose pins were rewritten by update')

mirrored class-attribute instance-attribute

mirrored: list[str] = Field(default_factory=list, description="Ids of assets the mirror restored instead of the source: because the pinned URL no longer served their bytes, or, for those also in unchecked, because the source's credentials are not set; pins are unchanged and each sidecar names the mirror object")

unchecked class-attribute instance-attribute

unchecked: list[str] = Field(default_factory=list, description='Ids of mirrored assets restored without asking their source, because its credentials are not set, so upstream was not checked for changes (ADR 0039)')

by_source class-attribute instance-attribute

by_source: dict[str, list[FetchedAsset]] = Field(default_factory=dict, description='The same assets grouped by source key, in manifest order')

one

one(source: str) -> FetchedAsset

The single asset a source resolved to.

Parameters:

Name	Type	Description	Default
source	str	The source key: its name, or its one-based position as a string.	required

Returns:

Type	Description
FetchedAsset	That source's only asset.

Raises:

Type	Description
KeyError	No source in the result has that key.
ValueError	The source resolved to no asset, or to more than one.

usdata.pull.Plan

Bases: BaseModel

What pulling a manifest would fetch, priced as far as the adapters can measure.

An asset whose adapter reports no size contributes nothing to known_bytes and counts in unknown_sizes instead, so the total is a floor rather than an estimate. A source that matched nothing is kept with no assets; pull would fail on it unless the source sets allow_empty.

manifest instance-attribute

manifest: str

sources class-attribute instance-attribute

sources: list[SourcePlan] = Field(description='One entry per manifest source, in order')

asset_count property

asset_count: int

How many assets the manifest resolves to.

known_bytes property

known_bytes: int

Total measured size across every source.

unknown_sizes property

unknown_sizes: int

How many assets no adapter gave a size for.

unsized_sources property

unsized_sources: list[str]

The sources whose adapters left some size unreported, in manifest order.

usdata.pull.SourcePlan

Bases: BaseModel

What one manifest source would fetch, as its adapter listed it.

source class-attribute instance-attribute

source: str = Field(description="The source's manifest key: its name, or its position")

dataset_id instance-attribute

dataset_id: str

assets instance-attribute

assets: list[Asset]

known_bytes property

known_bytes: int

Total size of the assets this source can measure.

unknown_sizes property

unknown_sizes: int

How many assets their adapter gave no size for.

usdata.pull.Drift

Bases: BaseModel

One lockfile entry whose local copy is missing or altered, or whose source moved on.

asset_id instance-attribute

asset_id: str

dataset_id instance-attribute

dataset_id: str

path instance-attribute

path: Path

problem class-attribute instance-attribute

problem: str = Field(description="'missing', 'checksum mismatch', 'upstream changed', 'gone upstream (<status>)', or 'range refused'; a restore that also tried a mirror appends why the mirror did not help")

usdata.pull.ListingComparison

Bases: BaseModel

A lockfile against today's listings: whether a re-resolve would pin the same assets.

Nothing is downloaded, so the bytes are not compared: restore checks those, and verify checks the cache. What this sees is the set of files, an asset added, removed, or re-described since the lockfile was written.

manifest instance-attribute

manifest: str

lockfile instance-attribute

lockfile: Path

sources class-attribute instance-attribute

sources: list[SourceComparison] = Field(description='One entry per manifest source, in order')

matches property

matches: bool

True when every source matches.

usdata.pull.SourceComparison

Bases: BaseModel

How one source's pinned assets compare with what its adapter lists today.

source class-attribute instance-attribute

source: str = Field(description="The source's manifest key: its name, or its position")

dataset_id instance-attribute

dataset_id: str

added class-attribute instance-attribute

added: list[Asset] = Field(description='Listed today and not pinned')

removed class-attribute instance-attribute

removed: list[Asset] = Field(description='Pinned and no longer listed')

changed class-attribute instance-attribute

changed: list[AssetChange] = Field(description='Pinned and listed, with a different href, or a different size where both the pin and the listing give one')

unchanged class-attribute instance-attribute

unchanged: int = Field(description='How many pinned assets are listed exactly as pinned')

matches property

matches: bool

True when nothing was added, removed, or changed.

usdata.pull.AssetChange

Bases: BaseModel

A pinned asset that today's listing still names, but describes differently.

asset_id instance-attribute

asset_id: str

locked_size class-attribute instance-attribute

locked_size: int | None = Field(description='Size the listing gave when the pin was written')

listed_size class-attribute instance-attribute

listed_size: int | None = Field(description="Size today's listing gives")

locked_href instance-attribute

locked_href: str

listed_href instance-attribute

listed_href: 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)

source_keys

source_keys() -> list[str]

Each source's key: its name when set, otherwise its one-based position.

load classmethod

load(path: str | PathLike[str]) -> 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

name class-attribute instance-attribute

name: str | None = Field(default=None, description='Optional label that keys this source in results and lockfiles')

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)

select class-attribute instance-attribute

select: TimeSelect | None = Field(default=None, description='Keep only the asset nearest an instant; replaces start and end (ADR 0044)')

to_query

to_query() -> Query

Build the Query this source resolves to; select supplies the window when set.

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: AwareUTC

usdata_version instance-attribute

usdata_version: str

assets class-attribute instance-attribute

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

load classmethod

load(path: str | PathLike[str]) -> Lockfile

Read a lockfile written by save.

save

save(path: str | PathLike[str]) -> 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

source class-attribute instance-attribute

source: str | None = Field(default=None, description='Key of the manifest source that resolved this asset')

Citations

usdata.cite_dataset

cite_dataset(dataset: Dataset, *, registry: Registry | None = None) -> Citation

Build the citation for one registry entry.

Parameters:

Name	Type	Description	Default
dataset	Dataset	The entry to cite.	required
registry	Registry | None	Registry supplying the agency name and homepage behind the entry's provider id. The bundled registry by default.	None

Returns:

Type	Description
Citation	A citation carrying the entry's own citation text where it has one, and
Citation	',