usdata 0.17.0__tar.gz → 0.18.0__tar.gz

{usdata-0.17.0 → usdata-0.18.0}/PKG-INFO

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.17.0"
+version = "0.18.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.17.0 → usdata-0.18.0}/src/usdata/__init__.py

@@ -11,7 +11,7 @@ except PackageNotFoundError:  # running from a source tree without an install
     __version__ = "0.0.0"
 
 from usdata._fetch import ChecksumMismatch, FetchedAsset, fetch, fetch_asset
-from usdata.cite import cite_dataset, cite_lockfile
+from usdata.cite import Citation, cite_dataset, cite_lockfile
 from usdata.inspect import inspect_asset, inspect_path
 from usdata.models import Asset, BBox, Dataset, Provenance, Query, TemporalSelection, TimeRange
 from usdata.pull import pull, verify
@@ -23,6 +23,7 @@ __all__ = [
     "Asset",
     "BBox",
     "ChecksumMismatch",
+    "Citation",
     "Dataset",
     "DatasetNotFound",
     "FetchedAsset",

usdata-0.18.0/src/usdata/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point: ``python -m usdata`` runs the same CLI the script does."""
+
+from __future__ import annotations
+
+from usdata.cli import app
+
+if __name__ == "__main__":
+    app()

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from collections.abc import Mapping
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -105,7 +106,14 @@ def _fetch_asset(
     *,
     root: Path | None = None,
     force: bool = False,
+    pinned: Provenance | None = None,
 ) -> FetchedAsset:
+    """Fetch one asset through the cache, passing any pinned record to the adapter.
+
+    ``pinned`` is the provenance a lockfile holds for this asset. The adapter sees
+    it through ``prepare_fetch``, so an asset that pins byte ranges is reproduced
+    from the record rather than by resolving its query again.
+    """
     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))
@@ -128,8 +136,9 @@ def _fetch_asset(
             _progress.emit(_progress.AssetProgress(asset.id, "cached", prov.size))
             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)
-        prov = provenance.record(dataset, asset, tmp)
+        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}")
     # A crash between replacements leaves a detectable mismatch, never a trusted partial file.
@@ -139,11 +148,17 @@ def _fetch_asset(
 
 
 def fetch_asset(
-    dataset: Dataset, asset: Asset, *, root: Path | None = None, force: bool = False
+    dataset: Dataset,
+    asset: Asset,
+    *,
+    root: str | os.PathLike[str] | None = None,
+    force: bool = False,
 ) -> FetchedAsset:
     """Fetch one asset, reusing the cache only when its provenance still describes it."""
     with load_adapter(dataset) as adapter:
-        return _fetch_asset(dataset, asset, adapter, root=root, force=force)
+        return _fetch_asset(
+            dataset, asset, adapter, root=None if root is None else Path(root), force=force
+        )
 
 
 def _fetch_with(
@@ -161,8 +176,14 @@ def _fetch_with(
 
 
 def fetch(
-    dataset: Dataset, query: Query, *, root: Path | None = None, force: bool = False
+    dataset: Dataset,
+    query: Query,
+    *,
+    root: str | os.PathLike[str] | None = None,
+    force: bool = False,
 ) -> list[FetchedAsset]:
     """Resolve and fetch a query, sharing one adapter and closing its owned resources."""
     with load_adapter(dataset) as adapter:
-        return _fetch_with(adapter, dataset, query, root=root, force=force)
+        return _fetch_with(
+            adapter, dataset, query, root=None if root is None else Path(root), force=force
+        )

{usdata-0.17.0 → usdata-0.18.0}/src/usdata/_grib.py

@@ -3,7 +3,9 @@
 Messages are decoded one at a time with the ecCodes Python bindings, never
 cfgrib. The reader builds the xarray Dataset itself: one data variable per
 selected message on one shared grid, coordinates computed from the grid
-definition, and provenance under ``attrs["usdata"]``. Values arrive from
+definition, and provenance under ``attrs["usdata"]``. Variable names follow
+from the set of selected messages alone, never from which short names happen to
+repeat, so the same select always yields the same names. Values arrive from
 ecCodes as float64, are masked to NaN where the message's bitmap marks them
 missing, and are stored as float32; the float64 array is released before the
 Dataset is returned. Rows are ordered north to south and columns west to east
@@ -15,13 +17,13 @@ from __future__ import annotations
 import gzip
 import re
 import warnings
-from collections.abc import Iterator, Mapping
+from collections.abc import Iterator, Mapping, Sequence
 from contextlib import contextmanager
 from datetime import UTC, datetime
 from importlib import import_module
 from inspect import currentframe
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from usdata.inspect import GribMessage
 from usdata.readers import MissingReaderDependency, fill_registry_attrs
@@ -205,7 +207,7 @@ def inventory(path: Path) -> list[GribMessage]:
         keys = {key: _get(eccodes, h, key, str) for key in INVENTORY_KEYS}
         messages.append(
             GribMessage(
-                index=index,
+                file_index=index,
                 short_name=keys["shortName"],
                 name=keys["name"],
                 type_of_level=keys["typeOfLevel"],
@@ -298,11 +300,64 @@ class _Grid:
         return numpy.ascontiguousarray(grid)
 
 
+class _Field(NamedTuple):
+    """One decoded message: its short name, values, variable attributes, and identity."""
+
+    short: str
+    data: Any
+    attrs: dict[str, Any]
+    message: dict[str, Any]
+
+
+def variable_names(fields: Sequence[tuple[str, Any, Any]]) -> list[str]:
+    """The names one set of selected messages takes, under the one GRIB2 naming rule.
+
+    Every name is the bare short name while the messages share one type of level
+    and level, and every name is ``short_typeOfLevel_level`` as soon as they span
+    more than one, so the names follow from the selection rather than from which
+    short names happened to repeat. A name that would still repeat gains its
+    position.
+
+    Args:
+        fields: One ``(short name, type of level, level)`` triple per message, in
+            the order the messages appear.
+
+    Returns:
+        One variable name per field, in the same order.
+    """
+    spans = len({(level_type, level) for _, level_type, level in fields}) > 1
+    names: list[str] = []
+    for short, level_type, level in fields:
+        label = short
+        if spans:
+            kind = "level" if level_type is None else level_type
+            label = f"{short}_{kind}_{'' if level is None else level}"
+        if label in names:
+            label = f"{label}_{len(names)}"
+        names.append(label)
+    return names
+
+
 def open_grib2(
     fetched: FetchedAsset, select: Mapping[str, Any] | None = None, *, strict: bool = False
 ) -> Any:
     """Decode selected GRIB2 messages into one loaded xarray Dataset.
 
+    A file of several messages needs ``select``, unless its provenance says the
+    fetch already selected them: a partial fetch concatenated the messages that
+    were asked for, so all of them are wanted and ``select`` stays optional.
+
+    Variables take their ``shortName`` when every selected message shares one
+    type of level and level, and ``shortName_typeOfLevel_level`` for all of
+    them as soon as the selection spans more than one, so the names follow from
+    the select rather than from which short names happened to repeat.
+    ``attrs["usdata"]["messages"]`` maps each variable name to the message it
+    came from: ``file_index`` numbers it in this file from zero, and
+    ``object_index`` numbers it in the source object as that object's index
+    sidecar does, one-based, for a partial fetch and ``None`` for a whole file.
+    A partial fetch's entries also carry ``selector``, the index selector the
+    message was fetched for.
+
     A select value that matches none of the selected messages warns, or raises
     ``ValueError`` when ``strict``; a select that matches nothing always raises.
     """
@@ -312,13 +367,15 @@ def open_grib2(
     options = {key: _options(key, wanted) for key, wanted in (select or {}).items()}
     matched: dict[str, set[int]] = {key: set() for key in options}
     present: dict[str, list[str]] = {key: [] for key in options}
-    fields: dict[str, tuple[Any, dict[str, Any]]] = {}
+    selected: list[_Field] = []
     grid: _Grid | None = None
     count = 0
-    names: list[str] = []
+    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):
         count += 1
-        if count > 1 and select is None:
+        if count > 1 and needs_select:
             continue
         hits = {key: _matched(eccodes, h, key, wanted) for key, wanted in options.items()}
         missed = [key for key, indexes in hits.items() if not indexes]
@@ -357,21 +414,30 @@ def open_grib2(
             stamp = _time(attrs.get(date_key), attrs.get(time_key))
             if stamp:
                 attrs[label] = stamp
-        short = _get(eccodes, h, "shortName", str)
+        message: dict[str, Any] = {
+            "file_index": count - 1,
+            "object_index": object_messages[count - 1] 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]
+        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')}"
             )
-        names.append(short)
-        fields[f"{short}#{len(names)}"] = (data, attrs)
-    if count > 1 and select is None:
+        selected.append(_Field(short=short, data=data, attrs=attrs, message=message))
+    if count > 1 and needs_select:
         raise ValueError(
             f"{count} messages; pass select={{...}} with ecCodes keys to choose, "
             f"for example select={{'shortName': ..., 'typeOfLevel': ...}}. "
             f"Available (shortName, typeOfLevel, level): {_available(fetched.path)}"
         )
-    if grid is None or not fields:
+    if grid is None or not selected:
         if not count:
             raise ValueError("no GRIB2 messages found")
         raise ValueError(
@@ -383,14 +449,16 @@ def open_grib2(
             raise ValueError(report)
         warnings.warn(report, UserWarning, stacklevel=_caller_stacklevel())
     variables: dict[str, Any] = {}
-    duplicates = {name for name in names if names.count(name) > 1}
-    for (data, attrs), name in zip(fields.values(), names, strict=True):
-        label = name
-        if name in duplicates:
-            label = f"{name}_{attrs.get('typeOfLevel', 'level')}_{attrs.get('level', '')}"
-        if label in variables:
-            label = f"{label}_{len(variables)}"
-        variables[label] = (grid.dims, data, attrs)
+    messages: dict[str, dict[str, Any]] = {}
+    names = variable_names(
+        [
+            (field.short, field.attrs.get("typeOfLevel"), field.attrs.get("level"))
+            for field in selected
+        ]
+    )
+    for label, field in zip(names, selected, strict=True):
+        variables[label] = (grid.dims, field.data, field.attrs)
+        messages[label] = field.message
     dataset = xarray.Dataset(variables, coords=grid.coords)
     dataset.latitude.attrs["units"] = "degrees_north"
     dataset.longitude.attrs["units"] = "degrees_east"
@@ -398,6 +466,7 @@ def open_grib2(
     dataset.attrs["usdata"] = {
         "asset_id": fetched.asset.id,
         "provenance": fetched.provenance.model_dump(mode="json"),
+        "messages": messages,
     }
     fill_registry_attrs(fetched, dataset)
     return dataset

{usdata-0.17.0 → usdata-0.18.0}/src/usdata/cache.py

@@ -56,6 +56,11 @@ def cached_path(dataset_id: str, asset_id: str, root: Path | None = None) -> Pat
     return path
 
 
+def sha256_bytes(data: bytes) -> str:
+    """Hex sha256 of a byte string, prefixed 'sha256:' as ``sha256_file`` prefixes a file's."""
+    return f"sha256:{hashlib.sha256(data).hexdigest()}"
+
+
 def sha256_file(path: Path) -> str:
     """Hex sha256 of a file, prefixed 'sha256:' to match Asset.checksum."""
     with path.open("rb") as f:

{usdata-0.17.0 → usdata-0.18.0}/src/usdata/cite.py

@@ -7,6 +7,7 @@ Rendering is plain text for a methods section or BibTeX for a bibliography.
 
 from __future__ import annotations
 
+import os
 import re
 from collections.abc import Iterable
 from pathlib import Path
@@ -21,6 +22,18 @@ from usdata.registry import Registry, default_registry
 ACCESSED_VIA = "accessed via usdata"
 """Tail of the fallback citation used when a registry entry states none."""
 
+DATE_PLACEHOLDER = "[date]"
+"""Literal an agency's requested citation leaves where the retrieval date belongs."""
+
+PLACEHOLDER_NOTE = (
+    f"{DATE_PLACEHOLDER} is filled from a lockfile; cite a pulled manifest to date this"
+)
+"""Note rendered beside a citation whose placeholder no lockfile has filled."""
+
+UNRECORDED_DATE = "an unrecorded date"
+"""Stand-in for a retrieval range that carries no bounds at all."""
+
+_ON_PLACEHOLDER = re.compile(rf"\bon {re.escape(DATE_PLACEHOLDER)}")
 _NOT_KEY = re.compile(r"[^A-Za-z0-9]+")
 _BIBTEX_SPECIAL = re.compile(r"([&%$#_])")
 
@@ -50,6 +63,23 @@ class Citation(BaseModel):
         default_factory=list, description="Keys of the manifest sources that pinned the assets"
     )
 
