usdata 0.18.0__tar.gz → 0.19.0__tar.gz

usdata-0.19.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.19.0
+Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
+Keywords: noaa,usgs,open-data,scientific-data,provenance,reproducible-research,weather,climate,meteorology
+Author: Jake Van Slyke
+Author-email: Jake Van Slyke <jakervanslyke@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.18
+Requires-Dist: eccodes>=2.48 ; extra == 'grib'
+Requires-Dist: eccodeslib>=2.48 ; sys_platform == 'linux' and extra == 'grib'
+Requires-Dist: xarray>=2025.1 ; extra == 'grib'
+Requires-Dist: numpy>=2 ; extra == 'grib'
+Requires-Dist: xarray>=2025.1 ; extra == 'netcdf'
+Requires-Dist: h5netcdf[h5py]>=1.8.1 ; extra == 'netcdf'
+Requires-Dist: pandas>=2.2 ; extra == 'pandas'
+Requires-Dist: xradar>=0.12.0 ; extra == 'radar'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://usdata.dev/
+Project-URL: Documentation, https://docs.usdata.dev/
+Project-URL: Repository, https://github.com/jakeryderv/usdata
+Project-URL: Examples, https://usdata.dev/examples/
+Project-URL: Changelog, https://github.com/jakeryderv/usdata/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jakeryderv/usdata/issues
+Provides-Extra: grib
+Provides-Extra: netcdf
+Provides-Extra: pandas
+Provides-Extra: radar
+Description-Content-Type: text/markdown
+
+# usdata
+
+[![PyPI](https://img.shields.io/pypi/v/usdata)](https://pypi.org/project/usdata/)
+[![Python](https://img.shields.io/pypi/pyversions/usdata)](https://pypi.org/project/usdata/)
+[![CI](https://github.com/jakeryderv/usdata/actions/workflows/ci.yml/badge.svg)](https://github.com/jakeryderv/usdata/actions/workflows/ci.yml)
+[![Live checks](https://github.com/jakeryderv/usdata/actions/workflows/integration.yml/badge.svg)](https://github.com/jakeryderv/usdata/actions/workflows/integration.yml)
+[![License](https://img.shields.io/github/license/jakeryderv/usdata)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docs.usdata.dev-2f5bea)](https://docs.usdata.dev/)
+
+[![usdata.dev: public science, reproducible inputs](https://usdata.dev/og.png)](https://usdata.dev/)
+
+Reproducible acquisition of U.S. public scientific data. One Python SDK and
+CLI discovers curated NOAA and USGS datasets, fetches their files, and keeps a
+record of every input: a manifest names them, a lockfile pins them by checksum,
+and the record of what was fetched is what a methods section cites. Analysis
+stays in pandas and xarray; usdata only acquires. If you need every product
+one agency publishes, that agency's own library is the better tool; usdata is
+for pinning inputs across sources and proving later that they have not changed.
+
+```sh
+pip install "usdata[pandas]"
+usdata search precipitation --location Oklahoma
+usdata fetch noaa:ghcn-daily -p stations=USW00013967 --start 2024-05-06 --end 2024-05-07
+usdata pull dataset.yaml && usdata cite dataset.yaml
+```
+
+The same four steps from Python:
+
+```python
+from usdata import build_query, fetch, get, pull
+
+query = build_query(start="2024-05-06", end="2024-05-07", stations="USW00013967")
+items = fetch(get("noaa:ghcn-daily"), query)
+frame = items[0].open()  # pandas DataFrame, units and provenance in frame.attrs
+result = pull("dataset.yaml")  # every manifest source, pinned in dataset.lock.json
+print(result.fetched[0].provenance.checksum)  # what usdata cite reports
+```
+
+**Alpha.** Releases are tested and lockfiles are stable, but the Python API
+and CLI can change between minor versions; the [changelog](CHANGELOG.md) marks
+breaking changes.
+
+## Where to look
+
+| | |
+| --- | --- |
+| [usdata.dev](https://usdata.dev/) | What it is for: the [dataset browser](https://usdata.dev/datasets/) and [worked examples](https://usdata.dev/examples/) with saved results |
+| [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
+| [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
+
+Twenty datasets are available today and twenty-five more are planned, grouped
+by agency and product family in the [catalog](docs/providers/README.md).
+
+## How this compares
+
+usdata resolves a place, a time window, and a few parameters to the exact
+files that satisfy them, then pins those files so the same inputs can be
+restored and verified later. Neighbouring tools each do part of that.
+
+| Tool | What it does | What usdata adds |
+| --- | --- | --- |
+| [pooch](https://www.fatiando.org/pooch/) | Downloads and verifies files from a registry of names, hashes, and a base URL you write | Discovery: the query resolves to the URLs, and the lockfile is written, not authored |
+| [intake](https://intake.readthedocs.io/) | Describes datasets in catalogs and opens them through drivers | Checksums, lockfiles, and provenance; usdata stops at handing a file to pandas or xarray |
+| [DVC](https://dvc.org/) | Versions data files and can track one URL by its ETag or hash | Knowing which URLs a scientific question needs, across agencies |
+| [Herbie](https://herbie.readthedocs.io/) | Deep access to model output, including subsetting GRIB2 through index files | One interface across observations, radar, satellite, and models, with a lockfile; usdata's index-file fetch reproduces Herbie's for that reason |
+| [dataretrieval](https://github.com/DOI-USGS/dataretrieval-python) | Full coverage of USGS water data | Cross-agency pinning; use dataretrieval for USGS breadth |
+
+## Contributing
+
+Setup, commands, checks, and the release procedure are in
+[CONTRIBUTING.md](CONTRIBUTING.md). The project record lives beside it:
+[architecture](docs/architecture.md), [testing](docs/testing.md),
+[decisions](docs/adr/README.md), [roadmap](docs/roadmap.md), and
+[versioning](docs/versioning.md). The main way the project grows is a new
+dataset, following [adding a dataset](docs/guides/adding-a-dataset.md).
+
+## License
+
+[Apache-2.0](LICENSE).

usdata-0.19.0/README.md

@@ -0,0 +1,79 @@
+# usdata
+
+[![PyPI](https://img.shields.io/pypi/v/usdata)](https://pypi.org/project/usdata/)
+[![Python](https://img.shields.io/pypi/pyversions/usdata)](https://pypi.org/project/usdata/)
+[![CI](https://github.com/jakeryderv/usdata/actions/workflows/ci.yml/badge.svg)](https://github.com/jakeryderv/usdata/actions/workflows/ci.yml)
+[![Live checks](https://github.com/jakeryderv/usdata/actions/workflows/integration.yml/badge.svg)](https://github.com/jakeryderv/usdata/actions/workflows/integration.yml)
+[![License](https://img.shields.io/github/license/jakeryderv/usdata)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-docs.usdata.dev-2f5bea)](https://docs.usdata.dev/)
+
+[![usdata.dev: public science, reproducible inputs](https://usdata.dev/og.png)](https://usdata.dev/)
+
+Reproducible acquisition of U.S. public scientific data. One Python SDK and
+CLI discovers curated NOAA and USGS datasets, fetches their files, and keeps a
+record of every input: a manifest names them, a lockfile pins them by checksum,
+and the record of what was fetched is what a methods section cites. Analysis
+stays in pandas and xarray; usdata only acquires. If you need every product
+one agency publishes, that agency's own library is the better tool; usdata is
+for pinning inputs across sources and proving later that they have not changed.
+
+```sh
+pip install "usdata[pandas]"
+usdata search precipitation --location Oklahoma
+usdata fetch noaa:ghcn-daily -p stations=USW00013967 --start 2024-05-06 --end 2024-05-07
+usdata pull dataset.yaml && usdata cite dataset.yaml
+```
+
+The same four steps from Python:
+
+```python
+from usdata import build_query, fetch, get, pull
+
+query = build_query(start="2024-05-06", end="2024-05-07", stations="USW00013967")
+items = fetch(get("noaa:ghcn-daily"), query)
+frame = items[0].open()  # pandas DataFrame, units and provenance in frame.attrs
+result = pull("dataset.yaml")  # every manifest source, pinned in dataset.lock.json
+print(result.fetched[0].provenance.checksum)  # what usdata cite reports
+```
+
+**Alpha.** Releases are tested and lockfiles are stable, but the Python API
+and CLI can change between minor versions; the [changelog](CHANGELOG.md) marks
+breaking changes.
+
+## Where to look
+
+| | |
+| --- | --- |
+| [usdata.dev](https://usdata.dev/) | What it is for: the [dataset browser](https://usdata.dev/datasets/) and [worked examples](https://usdata.dev/examples/) with saved results |
+| [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
+| [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
+
+Twenty datasets are available today and twenty-five more are planned, grouped
+by agency and product family in the [catalog](docs/providers/README.md).
+
+## How this compares
+
+usdata resolves a place, a time window, and a few parameters to the exact
+files that satisfy them, then pins those files so the same inputs can be
+restored and verified later. Neighbouring tools each do part of that.
+
+| Tool | What it does | What usdata adds |
+| --- | --- | --- |
+| [pooch](https://www.fatiando.org/pooch/) | Downloads and verifies files from a registry of names, hashes, and a base URL you write | Discovery: the query resolves to the URLs, and the lockfile is written, not authored |
+| [intake](https://intake.readthedocs.io/) | Describes datasets in catalogs and opens them through drivers | Checksums, lockfiles, and provenance; usdata stops at handing a file to pandas or xarray |
+| [DVC](https://dvc.org/) | Versions data files and can track one URL by its ETag or hash | Knowing which URLs a scientific question needs, across agencies |
+| [Herbie](https://herbie.readthedocs.io/) | Deep access to model output, including subsetting GRIB2 through index files | One interface across observations, radar, satellite, and models, with a lockfile; usdata's index-file fetch reproduces Herbie's for that reason |
+| [dataretrieval](https://github.com/DOI-USGS/dataretrieval-python) | Full coverage of USGS water data | Cross-agency pinning; use dataretrieval for USGS breadth |
+
+## Contributing
+
+Setup, commands, checks, and the release procedure are in
+[CONTRIBUTING.md](CONTRIBUTING.md). The project record lives beside it:
+[architecture](docs/architecture.md), [testing](docs/testing.md),
+[decisions](docs/adr/README.md), [roadmap](docs/roadmap.md), and
+[versioning](docs/versioning.md). The main way the project grows is a new
+dataset, following [adding a dataset](docs/guides/adding-a-dataset.md).
+
+## License
+
+[Apache-2.0](LICENSE).

{usdata-0.18.0 → usdata-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.18.0"
+version = "0.19.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"
@@ -8,16 +8,27 @@ requires-python = ">=3.11"
 keywords = [
     "noaa",
     "usgs",
-    "nasa",
     "open-data",
     "scientific-data",
     "provenance",
+    "reproducible-research",
+    "weather",
+    "climate",
+    "meteorology",
 ]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
     "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Scientific/Engineering :: Hydrology",
 ]
 dependencies = [
     "httpx>=0.28.1",
@@ -48,6 +59,9 @@ grib = [
 Homepage = "https://usdata.dev/"
 Documentation = "https://docs.usdata.dev/"
 Repository = "https://github.com/jakeryderv/usdata"
+Examples = "https://usdata.dev/examples/"
+Changelog = "https://github.com/jakeryderv/usdata/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jakeryderv/usdata/issues"
 
 [project.scripts]
 usdata = "usdata.cli:app"

{usdata-0.18.0 → usdata-0.19.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.18.0"
+version = "0.19.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"
@@ -8,12 +8,30 @@ authors = [
     { name = "Jake Van Slyke", email = "jakervanslyke@gmail.com" }
 ]
 requires-python = ">=3.11"
-keywords = ["noaa", "usgs", "nasa", "open-data", "scientific-data", "provenance"]
+keywords = [
+    "noaa",
+    "usgs",
+    "open-data",
+    "scientific-data",
+    "provenance",
+    "reproducible-research",
+    "weather",
+    "climate",
+    "meteorology",
+]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
     "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Scientific/Engineering :: Hydrology",
 ]
 dependencies = [
     "httpx>=0.28.1",
@@ -38,6 +56,9 @@ grib = [
 Homepage = "https://usdata.dev/"
 Documentation = "https://docs.usdata.dev/"
 Repository = "https://github.com/jakeryderv/usdata"
+Examples = "https://usdata.dev/examples/"
+Changelog = "https://github.com/jakeryderv/usdata/blob/main/CHANGELOG.md"
+Issues = "https://github.com/jakeryderv/usdata/issues"
 
 [project.scripts]
 usdata = "usdata.cli:app"

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/_fetch.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import Mapping
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -169,12 +170,31 @@ def _fetch_with(
     root: Path | None = None,
     force: bool = False,
 ) -> list[FetchedAsset]:
-    """Run the loop on an adapter the caller opened, so one adapter can serve many queries."""
-    assets = adapter.list_assets(query)
+    """Run the loop on an adapter the caller opened, so one adapter can serve many queries.
+
+    The listing is put in the order every result promises, by ``asset.time.start``
+    then id, so no adapter has to sort and no caller has to sort defensively.
+    """
+    assets = ordered(adapter.list_assets(query))
     _progress.batch([asset.size for asset in assets])
     return [_fetch_asset(dataset, a, adapter, root=root, force=force) for a in assets]
 
 
+def ordered(assets: list[Asset]) -> list[Asset]:
+    """``assets`` by start time, then id; assets without a start time come last, by id."""
+    return sorted(
+        assets,
+        key=lambda asset: (
+            asset.time is None or asset.time.start is None,
+            asset.time.start if asset.time is not None and asset.time.start is not None else _NEVER,
+            asset.id,
+        ),
+    )
+
+
+_NEVER = datetime.max.replace(tzinfo=UTC)
+
+
 def fetch(
     dataset: Dataset,
     query: Query,

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/cli/app.py

@@ -184,7 +184,10 @@ def search(
         typer.Option("--location", "--state", help="State, 'County, ST', or quoted FIPS code."),
     ] = None,
     start: Annotated[str | None, typer.Option(help="ISO date or datetime.")] = None,
-    end: Annotated[str | None, typer.Option(help="ISO date or datetime.")] = None,
+    end: Annotated[
+        str | None,
+        typer.Option(help="ISO date or datetime; a date alone runs to the end of that UTC day."),
+    ] = None,
     planned: Annotated[
         bool, typer.Option("--planned", help="Include planned datasets that have no adapter yet.")
     ] = False,
@@ -321,7 +324,10 @@ def fetch(
     lon: Annotated[float | None, typer.Option()] = None,
     radius_km: Annotated[float, typer.Option(help="Radius around --lat/--lon.")] = 50.0,
     start: Annotated[str | None, typer.Option(help="ISO date or datetime.")] = None,
-    end: Annotated[str | None, typer.Option(help="ISO date or datetime.")] = None,
+    end: Annotated[
+        str | None,
+        typer.Option(help="ISO date or datetime; a date alone runs to the end of that UTC day."),
+    ] = None,
     variables: Annotated[
         str | None, typer.Option("--vars", help="Comma-separated variable names.")
     ] = None,
@@ -507,16 +513,28 @@ def pull(
     except (httpx.HTTPError, ChecksumMismatch) as e:
         typer.secho(f"fetch failed: {e}", err=True, fg="red")
         raise typer.Exit(code=4) from None
-    updated = set(result.updated)
+    updated, mirrored = set(result.updated), set(result.mirrored)
     if not quiet:
         for f in result.fetched:
-            tag = "updated" if f.asset.id in updated else "cached" if f.from_cache else "fetched"
+            if f.asset.id in updated:
+                tag = "updated"
+            elif f.asset.id in mirrored:
+                tag = "mirrored"
+            else:
+                tag = "cached" if f.from_cache else "fetched"
             typer.echo(f"{f.path}\t{tag}\t{f.provenance.size} bytes")
     if result.updated:
         mode = f"updated {len(result.updated)} pin(s) in"
     else:
         mode = "restored from" if result.from_lockfile else "wrote"
     typer.echo(f"{len(result.fetched)} asset(s); {mode} {result.lockfile_path}", err=True)
+    if result.mirrored:
+        typer.secho(
+            f"{len(result.mirrored)} asset(s) changed upstream and were restored from the "
+            "mirror; the lockfile still pins the source. Pass --update to accept new bytes.",
+            err=True,
+            fg="yellow",
+        )
 
 
 @app.command()

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/data/registry.yaml

@@ -1227,19 +1227,54 @@ datasets:
 
   - id: usgs:earthquakes
     provider: usgs
-    status: planned
+    status: available
     domain: natural-hazards
-    target: later
+    since: "0.19"
     title: Earthquake Catalog (ComCat)
     description: >-
-      Global earthquake events with location, magnitude, and depth from the
-      ANSS Comprehensive Catalog via the FDSN event web service. Anonymous
-      REST with bbox, time, and magnitude filters.
-    keywords: [earthquakes, seismic, geology, hazards, comcat, fdsn]
+      Global earthquake events with origin time, epicenter, depth, magnitude, and review
+      status from the ANSS Comprehensive Catalog through the FDSN event web service.
+      Anonymous REST filtered by bounding box, time window, magnitude, and depth, served as
+      CSV with fixed columns; the service caps a response at 20,000 events, so longer
+      selections arrive as pages ordered by time. Events are revised as networks review them.
+    keywords: [earthquakes, seismic, geology, hazards, comcat, fdsn, anss]
     protocol: http
     homepage: https://earthquake.usgs.gov/fdsnws/event/1/
     license: US Government Work (public domain)
+    spatial_extent: { west: -180.0, south: -90.0, east: 180.0, north: 90.0 }
+    temporal_extent: { start: "1900-01-01T00:00:00Z" }
     capabilities: { spatial_subset: true, temporal_subset: true, variable_subset: false }
+    summary: Earthquake events
+    formats: [CSV]
+    selection: Events inside an inclusive UTC window and optional box, magnitude, and depth bounds
+    inputs: Both timestamps; optionally a location or bbox and magnitude or depth bounds
+    reader: pandas
+    guide: docs/providers/usgs-earthquakes.md
+    examples:
+      - examples/earthquakes/README.md
+    resolution:
+      spatial: "Point epicenters in decimal degrees, as located by the contributing network"
+      temporal: "Origin times to the millisecond"
+    update_frequency: >-
+      Continuous; events post automatically from contributing networks and are superseded by
+      reviewed versions
+    citation: >-
+      U.S. Geological Survey, Earthquake Hazards Program, 2017, Advanced National Seismic
+      System (ANSS) Comprehensive Catalog of Earthquake Events and Products,
+      doi:10.5066/F7MS3QZH
+    terms: https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
+    variables:
+      - { name: time, units: "ISO 8601 UTC", description: "Origin time of the event" }
+      - { name: latitude, units: "degrees north", description: "Epicenter latitude" }
+      - { name: longitude, units: "degrees east", description: "Epicenter longitude" }
+      - { name: depth, units: km, description: "Hypocenter depth below sea level" }
+      - { name: mag, units: "magnitude", description: "Magnitude on the scale magType names" }
+      - { name: magType, description: "Magnitude scale, such as ml or mw" }
+      - { name: place, description: "Nearby place and distance, as a phrase" }
+      - { name: type, description: "Event type; earthquake unless otherwise" }
+      - { name: status, description: "automatic or reviewed" }
+      - { name: updated, units: "ISO 8601 UTC", description: "When the event was last revised" }
+    adapter: usdata.providers.usgs.earthquakes:Earthquakes
 
   - id: usgs:3dep-elevation
     provider: usgs

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/doctor.py

@@ -29,6 +29,7 @@ from pydantic import BaseModel
 from usdata import __version__
 from usdata._grib import LIBRARY_HINT
 from usdata.cache import ENV_VAR, cache_dir
+from usdata.mirror import ENV_VAR as MIRROR_ENV_VAR
 from usdata.models import READER_EXTRAS
 from usdata.protocols import http
 from usdata.registry import default_registry
@@ -39,7 +40,7 @@ READER_MODULES: dict[str, tuple[str, ...]] = {
     "netcdf": ("xarray", "h5netcdf"),
     "grib": ("eccodes", "xarray", "numpy"),
 }
-ENV_VARS = (ENV_VAR, "XDG_CACHE_HOME")
+ENV_VARS = (ENV_VAR, "XDG_CACHE_HOME", MIRROR_ENV_VAR)
 PROBE_TIMEOUT = 5.0
 MAX_PROBES = 8
 GIB = 1024**3
@@ -190,7 +191,7 @@ def _cache_checks() -> Iterator[Check]:
 
 
 def _environment_checks() -> Iterator[Check]:
-    """The environment variables that move the cache, reported only when set."""
+    """The environment variables that move the cache or name a mirror, reported only when set."""
     for name in ENV_VARS:
         value = os.environ.get(name)
         if value:

usdata-0.19.0/src/usdata/mirror.py

@@ -0,0 +1,60 @@
+"""A read-only mirror of pinned bytes, addressed by checksum.
+
+An object lives at ``<mirror>/sha256/<hex>`` and nowhere else, so the lockfile
+entry's checksum is the whole lookup and no schema changes. Restore consults
+the mirror only after the pinned URL fails to reproduce its pin, and only when
+``USDATA_MIRROR_URL`` names one; the SDK never uploads. See ADR 0030.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import httpx
+
+from usdata.cache import sha256_file
+from usdata.protocols import http
+
+ENV_VAR = "USDATA_MIRROR_URL"
+PREFIX = "sha256/"
+
+
+class MirrorMismatch(RuntimeError):
+    """The mirror served bytes whose checksum is not the one their key names."""
+
+
+def mirror_url() -> str | None:
+    """The configured mirror base URL without a trailing slash, or ``None`` when unset."""
+    value = os.environ.get(ENV_VAR, "").strip().rstrip("/")
+    return value or None
+
+
+def object_key(checksum: str) -> str:
+    """The mirror key for a pinned checksum: ``sha256/<hex>``."""
+    algorithm, sep, digest = checksum.partition(":")
+    if not sep or algorithm != "sha256" or len(digest) != 64 or not digest.isalnum():
+        raise ValueError(f"not a sha256 checksum: {checksum!r}")
+    return PREFIX + digest.lower()
+
+
+def object_url(base: str, checksum: str) -> str:
+    """The public URL of one pinned object on a mirror."""
+    return f"{base.rstrip('/')}/{object_key(checksum)}"
+
+
+def download(base: str, checksum: str, dest: Path, client: httpx.Client) -> str:
+    """Fetch the object a checksum names into ``dest`` and prove it is that object.
+
+    Returns:
+        The URL the bytes came from.
+
+    Raises:
+        httpx.HTTPStatusError: The mirror holds no such object, or refused it.
+        MirrorMismatch: The mirror answered with bytes of another checksum.
+    """
+    url = object_url(base, checksum)
+    http.download(url, dest, client)
+    if (found := sha256_file(dest)) != checksum:
+        raise MirrorMismatch(f"{url} holds {found}, not the {checksum} it is named for")
+    return url

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/models.py

@@ -534,6 +534,10 @@ class Provenance(BaseModel):
     object_etag: str | None = Field(
         default=None, description="ETag that object carried, re-sent as ``If-Match`` on a restore"
     )
+    mirror: str | None = Field(
+        default=None,
+        description="Mirror object that served these bytes after the source stopped (ADR 0030)",
+    )
 
     @property
     def is_partial(self) -> bool:

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/providers/noaa/coastwatch.py

@@ -1,6 +1,6 @@
 """CoastWatch blended day/night SST as reproducible ERDDAP CSV subsets.
 
-Requires bbox and inclusive UTC start/end timestamps. Dates mean midnight UTC.
+Requires bbox and inclusive UTC start/end timestamps; a bare end date runs to the end of its day.
 Variables default to analysed_sst; stride optionally subsamples both spatial
 axes by a positive integer. Empty intersections resolve to no assets. Requests
 exceeding one million grid rows must be narrowed or use a larger stride.

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/providers/noaa/coops.py

@@ -2,7 +2,8 @@
 
 Both datasets share one station model: one seven-digit ``station``, an explicit
 ``datum``, optional ``units`` (metric or english), and both timestamps at minute
-precision, requested in UTC. Observations span at most 28 days; predictions
+precision, requested in UTC; a bare end date means 23:59 on that day.
+Observations span at most 28 days; predictions
 span at most a year on any ``interval`` (six-minute by default, another minute
 step, hourly, or high/low), within NOAA's own limits.
 """
@@ -25,6 +26,7 @@ from usdata.protocols import http
 from usdata.providers.base import QueryError
 from usdata.providers.http import HttpProvider
 from usdata.providers.params import choice
+from usdata.query import LAST_INSTANT
 
 DATA_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
 DATUMS = {"CRD", "IGLD", "LWD", "MHHW", "MHW", "MTL", "MSL", "MLW", "MLLW", "NAVD", "STND"}
@@ -156,6 +158,8 @@ class _CoopsStation(HttpProvider):
 
     def _window(self, query: Query, limit: timedelta) -> tuple[datetime, datetime]:
         start, end = self.utc_window(query)
+        if end.time() == LAST_INSTANT:
+            end = end.replace(second=0, microsecond=0)  # a bare end date: its last minute
         if any(value.second or value.microsecond for value in (start, end)):
             raise QueryError("CO-OPS timestamps must have minute precision (zero seconds)")
         if end - start > limit:

{usdata-0.18.0 → usdata-0.19.0}/src/usdata/providers/params.py

@@ -8,6 +8,7 @@ would otherwise let through, notably booleans, floats, and non-ASCII digits.
 Use them as ``Annotated`` metadata on a field of a parameter model::
 
     cycle: Annotated[int, int_range(0, 23)]
+    min_magnitude: Annotated[float, number_range(-10, 10)]
     nearest: Annotated[int, positive_int()]
     forecast_hour: Annotated[list[int], int_list(0, 48)]
     file: Annotated[str, choice("sfc", "prs", "nat")]
@@ -18,6 +19,7 @@ Every message reads as the tail of a sentence about the field; the formatter in
 
 from __future__ import annotations
 
+import math
 from typing import Annotated
 
 from pydantic import BeforeValidator
@@ -62,6 +64,25 @@ def _text(value: object) -> str:
     return value.strip()
 
 
+def _number(value: object, low: float, high: float) -> float:
+    """One finite number inside ``[low, high]``, read from an int, float, or numeric string."""
+    message = f"must be a number from {low:g} to {high:g}"
+    if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+        raise ValueError(message)
+    try:
+        number = float(str(value).strip())
+    except ValueError:
+        raise ValueError(message) from None
+    if not math.isfinite(number) or not low <= number <= high:
+        raise ValueError(message)
+    return number
+
+
+def number_range(low: float, high: float) -> BeforeValidator:
+    """Validate a decimal field such as a magnitude or depth, accepting the CLI's strings."""
+    return BeforeValidator(lambda value: _number(value, low, high))
+
+
 def int_range(low: int, high: int) -> BeforeValidator:
     """Validate an integer field, accepting the digit strings the CLI passes."""
     return BeforeValidator(lambda value: _integer(value, low, high))
@@ -140,5 +161,6 @@ __all__ = [
     "choice",
     "int_list",
     "int_range",
+    "number_range",
     "positive_int",
 ]