usdata 0.7.0__tar.gz → 0.9.0__tar.gz

usdata-0.9.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.9.0
+Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
+Keywords: noaa,usgs,nasa,open-data,scientific-data,provenance
+Author: Jake Van Slyke
+Author-email: Jake Van Slyke <jakervanslyke@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.18
+Requires-Dist: xarray>=2025.1 ; extra == 'netcdf'
+Requires-Dist: h5netcdf[h5py]>=1.8.1 ; extra == 'netcdf'
+Requires-Dist: pandas>=3.0 ; extra == 'pandas'
+Requires-Dist: xradar>=0.12.0 ; extra == 'radar'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jakeryderv/usdata
+Project-URL: Repository, https://github.com/jakeryderv/usdata
+Provides-Extra: netcdf
+Provides-Extra: pandas
+Provides-Extra: radar
+Description-Content-Type: text/markdown
+
+# usdata
+
+Discover U.S. scientific datasets, fetch their files, and keep a reproducible
+record of where every input came from. Use the same Python SDK or CLI across
+supported NOAA and USGS datasets.
+
+**Pre-alpha.** These docs describe the current source checkout. Features marked
+**Unreleased** require a source installation; consult the
+[changelog](CHANGELOG.md) for published versions. Other providers are planned.
+
+## Start here
+
+```sh
+pip install usdata
+usdata search precipitation --location Oklahoma
+usdata info noaa:ghcn-daily
+```
+
+Search uses a curated registry. Fetching contacts the upstream service; readers
+open the resulting local files. Provenance and manifests connect those steps.
+
+- [Quick start and documentation](docs/index.md)
+- [Fetch and analyze data](docs/guides/fetch-and-analyze.md)
+- [Runnable examples with saved outputs](examples/README.md)
+- [Readers](docs/reference/readers.md) and [reproducible manifests](docs/reference/manifests.md)
+
+## Providers
+
+<!-- registry:start -->
+| Provider | Available | Stub | Planned | Next up (unassigned) | Datasets |
+|---|---:|---:|---:|---|---|
+| [NOAA](docs/providers/noaa.md) | 6 | 0 | 23 | — | `ghcn-daily`, `gsom`, `storm-events`, `nexrad-level2`, `goes-abi`, `coastwatch-sst`, +23 planned |
+| [USGS](docs/providers/usgs.md) | 1 | 0 | 2 | — | `water-daily`, +2 planned |
+| [Census Bureau](docs/providers/census.md) | 0 | 0 | 1 | — | +1 planned |
+| [EPA](docs/providers/epa.md) | 0 | 0 | 1 | — | +1 planned |
+| [FEMA](docs/providers/fema.md) | 0 | 0 | 1 | — | +1 planned |
+| [NASA](docs/providers/nasa.md) | 0 | 0 | 1 | — | +1 planned |
+| [USDA](docs/providers/usda.md) | 0 | 0 | 1 | — | +1 planned |
+
+Available datasets are in `code`, stubs in _italics_; planned ones are counted. Available means implemented in this source checkout; consult the [releases](https://github.com/jakeryderv/usdata/releases) for published support. Provider pages link access notes to the generated dataset catalog; [the roadmap](docs/roadmap.md) explains future priorities.
+<!-- registry:end -->
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/).
+
+`just setup` uses the tested Python 3.14.7 pin in `.python-version`. Older Linux
+uv Python 3.14 builds can crash during NumPy array operations; see
+[the upstream fix](https://github.com/astral-sh/python-build-standalone/issues/991).
+
+```sh
+git clone https://github.com/jakeryderv/usdata && cd usdata
+just setup     # install toolchain and dependencies
+just test      # all offline tests
+just check     # format, lint, typecheck, offline tests, generated docs, release notices
+just check-pandas  # install the CSV extra and run the same checks
+just check-radar   # install the radar extra and run the same checks
+just check-netcdf  # install the NetCDF4 extra and run the same checks
+just notebooks    # launch the optional Jupyter examples environment
+just run-notebooks # execute notebooks live in fresh kernels and temporary caches
+just docs-serve # build and preview the documentation locally, with reload
+just check-docs # validate generated content and build the site strictly
+just build     # build wheel and sdist
+just smoke     # exercise core and pandas wheel installations outside the checkout
+just run search radar
+```
+
+Offline tests mechanically block network connections. Tests that hit
+live services run with `just test-live`; see [testing levels and organization](docs/testing.md). CI checks Python 3.11 and 3.14 on
+Linux with core-only, pandas, radar, and NetCDF dependency profiles. Installed-wheel
+checks cover all four profiles on Linux, macOS, and Windows. The full offline and
+live-service suites run on Linux. `just setup` restores a core-only development
+environment; the `check-pandas`, `check-radar`, and `check-netcdf` commands install
+their respective extras.
+
+Releases: `just release minor` opens a version-bump PR; merging it publishes
+to PyPI and creates the tag and GitHub release. See
+[docs/versioning.md](docs/versioning.md).
+
+See [provider access notes](docs/providers/README.md),
+[docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[architecture decisions](docs/adr/README.md) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
+
+## License
+
+[Apache-2.0](LICENSE).

usdata-0.9.0/README.md

@@ -0,0 +1,87 @@
+# usdata
+
+Discover U.S. scientific datasets, fetch their files, and keep a reproducible
+record of where every input came from. Use the same Python SDK or CLI across
+supported NOAA and USGS datasets.
+
+**Pre-alpha.** These docs describe the current source checkout. Features marked
+**Unreleased** require a source installation; consult the
+[changelog](CHANGELOG.md) for published versions. Other providers are planned.
+
+## Start here
+
+```sh
+pip install usdata
+usdata search precipitation --location Oklahoma
+usdata info noaa:ghcn-daily
+```
+
+Search uses a curated registry. Fetching contacts the upstream service; readers
+open the resulting local files. Provenance and manifests connect those steps.
+
+- [Quick start and documentation](docs/index.md)
+- [Fetch and analyze data](docs/guides/fetch-and-analyze.md)
+- [Runnable examples with saved outputs](examples/README.md)
+- [Readers](docs/reference/readers.md) and [reproducible manifests](docs/reference/manifests.md)
+
+## Providers
+
+<!-- registry:start -->
+| Provider | Available | Stub | Planned | Next up (unassigned) | Datasets |
+|---|---:|---:|---:|---|---|
+| [NOAA](docs/providers/noaa.md) | 6 | 0 | 23 | — | `ghcn-daily`, `gsom`, `storm-events`, `nexrad-level2`, `goes-abi`, `coastwatch-sst`, +23 planned |
+| [USGS](docs/providers/usgs.md) | 1 | 0 | 2 | — | `water-daily`, +2 planned |
+| [Census Bureau](docs/providers/census.md) | 0 | 0 | 1 | — | +1 planned |
+| [EPA](docs/providers/epa.md) | 0 | 0 | 1 | — | +1 planned |
+| [FEMA](docs/providers/fema.md) | 0 | 0 | 1 | — | +1 planned |
+| [NASA](docs/providers/nasa.md) | 0 | 0 | 1 | — | +1 planned |
+| [USDA](docs/providers/usda.md) | 0 | 0 | 1 | — | +1 planned |
+
+Available datasets are in `code`, stubs in _italics_; planned ones are counted. Available means implemented in this source checkout; consult the [releases](https://github.com/jakeryderv/usdata/releases) for published support. Provider pages link access notes to the generated dataset catalog; [the roadmap](docs/roadmap.md) explains future priorities.
+<!-- registry:end -->
+
+## Development
+
+Requires [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/).
+
+`just setup` uses the tested Python 3.14.7 pin in `.python-version`. Older Linux
+uv Python 3.14 builds can crash during NumPy array operations; see
+[the upstream fix](https://github.com/astral-sh/python-build-standalone/issues/991).
+
+```sh
+git clone https://github.com/jakeryderv/usdata && cd usdata
+just setup     # install toolchain and dependencies
+just test      # all offline tests
+just check     # format, lint, typecheck, offline tests, generated docs, release notices
+just check-pandas  # install the CSV extra and run the same checks
+just check-radar   # install the radar extra and run the same checks
+just check-netcdf  # install the NetCDF4 extra and run the same checks
+just notebooks    # launch the optional Jupyter examples environment
+just run-notebooks # execute notebooks live in fresh kernels and temporary caches
+just docs-serve # build and preview the documentation locally, with reload
+just check-docs # validate generated content and build the site strictly
+just build     # build wheel and sdist
+just smoke     # exercise core and pandas wheel installations outside the checkout
+just run search radar
+```
+
+Offline tests mechanically block network connections. Tests that hit
+live services run with `just test-live`; see [testing levels and organization](docs/testing.md). CI checks Python 3.11 and 3.14 on
+Linux with core-only, pandas, radar, and NetCDF dependency profiles. Installed-wheel
+checks cover all four profiles on Linux, macOS, and Windows. The full offline and
+live-service suites run on Linux. `just setup` restores a core-only development
+environment; the `check-pandas`, `check-radar`, and `check-netcdf` commands install
+their respective extras.
+
+Releases: `just release minor` opens a version-bump PR; merging it publishes
+to PyPI and creates the tag and GitHub release. See
+[docs/versioning.md](docs/versioning.md).
+
+See [provider access notes](docs/providers/README.md),
+[docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[architecture decisions](docs/adr/README.md) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
+
+## License
+
+[Apache-2.0](LICENSE).

{usdata-0.7.0 → usdata-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.7.0"
+version = "0.9.0"
 description = "Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data"
 readme = "README.md"
 license = "Apache-2.0"
@@ -23,7 +23,7 @@ dependencies = [
     "httpx>=0.28.1",
     "pydantic>=2.7",
     "pyyaml>=6.0",
-    "typer>=0.12",
+    "typer>=0.18",
 ]
 
 [[project.authors]]
@@ -32,6 +32,11 @@ email = "jakervanslyke@gmail.com"
 
 [project.optional-dependencies]
 pandas = ["pandas>=3.0"]
+radar = ["xradar>=0.12.0"]
+netcdf = [
+    "xarray>=2025.1",
+    "h5netcdf[h5py]>=1.8.1",
+]
 
 [project.urls]
 Homepage = "https://github.com/jakeryderv/usdata"
@@ -48,6 +53,18 @@ dev = [
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
+docs = [
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "zensical>=0.0.60",
+]
+examples = [
+    "ipykernel>=6.29",
+    "jupyterlab>=4.3",
+    "matplotlib>=3.9",
+    "nbclient>=0.10",
+    "pandas>=3.0",
+]
 
 [build-system]
 requires = ["uv_build>=0.12.5,<0.13.0"]
@@ -96,5 +113,16 @@ venv = ".venv"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-markers = ["integration: hits live services; skipped unless --run-integration is passed"]
-addopts = "-ra"
+markers = [
+    "l0: pure in-memory logic",
+    "l1: in-process components with controlled transport",
+    "l2: local functional tests with filesystem or real decoders",
+    "l3: controlled service deployment (currently unused)",
+    "l4: production or upstream-live compatibility",
+    "live: hits upstream services; requires --run-live",
+    "integration: compatibility alias for live",
+    "pandas: optional CSV reader coverage",
+    "radar: optional radar reader coverage",
+    "netcdf: optional NetCDF reader coverage",
+]
+addopts = "-ra --strict-markers"

{usdata-0.7.0 → usdata-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.7.0"
+version = "0.9.0"
 description = "Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data"
 readme = "README.md"
 license = "Apache-2.0"
@@ -19,11 +19,13 @@ dependencies = [
     "httpx>=0.28.1",
     "pydantic>=2.7",
     "pyyaml>=6.0",
-    "typer>=0.12",
+    "typer>=0.18",
 ]
 
 [project.optional-dependencies]
 pandas = ["pandas>=3.0"]
+radar = ["xradar>=0.12.0"]
+netcdf = ["xarray>=2025.1", "h5netcdf[h5py]>=1.8.1"]
 
 [project.urls]
 Homepage = "https://github.com/jakeryderv/usdata"
@@ -40,6 +42,18 @@ dev = [
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
+docs = [
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "zensical>=0.0.60",
+]
+examples = [
+    "ipykernel>=6.29",
+    "jupyterlab>=4.3",
+    "matplotlib>=3.9",
+    "nbclient>=0.10",
+    "pandas>=3.0",
+]
 
 [build-system]
 requires = ["uv_build>=0.12.5,<0.13.0"]
@@ -72,6 +86,15 @@ venv = ".venv"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = [
-    "integration: hits live services; skipped unless --run-integration is passed",
+    "l0: pure in-memory logic",
+    "l1: in-process components with controlled transport",
+    "l2: local functional tests with filesystem or real decoders",
+    "l3: controlled service deployment (currently unused)",
+    "l4: production or upstream-live compatibility",
+    "live: hits upstream services; requires --run-live",
+    "integration: compatibility alias for live",
+    "pandas: optional CSV reader coverage",
+    "radar: optional radar reader coverage",
+    "netcdf: optional NetCDF reader coverage",
 ]
-addopts = "-ra"
+addopts = "-ra --strict-markers"

{usdata-0.7.0 → usdata-0.9.0}/src/usdata/__init__.py

@@ -10,10 +10,11 @@ try:
 except PackageNotFoundError:  # running from a source tree without an install
     __version__ = "0.0.0"
 
-from usdata.models import Asset, BBox, Dataset, Provenance, Query, TimeRange
+from usdata.models import Asset, BBox, Dataset, Provenance, Query, TemporalSelection, TimeRange
 from usdata.pull import pull, verify
 from usdata.query import build_query
 from usdata.registry import DatasetNotFound, Registry, SearchResult, default_registry
+from usdata.selection import select_by_time
 
 __all__ = [
     "Asset",
@@ -24,6 +25,7 @@ __all__ = [
     "Query",
     "Registry",
     "SearchResult",
+    "TemporalSelection",
     "TimeRange",
     "__version__",
     "build_query",
@@ -31,6 +33,7 @@ __all__ = [
     "get",
     "pull",
     "search",
+    "select_by_time",
     "verify",
 ]
 

usdata-0.9.0/src/usdata/_netcdf.py

@@ -0,0 +1,36 @@
+"""Local, eagerly loaded NetCDF4 reading behind the netcdf extra."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from usdata.readers import MissingReaderDependency
+
+if TYPE_CHECKING:
+    from usdata.fetch import FetchedAsset
+
+
+def open_netcdf(fetched: FetchedAsset) -> Any:
+    """Load a NetCDF4 root Dataset, then close every source file handle."""
+    try:
+        xarray = import_module("xarray")
+        import_module("h5netcdf")
+        import_module("h5py")
+    except ModuleNotFoundError as error:
+        if error.name not in {"xarray", "h5netcdf", "h5py"}:
+            raise
+        raise MissingReaderDependency(
+            'NetCDF4 reading requires xarray and h5netcdf; install: pip install "usdata[netcdf]"'
+        ) from error
+    # A local file object and fixed engine prevent interpretation as an OPeNDAP URL.
+    with (
+        fetched.path.open("rb") as stream,
+        xarray.open_dataset(stream, engine="h5netcdf", chunks=None) as dataset,
+    ):
+        dataset.load()
+    dataset.attrs["usdata"] = {
+        "asset_id": fetched.asset.id,
+        "provenance": fetched.provenance.model_dump(mode="json"),
+    }
+    return dataset

usdata-0.9.0/src/usdata/_radar.py

@@ -0,0 +1,123 @@
+"""Local NEXRAD Level II decoding behind the radar extra."""
+
+from __future__ import annotations
+
+import bz2
+import gzip
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from usdata.readers import MissingReaderDependency, RadarDecodeError
+
+# NOAA RDA/RPG ICD 2620002Y, Table XVII-I notes 21 and 30.
+MOMENT_FLAG_COUNTS = {
+    "DBZH": 2,
+    "VRADH": 2,
+    "WRADH": 2,
+    "ZDR": 2,
+    "PHIDP": 2,
+    "RHOHV": 2,
+    "CCORH": 8,
+}
+
+if TYPE_CHECKING:
+    from usdata.fetch import FetchedAsset
+
+
+def _check_sweeps(content: bytes, sweep: int | list[int] | None) -> None:
+    """Reject decoder tables that pair a sweep with another sweep's coordinates.
+
+    xradar 0.12 can omit an interior sweep without an end marker from its data
+    table while keeping its moment metadata. The coordinate list then shifts.
+    Compare record identities, not just ray counts: equal-length sweeps can
+    otherwise silently acquire another sweep's coordinates and timestamps.
+    """
+    backend = import_module("xradar.io.backends.nexrad_level2")
+    with backend.NEXRADLevel2File(content, loaddata=False) as volume:
+        # Parsing completeness also populates the per-sweep data tables.
+        _ = volume.incomplete_sweeps
+        moments = volume.msg_31_data_header
+        coordinates = volume.msg_31_header
+        requested = (
+            list(range(len(moments)))
+            if sweep is None
+            else (sweep if isinstance(sweep, list) else [sweep])
+        )
+        for index in requested:
+            if index >= len(moments):
+                raise ValueError(f"sweep {index} is outside this volume's {len(moments)} sweeps")
+            data = volume.data.get(index)
+            rays = coordinates[index] if index < len(coordinates) else []
+            # Non-radial messages may occur within a sweep or after its last
+            # received ray. Follow the decoder's traversal, excluding those
+            # records, instead of requiring record_end to be a radial message.
+            expected_records = []
+            if data is not None:
+                intermediate = {record["record_number"] for record in data["intermediate_records"]}
+                expected_records = [
+                    record
+                    for record in range(data["record_number"], data["record_end"] + 1)
+                    if record not in intermediate
+                ]
+            if (
+                data is None
+                or not rays
+                or moments[index]["record_number"] != data["record_number"]
+                or [ray["record_number"] for ray in rays] != expected_records
+            ):
+                raise RadarDecodeError(
+                    f"cannot safely decode sweep {index}: NEXRAD moment and coordinate records "
+                    "do not agree; select an unaffected sweep explicitly with open(sweep=...) "
+                    "or use another decoder. No sweeps were silently dropped."
+                )
+
+
+def open_nexrad(fetched: FetchedAsset, *, sweep: int | list[int] | None = None) -> Any:
+    """Decode a local volume into a fully loaded xarray DataTree."""
+    try:
+        xradar = import_module("xradar")
+    except ModuleNotFoundError as error:
+        if error.name != "xradar":
+            raise
+        raise MissingReaderDependency(
+            'NEXRAD reading requires xradar; install it with: pip install "usdata[radar]" '
+            '(or uv add "usdata[radar]")'
+        ) from error
+
+    # Bytes prevent remote URL interpretation and work across the backend's
+    # repeated sweep reads. Compressed source files stay unchanged in the cache.
+    content = fetched.path.read_bytes()
+    if content.startswith(b"\x1f\x8b"):
+        content = gzip.decompress(content)
+    elif content.startswith(b"BZh"):
+        content = bz2.decompress(content)
+    _check_sweeps(content, sweep)
+    radar = xradar.io.open_nexradlevel2_datatree(content, sweep=sweep, incomplete_sweep="pad")
+    try:
+        radar.load()
+    finally:
+        radar.close()
+    for node in radar.subtree:
+        for name, variable in node.ds.variables.items():
+            # The backend records the entire input byte string as `source`.
+            # Provenance below is the durable reference, not that decoder buffer.
+            variable.encoding.pop("source", None)
+            if name in MOMENT_FLAG_COUNTS and "range" in variable.dims:
+                scale = variable.encoding.get("scale_factor")
+                offset = variable.encoding.get("add_offset")
+                if scale is not None and offset is not None:
+                    # xradar 0.12 does not supply _FillValue for NEXRAD flags.
+                    # Compare using each moment's native scale, not fixed units.
+                    data = node[name]
+                    valid = data.notnull()
+                    for code in range(MOMENT_FLAG_COUNTS[name]):
+                        valid = valid & (data != offset + code * scale)
+                    masked = data.where(valid)
+                    masked.encoding = data.encoding.copy()
+                    node[name] = masked
+    radar.attrs["usdata"] = {
+        "asset_id": fetched.asset.id,
+        "provenance": fetched.provenance.model_dump(mode="json"),
+        "sweeps": [name.lstrip("/") for name in radar.groups if name.startswith("/sweep_")],
+    }
+    return radar

{usdata-0.7.0 → usdata-0.9.0}/src/usdata/data/registry.yaml

@@ -105,21 +105,22 @@ datasets:
 
   - id: noaa:goes-abi
     provider: noaa
-    status: planned
+    status: available
     domain: weather-satellites
-    target: later
-    title: GOES-R ABI Satellite Imagery
-    description: >-
-      Advanced Baseline Imager products from GOES-16, 18, and 19 in the public
-      noaa-goes16/18/19 S3 buckets, laid out as PRODUCT/YYYY/DDD/HH/ with one
-      NetCDF per scan (for example ABI-L2-CMIPC). Same anonymous S3 pattern as
-      NEXRAD, plus product, satellite, and channel selection.
-    keywords: [satellite, imagery, goes, abi, clouds, fire, radiance, netcdf]
+    since: "0.8"
+    title: GOES-R ABI CONUS Cloud and Moisture Imagery
+    description: >-
+      Single-channel CONUS Cloud and Moisture Imagery (ABI-L2-CMIPC) from
+      GOES-16, 17, 18, and 19 in anonymous NOAA S3 buckets. Select an explicit
+      satellite, channel, and scan-start interval; each asset is a complete
+      NetCDF scene with no geographic or variable subsetting.
+    keywords: [satellite, imagery, goes, abi, clouds, infrared, reflectance, netcdf, conus]
     protocol: s3
     homepage: https://registry.opendata.aws/noaa-goes/
     license: US Government Work (public domain)
-    temporal_extent: { start: "2017-01-01T00:00:00Z" }
-    capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: true }
+    temporal_extent: { start: "2017-02-28T00:00:00Z" }
+    capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
+    adapter: usdata.providers.noaa.goes:GoesAbi
 
   - id: noaa:goes-glm
     provider: noaa
@@ -139,21 +140,24 @@ datasets:
 
   - id: noaa:storm-events
     provider: noaa
-    status: planned
+    status: available
     domain: severe-weather
-    target: later
+    since: "0.8"
     title: Storm Events Database
     description: >-
-      NCEI's record of significant weather events since 1950 (tornadoes, hail,
-      wind, floods, and more) with locations, damage, and narratives. Published
-      as per-year gzipped CSV files (details, fatalities, locations) in a plain
-      HTTPS directory; the first NCEI bulk-directory dataset.
+      NCEI's significant-weather event details since 1950, with locations,
+      impacts, and narratives. Anonymous whole-year gzipped CSV archives;
+      select the latest creation-date revision for each requested year.
+      No server-side row, location, or variable subsetting. Historical event
+      coverage and reporting practices vary; fatalities and locations tables
+      are separate products not included by this adapter.
     keywords: [storms, tornado, hail, wind, flood, damage, severe weather, events]
     protocol: http
-    homepage: https://www.ncdc.noaa.gov/stormevents/
+    homepage: https://www.ncei.noaa.gov/access/storm-events-database/
     license: US Government Work (public domain)
     temporal_extent: { start: "1950-01-01T00:00:00Z" }
-    capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
+    capabilities: { spatial_subset: false, temporal_subset: false, variable_subset: false }
+    adapter: usdata.providers.noaa.storm_events:StormEvents
 
   - id: noaa:hurdat2
     provider: noaa

{usdata-0.7.0 → usdata-0.9.0}/src/usdata/fetch.py

@@ -34,17 +34,27 @@ class FetchedAsset(BaseModel):
         parse_dates: list[str] | None = None,
         usecols: list[str] | None = None,
         nrows: int | None = None,
+        sweep: int | list[int] | None = None,
     ) -> Any:
-        """Open this local CSV as a DataFrame; requires the ``pandas`` extra.
+        """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"]``. See ``usdata.readers.open_asset`` for options.
+        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.
         """
         from usdata.readers import open_asset
 
         return open_asset(
-            self, reader=reader, dtype=dtype, parse_dates=parse_dates, usecols=usecols, nrows=nrows
+            self,
+            reader=reader,
+            dtype=dtype,
+            parse_dates=parse_dates,
+            usecols=usecols,
+            nrows=nrows,
+            sweep=sweep,
         )
 
 

{usdata-0.7.0 → usdata-0.9.0}/src/usdata/models.py

@@ -9,9 +9,9 @@ from __future__ import annotations
 
 import math
 import re
-from datetime import datetime
+from datetime import datetime, timedelta
 from enum import StrEnum
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -79,6 +79,12 @@ class BBox(BaseModel):
     @classmethod
     def from_point(cls, lat: float, lon: float, radius_km: float = 0.0) -> BBox:
         """Box around a point. Uses a flat-earth approximation, fine for small radii."""
+        if not math.isfinite(lat) or not -90 <= lat <= 90:
+            raise ValueError("lat must be finite and between -90 and 90")
+        if not math.isfinite(lon) or not -180 <= lon <= 180:
+            raise ValueError("lon must be finite and between -180 and 180")
+        if not math.isfinite(radius_km) or radius_km < 0:
+            raise ValueError("radius_km must be finite and nonnegative")
         dlat = radius_km / 111.0
         dlon = radius_km / (111.0 * max(math.cos(math.radians(lat)), 1e-6))
         return cls(
@@ -223,6 +229,22 @@ class Asset(BaseModel):
     bbox: BBox | None = None
 
 
+class TemporalSelection(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: datetime
+    tolerance: timedelta
+    direction: Literal["nearest", "at_or_before"]
+    asset: Asset | None
+    offset_seconds: float | None
+    candidate_count: int = Field(ge=0)
+    eligible_count: int = Field(ge=0)
+
+
 class Provenance(BaseModel):
     """Everything needed to say where a local file came from and re-fetch it."""