+    def as_text(self) -> str:
+        """Render this citation the way ``usdata cite`` prints it.
+
+        Returns:
+            The dataset id, the citation text, and each field that is set, one
+            labelled line apiece.
+        """
+        return render_text([self])
+
+    def as_bibtex(self) -> str:
+        """Render this citation the way ``usdata cite --format bibtex`` prints it.
+
+        Returns:
+            One ``@misc`` entry keyed on the dataset id.
+        """
+        return render_bibtex([self])
+
 
 def cite_dataset(dataset: Dataset, *, registry: Registry | None = None) -> Citation:
     """Build the citation for one registry entry.
@@ -74,11 +104,14 @@ def cite_dataset(dataset: Dataset, *, registry: Registry | None = None) -> Citat
     )
 
 
-def cite_lockfile(manifest_path: Path, registry: Registry | None = None) -> list[Citation]:
+def cite_lockfile(
+    manifest_path: str | os.PathLike[str], registry: Registry | None = None
+) -> list[Citation]:
     """Cite every dataset a manifest's lockfile pins, one citation per dataset.
 
     Args:
-        manifest_path: The manifest whose lockfile records what was fetched.
+        manifest_path: The manifest whose lockfile records what was fetched,
+            written as a string or as any ``os.PathLike``.
         registry: Registry the pinned dataset ids are looked up in. The bundled
             registry by default.
 
