usdata 0.28.0__tar.gz → 0.29.0__tar.gz

{usdata-0.28.0 → usdata-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.28.0
+Version: 0.29.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

{usdata-0.28.0 → usdata-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.28.0"
+version = "0.29.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"

{usdata-0.28.0 → usdata-0.29.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.28.0"
+version = "0.29.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"

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/_fetch.py

@@ -132,6 +132,29 @@ def _sidecar_not_older(path: Path) -> bool:
         return False
 
 
+def _cached(dataset: Dataset, asset: Asset, path: Path) -> Provenance | None:
+    """The record of a file at ``path`` that still describes ``asset``, or None if there is none."""
+    if not path.is_file():
+        return None
+    try:
+        prov = provenance.read(path)
+    except (ValueError, OSError):
+        return None
+    if (
+        prov.dataset_id == dataset.id
+        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)
+    ):
+        return prov
+    return None
+
+
 def _fetch_asset(
     dataset: Dataset,
     asset: Asset,
@@ -149,35 +172,23 @@ def _fetch_asset(
     from the record rather than by resolving its query again.
 
     ``staging`` is a root a download is written under instead of the cache. The
-    cache at ``root`` is still checked, and a hit is returned from there; a
-    miss comes back with its ``path`` under ``staging``, for the caller to move
-    home once it can pin it (ADR 0031).
+    cache at ``root`` is still checked, and a hit is returned from there; so is
+    ``staging``, where an earlier source in the same run may have fetched the
+    same asset. A miss comes back with its ``path`` under ``staging``, for the
+    caller to move home once it can pin it (ADR 0031).
     """
     if asset.dataset_id != dataset.id:
         raise ValueError(f"asset dataset {asset.dataset_id!r} does not match {dataset.id!r}")
     _progress.emit(_progress.AssetProgress(asset.id, "start", asset.size))
     path = asset_path(asset, root)
-    if not force and path.is_file():
-        try:
-            prov = provenance.read(path)
-        except (ValueError, OSError):
-            prov = None
-        if (
-            prov is not None
-            and prov.dataset_id == dataset.id
-            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)
-        ):
+    staged = None if staging is None else asset_path(asset, staging)
+    # A staged run looks in its staging too, so an asset two sources share is fetched once.
+    for candidate in () if force else (path, staged):
+        if candidate is not None and (prov := _cached(dataset, asset, candidate)) is not None:
             _progress.emit(_progress.AssetProgress(asset.id, "cached", prov.size))
-            return FetchedAsset(asset=asset, path=path, provenance=prov, from_cache=True)
-    if staging is not None:
-        path = asset_path(asset, staging)
+            return FetchedAsset(asset=asset, path=candidate, provenance=prov, from_cache=True)
+    if staged is not None:
+        path = staged
     with staged_path(path) as tmp:
         partial = adapter.prepare_fetch(asset, pinned)
         if partial is None:

usdata-0.29.0/src/usdata/_files.py

@@ -0,0 +1,64 @@
+"""Atomic replacement helpers for downloads and JSON records."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+TEMP_SUFFIX = ".part"
+
+
+def is_temporary(path: Path) -> bool:
+    """Whether ``path`` is a temporary file ``staged_path`` made, finished or abandoned."""
+    return path.name.startswith(".") and path.name.endswith(TEMP_SUFFIX)
+
+
+@contextmanager
+def staged_path(dest: Path) -> Iterator[Path]:
+    """Replace dest only after successful work in a unique sibling temporary file.
+
+    The file is flushed to disk before it replaces ``dest``, and the rename
+    after, so once this returns the new ``dest`` survives a crash; without that
+    a crash could keep the rename but lose the bytes, or reorder two renames.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile(
+        prefix=f".{dest.name}.", suffix=TEMP_SUFFIX, dir=dest.parent, delete=False
+    ) as f:
+        tmp = Path(f.name)
+    try:
+        yield tmp
+        _fsync(tmp)
+        tmp.replace(dest)
+        _fsync_directory(dest.parent)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def atomic_write_text(dest: Path, text: str) -> None:
+    """Write UTF-8 text without exposing an incomplete record to readers."""
+    with staged_path(dest) as tmp:
+        tmp.write_text(text, encoding="utf-8")
+
+
+def _fsync(path: Path) -> None:
+    # Windows flushes only through a descriptor opened for writing.
+    fd = os.open(path, os.O_RDWR)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _fsync_directory(path: Path) -> None:
+    """Flush a directory's entries, where the platform allows opening a directory."""
+    if os.name == "nt":
+        return
+    fd = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/_grib.py

@@ -42,12 +42,19 @@ LIBRARY_HINT = (
     "on macOS and on Windows with Python 3.14 install it separately, for example "
     "`conda install -c conda-forge eccodes` or `brew install eccodes`"
 )
-MRMS_NAME = re.compile(r"^MRMS_(?P<product>.+?)_\d{2}\.\d{2}_\d{8}-\d{6}\.grib2(?:\.gz)?$")
+MRMS_NAME = re.compile(r"^MRMS_(?P<product>.+?)(?:_\d{2}\.\d{2})?_\d{8}-\d{6}\.grib2(?:\.gz)?$")
+"""An MRMS filename, whose product segment names a variable ecCodes cannot.
+
+Most products end in a level such as ``_00.50``, which the name drops; one,
+``LightningProbabilityNext30minGrid_scale_1``, has none and is named whole.
+"""
 INVENTORY_KEYS = ("shortName", "name", "typeOfLevel", "level", "step", "units")
-SYMBOL_POWER = re.compile(r"(?<=[A-Za-z])\*\*")
-"""A power written after a unit symbol, as ecCodes writes ``kg**-1``."""
-NUMERIC_POWER = re.compile(r"(?<![A-Za-z])\*\*")
-"""A power written after anything else, such as the ``10**-3`` of a scale factor."""
+PARAMETER_KEYS = ("discipline", "parameterCategory", "parameterNumber")
+"""The keys that identify a parameter ecCodes has no short name for."""
+UNNAMED = frozenset({"", "unknown", "~"})
+"""Short names ecCodes gives a parameter its tables do not name."""
+SYMBOL_POWER = re.compile(r"(?<=[A-Za-z])\*\*(?=-?\d+(?![\d.]))")
+"""An integer power of a unit symbol, as ecCodes writes ``kg**-1``."""
 
 VARIABLE_KEYS = (
     "name",
@@ -218,16 +225,23 @@ def _shape(eccodes: Any, h: int) -> tuple[int, int] | None:
     return None if rows is None or cols is None else (rows, cols)
 
 
-def inventory(path: Path) -> list[GribMessage]:
-    """Every message in a local GRIB2 file, in file order, without decoding its values."""
+def inventory(path: Path, source: str | None = None) -> list[GribMessage]:
+    """Every message in a local GRIB2 file, in file order, without decoding its values.
+
+    ``source`` is the asset id the file was fetched as, which names a message
+    ecCodes cannot; it defaults to the file's name, which is the asset id for a
+    cached file.
+    """
     eccodes = _modules()[0]
     messages = []
     for index, h in _messages(eccodes, path):
         keys = {key: _get(eccodes, h, key, str) for key in INVENTORY_KEYS}
+        parameter = [_get(eccodes, h, key) for key in PARAMETER_KEYS]
         messages.append(
             GribMessage(
                 file_index=index,
                 short_name=keys["shortName"],
+                base_name=base_name(keys["shortName"], parameter, source or path.name),
                 name=keys["name"],
                 type_of_level=keys["typeOfLevel"],
                 level=keys["level"],
@@ -244,11 +258,13 @@ def udunits(units: str) -> str:
 
     ecCodes writes powers as ``**``: ``J kg**-1``, ``m**2 s**-2``. UDUNITS and
     CF write them as a trailing signed integer, ``J kg-1`` and ``m2 s-2``,
-    which is what xarray-based tools expect. Only the notation changes. A power
-    of a number, such as ``10**-3``, has no such spelling, so a string holding
-    one is returned as it is rather than half rewritten.
+    which is what xarray-based tools expect. Only the notation changes, and only
+    for an integer power of a unit symbol. Any other power has no such
+    spelling: of a number, as in ``10**-3``, of a group, as in ``(m s**-1)**2``,
+    or not an integer, as in ``m**(2/3)``. A string holding one is returned as
+    it is rather than half rewritten.
     """
-    if NUMERIC_POWER.search(units):
+    if len(SYMBOL_POWER.findall(units)) != units.count("**"):
         return units
     return SYMBOL_POWER.sub("", units)
 
@@ -266,6 +282,28 @@ def _product_name(asset_id: str) -> str | None:
     return match["product"] if match else None
 
 
+def base_name(short_name: str | None, parameter: Sequence[Any], source: str) -> str:
+    """The name one message's variable starts from, before ``variable_names`` qualifies it.
+
+    That is the ecCodes ``shortName`` where its tables name the parameter.
+    Where they do not, it is the MRMS product the asset id names, or else
+    ``parameter_<discipline>_<category>_<number>``. The reader and
+    ``Grib2Summary.variable_for`` both name messages through here.
+
+    Args:
+        short_name: The message's ecCodes ``shortName``, or None when it has none.
+        parameter: Its ``discipline``, ``parameterCategory``, and ``parameterNumber``.
+        source: The asset id the file was fetched as.
+
+    Returns:
+        The unqualified variable name.
+    """
+    if short_name is not None and short_name not in UNNAMED:
+        return short_name
+    discipline, category, number = parameter
+    return _product_name(source) or f"parameter_{discipline}_{category}_{number}"
+
+
 def _time(date: Any, time: Any) -> str | None:
     if date is None or time is None:
         return None
@@ -473,12 +511,9 @@ def open_grib2(
         }
         if selectors:
             message["selector"] = selectors[index]
-        short = message["shortName"]
-        if short in (None, "", "unknown", "~"):
-            short = _product_name(fetched.asset.id) or (
-                f"parameter_{attrs.get('discipline')}_{attrs.get('parameterCategory')}"
-                f"_{attrs.get('parameterNumber')}"
-            )
+        short = base_name(
+            message["shortName"], [attrs.get(key) for key in PARAMETER_KEYS], fetched.asset.id
+        )
         selected.append(_Field(short=short, data=data, attrs=attrs, message=message))
     if count > 1 and needs_select:
         raise ValueError(

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/cache_ops.py

@@ -15,9 +15,10 @@ from pathlib import Path
 from pydantic import BaseModel, Field, ValidationError
 
 from usdata import provenance
+from usdata._files import is_temporary
 from usdata.cache import asset_path, cache_dir
 from usdata.manifest import Lockfile, lockfile_path
-from usdata.models import Provenance
+from usdata.models import AwareUTC, Provenance, as_utc
 from usdata.provenance import SIDECAR_SUFFIX
 
 MANIFEST_GLOBS = ("*.yaml", "*.yml")
@@ -37,8 +38,8 @@ class CacheEntry(BaseModel):
     asset_id: str
     path: Path
     size: int = Field(ge=0, description="Bytes of the data file, excluding its sidecar")
-    modified_at: datetime = Field(description="Filesystem modification time, in UTC")
-    retrieved_at: datetime | None = Field(
+    modified_at: AwareUTC = Field(description="Filesystem modification time, in UTC")
+    retrieved_at: AwareUTC | None = Field(
         default=None,
         description="When the sidecar says the file was fetched; unset without a readable sidecar",
     )
@@ -90,6 +91,7 @@ def entries(root: Path | None = None) -> list[CacheEntry]:
         One entry per file at ``<root>/<provider>/<name>/<asset id>``. A file
         with no readable sidecar is still listed, as unrecorded, with its
         dataset id taken from the directories it sits in. Sidecars themselves,
+        temporary files a download or a killed run left, the staging directory,
         and files at any other depth, are skipped.
     """
     base = _root(root)
@@ -98,9 +100,11 @@ def entries(root: Path | None = None) -> list[CacheEntry]:
     found = [
         _entry(path)
         for provider in _subdirectories(base)
+        # No provider id starts with a dot; the staging directory does.
+        if not provider.name.startswith(".")
         for name in _subdirectories(provider)
         for path in sorted(name.iterdir())
-        if path.is_file() and not path.name.endswith(SIDECAR_SUFFIX)
+        if path.is_file() and not path.name.endswith(SIDECAR_SUFFIX) and not is_temporary(path)
     ]
     return sorted(found, key=lambda entry: (entry.dataset_id, entry.asset_id))
 
@@ -131,11 +135,12 @@ def candidates(
         older_than: Keep entries younger than this age. Unfiltered when None.
         dataset: Keep only entries of this dataset id. Unfiltered when None.
         now: The moment ages are measured from; the current UTC time when omitted.
+            A naive value means UTC.
 
     Returns:
         The matching entries, in the order :func:`entries` returns them.
     """
-    moment = now or datetime.now(UTC)
+    moment = datetime.now(UTC) if now is None else as_utc(now)
     return [
         entry
         for entry in entries(root)

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/cli/app.py

@@ -404,6 +404,8 @@ def fetch(
             typer.echo(f"{len(assets)} asset(s) matched, {sizes}", err=True)
             with progress(disabled=no_progress):
                 batch([asset.size for asset in assets])
+            if not assets:
+                raise typer.Exit(code=1)
             return
         with progress(disabled=no_progress):
             fetched = fetch_query(ds, query, root=cache_dir, force=force)
@@ -507,7 +509,8 @@ def pull(
             typer.echo(f"{d.asset_id}\t{d.problem}\t{d.path}")
         typer.secho(
             f"{len(e.drift)} asset(s) changed upstream; lockfile unchanged. "
-            "Pass --update <asset or dataset id> to accept the new bytes.",
+            "Pass --update <asset or dataset id> to accept the new bytes, "
+            "or --force to re-resolve.",
             err=True,
             fg="red",
         )

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/data/places.csv

@@ -1,6 +1,6 @@
 kind,geoid,name,qualified_name,state,state_name,west,south,east,north
 state,01,Alabama,Alabama,AL,Alabama,-88.473227,30.223334,-84.889080,35.008028
-state,02,Alaska,Alaska,AK,Alaska,-179.146711,51.215567,179.778470,71.387815
+state,02,Alaska,Alaska,AK,Alaska,-179.146711,51.215567,-129.974167,71.387815
 state,04,Arizona,Arizona,AZ,Arizona,-114.816510,31.332177,-109.045223,37.004260
 state,05,Arkansas,Arkansas,AR,Arkansas,-94.617919,33.004291,-89.641003,36.499600
 state,06,California,California,CA,California,-124.409591,32.534435,-114.131211,42.009485
@@ -123,7 +123,7 @@ county,01129,Washington,Washington County,AL,Alabama,-88.464427,31.114298,-87.88
 county,01131,Wilcox,Wilcox County,AL,Alabama,-87.667945,31.827123,-86.856576,32.268921
 county,01133,Winston,Winston County,AL,Alabama,-87.636573,33.985004,-87.109911,34.306997
 county,02013,Aleutians East,Aleutians East Borough,AK,Alaska,-166.199167,53.953959,-158.893471,56.880265
-county,02016,Aleutians West,Aleutians West Census Area,AK,Alaska,-179.146711,51.215567,179.778470,57.249626
+county,02016,Aleutians West,Aleutians West Census Area,AK,Alaska,-179.146711,51.215567,-166.038614,57.249626
 county,02020,Anchorage,Anchorage Municipality,AK,Alaska,-150.285859,60.732987,-148.462403,61.484029
 county,02050,Bethel,Bethel Census Area,AK,Alaska,-173.121318,58.550337,-153.001640,62.292644
 county,02060,Bristol Bay,Bristol Bay Borough,AK,Alaska,-157.260883,58.615921,-156.316015,58.885114

usdata-0.29.0/src/usdata/data/places.sources.json

@@ -0,0 +1,44 @@
+{
+  "vintage": "2025",
+  "scale": "1:500,000",
+  "coordinate_system": "WGS84 longitude/latitude",
+  "generator": "scripts/build_places.py",
+  "sources": [
+    {
+      "url": "https://www2.census.gov/geo/tiger/GENZ2025/kml/cb_2025_us_state_500k.zip",
+      "sha256": "4295a503ff47e6787adfb520ad6706557e41c2ce57ced5a134087f8e35143a02",
+      "records": 56
+    },
+    {
+      "url": "https://www2.census.gov/geo/tiger/GENZ2025/kml/cb_2025_us_county_500k.zip",
+      "sha256": "fd8e3d57d59d43ab16692ba62a3c139705a899acd6ad4db3d66a05e3a21a54c6",
+      "records": 3235
+    }
+  ],
+  "csv_sha256": "eed6d7c53dcccb486f4e6f46fd393195cfb14e198b241f5ed9eed356f41f71f4",
+  "antimeridian": {
+    "rule": "A place whose longitudes span more than 180 degrees keeps only its western-hemisphere polygons; no box crosses the antimeridian.",
+    "clipped": [
+      {
+        "geoid": "02",
+        "dropped_polygons": 14,
+        "dropped_box": [
+          172.461667,
+          51.357688,
+          179.77847,
+          53.01075
+        ]
+      },
+      {
+        "geoid": "02016",
+        "dropped_polygons": 14,
+        "dropped_box": [
+          172.461667,
+          51.357688,
+          179.77847,
+          53.01075
+        ]
+      }
+    ]
+  }
+}

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/data/registry.yaml

@@ -79,12 +79,14 @@ datasets:
       unidata-nexrad-level2 S3 bucket (NOAA Open Data Dissemination). One object per radar site
       per volume scan. No server-side subsetting; whole files are fetched. Select radars by site
       id, bbox, or nearest to a point. Moments vary by sweep and volume coverage pattern; the
-      catalog lists the ones the radar example's lowest sweep carries.
+      catalog lists the ones the radar example's lowest sweep carries. The extent spans the
+      radars from the Aleutians to the Azores; Guam, Korea, and Okinawa lie beyond the
+      antimeridian, outside it, and are reached by site id.
     keywords: [radar, weather, storms, tornado, precipitation, reflectivity, nexrad, wsr-88d]
     protocol: s3
     homepage: https://registry.opendata.aws/noaa-nexrad/
     license: US Government Work (public domain)
-    spatial_extent: { west: -180.0, south: 15.0, east: -60.0, north: 72.0 }
+    spatial_extent: { west: -180.0, south: 15.0, east: -27.0, north: 72.0 }
     temporal_extent: { start: "1991-06-01T00:00:00Z" }
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
     summary: NEXRAD radar scans
@@ -905,12 +907,14 @@ datasets:
       S3 bucket, with flat keys SITE_PRODUCT_YYYY_MM_DD_HH_MM_SS where the site
       id drops the first letter of its ICAO id. One object per product per
       volume scan since 2020-03-30; earlier products are archived at NCEI.
-      Files are fetched whole and have no reader.
+      Files are fetched whole and have no reader. The extent spans the radars
+      from the Aleutians to the Azores; Guam, Korea, and Okinawa lie beyond the
+      antimeridian, outside it, and are reached by site id.
     keywords: [radar, nexrad, level iii, reflectivity, velocity, mesocyclone, storm tracks, products, tornado]
     protocol: s3
     homepage: https://registry.opendata.aws/noaa-nexrad/
     license: US Government Work (public domain)
-    spatial_extent: { west: -180.0, south: 15.0, east: -60.0, north: 72.0 }
+    spatial_extent: { west: -180.0, south: 15.0, east: -27.0, north: 72.0 }
     temporal_extent: { start: "2020-03-30T00:00:00Z" }
     capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
     summary: NEXRAD derived radar products

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/inspect.py

@@ -13,7 +13,6 @@ import csv
 import gzip
 import io
 import os
-from datetime import datetime
 from enum import StrEnum
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -21,7 +20,7 @@ from typing import TYPE_CHECKING
 from pydantic import BaseModel, Field
 
 from usdata import provenance, readers
-from usdata.models import Protocol, Provenance
+from usdata.models import AwareUTC, Protocol, Provenance
 
 if TYPE_CHECKING:
     from usdata._fetch import FetchedAsset
@@ -99,6 +98,13 @@ class GribMessage(BaseModel):
         default=None, description="Index selector this message was fetched for, for a partial fetch"
     )
     short_name: str | None = Field(default=None, description="ecCodes shortName")
+    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: str | None = Field(default=None, description="ecCodes name")
     type_of_level: str | None = Field(default=None, description="ecCodes typeOfLevel")
     level: str | None = Field(default=None, description="ecCodes level")
@@ -130,18 +136,35 @@ class Grib2Summary(BaseModel):
         Raises:
             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 cannot say
+                which field it named; the message lists their variables.
         """
         from usdata._grib import variable_names
 
         names = variable_names(
             [
-                (message.short_name or "", message.type_of_level, message.level)
+                (
+                    message.base_name or message.short_name or "",
+                    message.type_of_level,
+                    message.level,
+                )
                 for message in self.messages
             ]
         )
-        for message, name in zip(self.messages, names, strict=True):
-            if message.selector == selector:
-                return name
+        matched = [
+            name
+            for message, name in zip(self.messages, names, strict=True)
+            if message.selector == selector
+        ]
+        if len(matched) > 1:
+            # The record keeps one selector per byte range, and one range can hold several fields.
+            raise ValueError(
+                f"selector {selector!r} fetched one message holding {len(matched)} fields "
+                f"({', '.join(matched)}); pick the variable by name"
+            )
+        if matched:
+            return matched[0]
         recorded = ", ".join(
             repr(message.selector) for message in self.messages if message.selector is not None
         )
@@ -164,7 +187,7 @@ class Summary(BaseModel):
     path: Path
     size: int = Field(ge=0, description="Bytes on disk now, not the size provenance recorded")
     format: AssetFormat
-    retrieved_at: datetime
+    retrieved_at: AwareUTC
     checksum: str
     source_url: str
     csv: CsvSummary | None = None
@@ -243,7 +266,7 @@ def _summarize(
     note: str | None = None
     if fmt is not AssetFormat.BYTES:
         try:
-            detail = _detail(path, fmt, record, protocol)
+            detail = _detail(path, asset_id, fmt, record, protocol)
         except readers.MissingReaderDependency as error:
             note = str(error)
         # A cached file that no longer decodes is reported, not raised: a summary
@@ -288,16 +311,22 @@ def _detect(name: str, media_type: str | None) -> AssetFormat:
 
 
 def _detail(
-    path: Path, fmt: AssetFormat, record: Provenance, protocol: Protocol | None
+    path: Path, asset_id: str, fmt: AssetFormat, record: Provenance, protocol: Protocol | None
 ) -> CsvSummary | NetcdfSummary | Grib2Summary:
-    """The detail for one recognized format, reading only what that format needs."""
+    """The detail for one recognized format, reading only what that format needs.
+
+    A GRIB2 inventory is given the asset id, which names a message ecCodes
+    cannot, as the reader names it.
+    """
     if fmt is AssetFormat.CSV:
         return _csv_summary(path, units_row=readers.has_units_row(record.dataset_id, protocol))
     if fmt is AssetFormat.NETCDF:
         from usdata._netcdf import variables
 
         return NetcdfSummary(variables=variables(path))
-    return Grib2Summary(messages=_paired(readers.inventory(path), record))
+    from usdata._grib import inventory
+
+    return Grib2Summary(messages=_paired(inventory(path, asset_id), record))
 
 
 def _paired(messages: list[GribMessage], record: Provenance) -> list[GribMessage]:

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/manifest.py

@@ -12,7 +12,7 @@ import yaml
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from usdata._files import atomic_write_text
-from usdata.models import Asset, BBox, Provenance, Query
+from usdata.models import Asset, AwareUTC, BBox, Provenance, Query
 from usdata.query import build_query
 from usdata.registry import Registry, default_registry
 
@@ -123,7 +123,7 @@ class Lockfile(BaseModel):
 
     manifest: str
     manifest_checksum: str = Field(description="sha256 of the manifest file when it was resolved")
-    generated_at: datetime
+    generated_at: AwareUTC
     usdata_version: str
     assets: list[LockedAsset] = Field(default_factory=list)
 

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/models.py

@@ -9,12 +9,21 @@ from __future__ import annotations
 
 import math
 import re
-from datetime import datetime, timedelta
+from datetime import UTC, datetime, timedelta
 from enum import StrEnum
 from pathlib import PurePosixPath
-from typing import Any, Literal
+from typing import Annotated, Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, model_validator
+
+
+def as_utc(value: datetime) -> datetime:
+    """The shared time policy: a naive datetime means UTC, an aware one converts to UTC."""
+    return value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
+
+
+AwareUTC = Annotated[datetime, AfterValidator(as_utc)]
+"""A datetime field stored as aware UTC whatever it was given; see :func:`as_utc`."""
 
 
 class Protocol(StrEnum):
@@ -128,8 +137,8 @@ class TimeRange(BaseModel):
 
     model_config = ConfigDict(frozen=True)
 
-    start: datetime | None = None
-    end: datetime | None = None
+    start: AwareUTC | None = None
+    end: AwareUTC | None = None
 
     @model_validator(mode="after")
     def _ordered(self) -> TimeRange:
@@ -596,7 +605,7 @@ class TemporalSelection(BaseModel):
     candidates. Counts refer to the supplied candidates, not a remote catalog.
     """
 
-    target: datetime
+    target: AwareUTC
     tolerance: timedelta
     direction: Literal["nearest", "at_or_before"]
     asset: Asset | None
@@ -611,7 +620,7 @@ class Provenance(BaseModel):
     dataset_id: str
     provider: str
     source_url: str
-    retrieved_at: datetime
+    retrieved_at: AwareUTC
     checksum: str
     size: int = Field(ge=0)
     license: str | None = None

{usdata-0.28.0 → usdata-0.29.0}/src/usdata/protocols/erddap.py

@@ -70,6 +70,9 @@ def axis(base: str, dataset: str, name: str, client: httpx.Client) -> tuple[str,
     response = http.get(_endpoint(base, "griddap", dataset) + ".csv?" + _identifier(name), client)
     try:
         rows = list(csv.reader(io.StringIO(response.text)))
+        # A unitless axis has an empty units row, which reads as no fields at all.
+        if len(rows) >= 2 and rows[1] == []:
+            rows[1] = [""]
         if len(rows) < 3 or rows[0] != [name] or any(len(row) != 1 for row in rows):
             raise ValueError("invalid axis CSV")
         return rows[1][0], [row[0] for row in rows[2:]]