usdata 0.18.0__tar.gz → 0.20.0__tar.gz

usdata-0.20.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.20.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-three datasets are available today and twenty-one 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.20.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-three datasets are available today and twenty-one 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.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.18.0"
+version = "0.20.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.20.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.18.0"
+version = "0.20.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.20.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
 
@@ -129,6 +130,8 @@ def _fetch_asset(
             and prov.provider == dataset.provider
             and prov.source_url == asset.href
             and prov.size == path.stat().st_size
+            # A listing that now reports another size describes a rebuilt file.
+            and (asset.size is None or prov.size == asset.size)
             and (asset.checksum is None or prov.checksum == asset.checksum)
             # Trust an untouched cached file; hash whenever anything is unclear.
             and (_sidecar_not_older(path) or sha256_file(path) == prov.checksum)
@@ -137,7 +140,10 @@ def _fetch_asset(
             return FetchedAsset(asset=asset, path=path, provenance=prov, from_cache=True)
     with staged_path(path) as tmp:
         partial = adapter.prepare_fetch(asset, pinned)
-        adapter.fetch(asset, tmp)
+        if partial is None:
+            adapter.fetch(asset, tmp)
+        else:
+            adapter.fetch_partial(asset, tmp, partial)
         prov = provenance.record(dataset, asset, tmp, partial)
         if asset.checksum and prov.checksum != asset.checksum:
             raise ChecksumMismatch(f"{asset.id}: expected {asset.checksum}, got {prov.checksum}")
@@ -169,12 +175,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.20.0}/src/usdata/_grib.py

@@ -81,6 +81,9 @@ def _modules() -> tuple[Any, Any, Any]:
     except (RuntimeError, OSError) as error:
         # eccodes imports, then findlibs fails to locate the shared library.
         raise MissingReaderDependency(f"{LIBRARY_HINT} ({error})") from error
+    # A GRIB2 message may hold several fields (RAP packs wind components that way);
+    # without this ecCodes yields only the first and silently drops the rest.
+    eccodes.codes_grib_multi_support_on()
     return eccodes, xarray, numpy
 
 
@@ -92,9 +95,15 @@ def _handle(eccodes: Any, handle: int) -> Iterator[int]:
         eccodes.codes_release(handle)
 
 
-def _messages_from_bytes(eccodes: Any, data: bytes) -> Iterator[int]:
-    """Handles for each message in an in-memory GRIB byte string, using section 0 lengths."""
+def _messages_from_bytes(eccodes: Any, data: bytes) -> Iterator[tuple[int, int]]:
+    """Message index and handle for each field in an in-memory GRIB byte string.
+
+    Messages are walked by their section 0 lengths; an in-memory message yields
+    its first field only, which is every field of the single-field products
+    that arrive compressed.
+    """
     offset = 0
+    index = 0
     while offset < len(data):
         if data[offset : offset + 4] != b"GRIB":
             raise ValueError(f"not a GRIB message at byte {offset}")
@@ -104,12 +113,18 @@ def _messages_from_bytes(eccodes: Any, data: bytes) -> Iterator[int]:
         if length < 16 or offset + length > len(data):
             raise ValueError(f"truncated GRIB message at byte {offset}")
         with _handle(eccodes, eccodes.codes_new_from_message(data[offset : offset + length])) as h:
-            yield h
+            yield index, h
         offset += length
+        index += 1
 
 
-def _messages(eccodes: Any, path: Path) -> Iterator[int]:
-    """Handles for each message, decompressing gzip in memory without changing cached bytes."""
+def _messages(eccodes: Any, path: Path) -> Iterator[tuple[int, int]]:
+    """Message index and handle for each field, decompressing gzip in memory.
+
+    The index counts GRIB2 messages from zero, so the fields of one message
+    that holds several share it; that is the number a partial fetch's record
+    pairs with, and the ``file_index`` the reader and ``inspect`` report.
+    """
     with path.open("rb") as probe:
         compressed = probe.read(2) == b"\x1f\x8b"
     if compressed:
@@ -117,12 +132,18 @@ def _messages(eccodes: Any, path: Path) -> Iterator[int]:
         yield from _messages_from_bytes(eccodes, data)
         return
     # ecCodes reads through the descriptor, so it gets a file object it alone positions.
+    index = -1
+    last_offset: int | None = None
     with path.open("rb") as raw:
         while (handle := eccodes.codes_grib_new_from_file(raw)) is not None:
             with _handle(eccodes, handle) as h:
                 if eccodes.codes_get(h, "edition") != 2:
                     raise ValueError("only GRIB edition 2 is supported")
-                yield h
+                offset = _get(eccodes, h, "offset", int)
+                if offset is None or offset != last_offset:
+                    index += 1
+                    last_offset = offset
+                yield index, h
 
 
 def _get(eccodes: Any, h: int, key: str, ktype: type | None = None) -> Any:
@@ -203,7 +224,7 @@ def inventory(path: Path) -> list[GribMessage]:
     """Every message in a local GRIB2 file, in file order, without decoding its values."""
     eccodes = _modules()[0]
     messages = []
-    for index, h in enumerate(_messages(eccodes, path)):
+    for index, h in _messages(eccodes, path):
         keys = {key: _get(eccodes, h, key, str) for key in INVENTORY_KEYS}
         messages.append(
             GribMessage(
@@ -373,7 +394,7 @@ def open_grib2(
     needs_select = select is None and not fetched.provenance.is_partial
     object_messages = fetched.provenance.object_messages
     selectors = fetched.provenance.selectors if object_messages else []
-    for h in _messages(eccodes, fetched.path):
+    for index, h in _messages(eccodes, fetched.path):
         count += 1
         if count > 1 and needs_select:
             continue
@@ -415,15 +436,15 @@ def open_grib2(
             if stamp:
                 attrs[label] = stamp
         message: dict[str, Any] = {
-            "file_index": count - 1,
-            "object_index": object_messages[count - 1] if object_messages else None,
+            "file_index": index,
+            "object_index": object_messages[index] if object_messages else None,
             "shortName": _get(eccodes, h, "shortName", str),
             "typeOfLevel": attrs.get("typeOfLevel"),
             "level": attrs.get("level"),
             "step": attrs.get("step"),
         }
         if selectors:
-            message["selector"] = selectors[count - 1]
+            message["selector"] = selectors[index]
         short = message["shortName"]
         if short in (None, "", "unknown", "~"):
             short = _product_name(fetched.asset.id) or (

{usdata-0.18.0 → usdata-0.20.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.20.0}/src/usdata/cli/inspect.py

@@ -94,7 +94,8 @@ def _echo_detail(summary: Summary, width: int) -> None:
         else:
             typer.echo("  columns:")
             for name in frame.columns:
-                typer.echo(f"    {name}")
+                unit = frame.units.get(name)
+                typer.echo(f"    {name} ({unit})" if unit else f"    {name}")
     if (scene := summary.netcdf) is not None:
         _echo_table(
             "variables",