@@ -92,6 +125,7 @@ def cite_lockfile(manifest_path: Path, registry: Registry | None = None) -> list
         DatasetNotFound: The lockfile pins a dataset the registry does not know.
     """
     reg = registry or default_registry()
+    manifest_path = Path(manifest_path)
     lock = Lockfile.load(lockfile_path(manifest_path))
     _check_manifest(manifest_path, lock)
     grouped: dict[str, list[LockedAsset]] = {}
@@ -126,11 +160,13 @@ def _cite_pinned(
 ) -> Citation:
     """One dataset's citation, extended with what its lockfile entries record."""
     times = [entry.provenance.retrieved_at for entry in entries]
+    retrieved = TimeRange(start=min(times), end=max(times))
     base = cite_dataset(registry.get(dataset_id), registry=registry)
     return base.model_copy(
         update={
+            "text": _fill_date(base.text, retrieved),
             "license": base.license or entries[0].provenance.license,
-            "retrieved": TimeRange(start=min(times), end=max(times)),
+            "retrieved": retrieved,
             "asset_count": len(entries),
             "total_bytes": sum(entry.provenance.size for entry in entries),
             "usdata_version": usdata_version,
@@ -139,10 +175,31 @@ def _cite_pinned(
     )
 
 
+def _dates(retrieved: TimeRange) -> list[str]:
+    """The distinct ISO dates a retrieval range touches, earliest first."""
+    bounds = [moment.date().isoformat() for moment in (retrieved.start, retrieved.end) if moment]
+    return list(dict.fromkeys(bounds))
+
+
+def _fill_date(text: str, retrieved: TimeRange) -> str:
+    """The citation text with any literal ``[date]`` replaced by when it was retrieved.
+
+    A range within one day reads as that date, and a wider one as 'between A and
+    B', so no rendering of a lockfile citation keeps the placeholder.
+    """
+    if DATE_PLACEHOLDER not in text:
+        return text
+    dates = _dates(retrieved)
+    if len(dates) < 2:
+        return text.replace(DATE_PLACEHOLDER, dates[0] if dates else UNRECORDED_DATE)
+    span = f"between {dates[0]} and {dates[-1]}"
+    # 'accessed on [date]' has to read 'accessed between A and B', not 'on between'.
+    return _ON_PLACEHOLDER.sub(span, text).replace(DATE_PLACEHOLDER, span)
+
+
 def _retrieval(citation: Citation, retrieved: TimeRange) -> str:
     """The retrieval dates, checksummed asset count, size, and pinning version."""
-    bounds = [moment.date().isoformat() for moment in (retrieved.start, retrieved.end) if moment]
-    dates = " through ".join(dict.fromkeys(bounds)) or "an unrecorded date"
+    dates = " through ".join(_dates(retrieved)) or UNRECORDED_DATE
     assets = "asset" if citation.asset_count == 1 else "assets"
     version = f" by usdata {citation.usdata_version}" if citation.usdata_version else ""
     return (
@@ -164,6 +221,8 @@ def _text_lines(citation: Citation) -> list[str]:
         lines.append(f"  retrieved: {_retrieval(citation, retrieved)}")
     if citation.sources:
         lines.append(f"  sources: {', '.join(citation.sources)}")
+    if DATE_PLACEHOLDER in citation.text:
+        lines.append(f"  note: {PLACEHOLDER_NOTE}")
     return lines
 
 
@@ -189,6 +248,9 @@ def _escape(value: str) -> str:
 
 __all__ = [
     "ACCESSED_VIA",
+    "DATE_PLACEHOLDER",
+    "PLACEHOLDER_NOTE",
+    "UNRECORDED_DATE",
     "Citation",
     "cite_dataset",
     "cite_lockfile",

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from collections.abc import Iterable
 from pathlib import Path
 from typing import Annotated
 
@@ -22,7 +23,8 @@ from usdata.manifest import lockfile_path
 from usdata.models import READER_EXTRAS_TEXT, Dataset, Status, describe_duration
 from usdata.providers import load_adapter
 from usdata.providers.base import NotImplementedProvider
-from usdata.pull import EmptySource, ManifestChanged, UnknownDatasets, UpstreamChanged
+from usdata.pull import EmptySource, ManifestChanged, Plan, UnknownDatasets, UpstreamChanged
+from usdata.pull import plan as plan_manifest
 from usdata.pull import pull as pull_manifest
 from usdata.pull import verify as verify_manifest
 from usdata.query import UnknownPlace
@@ -57,6 +59,25 @@ _QUERY_FLAGS = {
 }
 
 
+def _size_phrase(known_bytes: int, unknown: int, *, sources: Iterable[str] = ()) -> str:
+    """How many bytes a dry run would move, said honestly when some size is missing.
+
+    A bare total would read as a measurement; when an adapter reports no size for
+    an asset, the known bytes are a floor and the sources that withheld a size are
+    named instead.
+    """
+    if not unknown:
+        return f"{known_bytes} bytes"
+    phrase = f"at least {known_bytes} bytes; size unknown for {unknown} asset(s)"
+    named = ", ".join(sources)
+    return f"{phrase} from {named}" if named else phrase
+
+
+def _asset_line(asset_id: str, size: int | None, href: str) -> str:
+    """One dry-run row: id, size or '?' when the adapter reported none, and the href."""
+    return f"{asset_id}\t{size if size is not None else '?'}\t{href}"
+
+
 _STATUS_HELP = f"Support status to include: {', '.join(STATUS_FILTERS)}."
 
 _ProviderOption = Annotated[str | None, typer.Option(help="Restrict to one provider, e.g. noaa.")]
@@ -368,12 +389,11 @@ def fetch(
                 typer.echo(json.dumps([a.model_dump(mode="json") for a in assets], indent=2))
             else:
                 for a in assets:
-                    typer.echo(f"{a.id}\t{a.size if a.size is not None else '?'}\t{a.href}")
+                    typer.echo(_asset_line(a.id, a.size, a.href))
             known = [a.size for a in assets if a.size is not None]
-            summary = f"{len(assets)} asset(s) matched, {sum(known)} bytes"
-            if len(known) != len(assets):
-                summary += f"; size unknown for {len(assets) - len(known)}"
-            typer.echo(summary, err=True)
+            unknown = len(assets) - len(known)
+            sizes = _size_phrase(sum(known), unknown, sources=[ds.id] if unknown else [])
+            typer.echo(f"{len(assets)} asset(s) matched, {sizes}", err=True)
             with progress(disabled=no_progress):
                 batch([asset.size for asset in assets])
             return
@@ -399,6 +419,26 @@ def fetch(
         typer.echo(f"{f.path}\t{tag}\t{f.provenance.size} bytes")
 
 
+def _print_plan(plan: Plan, *, as_json: bool, quiet: bool) -> None:
+    """Report what a pull would fetch: assets, a subtotal per source, a total on stderr."""
+    if as_json:
+        typer.echo(plan.model_dump_json(indent=2))
+    else:
+        for source in plan.sources:
+            if not quiet:
+                for asset in source.assets:
+                    typer.echo(_asset_line(asset.id, asset.size, asset.href))
+            sizes = _size_phrase(source.known_bytes, source.unknown_sizes)
+            typer.echo(
+                f"{source.source} ({source.dataset_id}): {len(source.assets)} asset(s), {sizes}"
+            )
+    total = _size_phrase(plan.known_bytes, plan.unknown_sizes, sources=plan.unsized_sources)
+    typer.echo(
+        f"{len(plan.sources)} source(s), {plan.asset_count} asset(s), {total}; nothing downloaded",
+        err=True,
+    )
+
+
 @app.command()
 def pull(
     manifest: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
@@ -420,9 +460,29 @@ def pull(
         bool,
         typer.Option("--quiet", "-q", help="Print only the summary line, not one line per asset."),
     ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(help="List what every source would fetch, and its size, without downloading."),
+    ] = False,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="With --dry-run, emit the plan as JSON on stdout.")
+    ] = False,
 ) -> None:
     """Fetch every source in a manifest and write (or restore from) its lockfile."""
+    if as_json and not dry_run:
+        typer.secho("--json applies to --dry-run only", err=True, fg="red")
+        raise typer.Exit(code=2)
+    if dry_run and update:
+        typer.secho(
+            "--dry-run prices a fresh resolve of every source; it cannot update pins",
+            err=True,
+            fg="red",
+        )
+        raise typer.Exit(code=2)
     try:
+        if dry_run:
+            _print_plan(plan_manifest(manifest), as_json=as_json, quiet=quiet)
+            return
         with progress(disabled=no_progress):
             result = pull_manifest(manifest, root=cache_dir, force=force, update=update or [])
     except EmptySource as e:

{usdata-0.17.0 → usdata-0.18.0}/src/usdata/cli/inspect.py

@@ -111,12 +111,29 @@ def _echo_detail(summary: Summary, width: int) -> None:
             ],
         )
     if (fields := summary.grib2) is not None:
+        # A partial fetch knows both numberings and the selector each message
+        # was asked for; a whole file knows neither, so those columns are dropped.
+        in_object = any(message.object_index is not None for message in fields.messages)
+        asked = any(message.selector is not None for message in fields.messages)
+        numbering = ["file #", "object #"] if in_object else ["#"]
         _echo_table(
             "messages",
-            ["#", "shortName", "name", "typeOfLevel", "level", "step", "units", "grid"],
+            [
+                *numbering,
+                *(["selector"] if asked else []),
+                "shortName",
+                "name",
+                "typeOfLevel",
+                "level",
+                "step",
+                "units",
+                "grid",
+            ],
             [
                 [
-                    str(message.index),
+                    str(message.file_index),
+                    *([str(message.object_index or "")] if in_object else []),
+                    *([message.selector or ""] if asked else []),
                     message.short_name or "",
                     message.name or "",
                     message.type_of_level or "",