usdata 0.9.0__tar.gz → 0.11.0__tar.gz

usdata-0.11.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.11.0
+Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
+Keywords: noaa,usgs,nasa,open-data,scientific-data,provenance
+Author: Jake Van Slyke
+Author-email: Jake Van Slyke <jakervanslyke@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.18
+Requires-Dist: xarray>=2025.1 ; extra == 'netcdf'
+Requires-Dist: h5netcdf[h5py]>=1.8.1 ; extra == 'netcdf'
+Requires-Dist: pandas>=3.0 ; extra == 'pandas'
+Requires-Dist: xradar>=0.12.0 ; extra == 'radar'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://usdata.dev/
+Project-URL: Documentation, https://docs.usdata.dev/
+Project-URL: Repository, https://github.com/jakeryderv/usdata
+Provides-Extra: netcdf
+Provides-Extra: pandas
+Provides-Extra: radar
+Description-Content-Type: text/markdown
+
+# usdata
+
+Discover U.S. scientific datasets, fetch their files, and keep a reproducible
+record of where every input came from. Use the same Python SDK or CLI across
+supported NOAA and USGS datasets.
+
+**Pre-alpha.** These docs describe the current source checkout. Features marked
+**Unreleased** require a source installation; consult the
+[changelog](CHANGELOG.md) for published versions. Other providers are planned.
+
+Project home: [usdata.dev](https://usdata.dev/).
+[Documentation and getting started](https://docs.usdata.dev/).
+
+## Start here
+
+```sh
+pip install usdata
+usdata search precipitation --location Oklahoma
+usdata info noaa:ghcn-daily
+```
+
+Search uses a curated registry. Fetching contacts the upstream service; readers
+open the resulting local files. Provenance and manifests connect those steps.
+
+- [Quick start and documentation](docs/index.md)
+- [Fetch and analyze data](docs/guides/fetch-and-analyze.md)
+- [Runnable examples with saved outputs](examples/README.md)
+- [Readers](docs/reference/readers.md) and [reproducible manifests](docs/reference/manifests.md)
+
+## Source installation
+
+For features marked **Unreleased**, install this checkout with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/jakeryderv/usdata && cd usdata
+uv sync --extra pandas
+uv run usdata info noaa:coops-water-levels
+```
+
+Run source examples from this checkout with `uv run usdata` (CLI) or
+`uv run python` (Python). The pandas extra enables CSV reading; use `--extra radar`
+or `--extra netcdf` for those formats. For contribution checks, continue with
+[development setup](#development).
+
+## Providers
+
+Browse the [dataset catalog](docs/generated/catalog/index.md) for current support,
+release availability, and dataset details. [Provider access notes](docs/providers/README.md)
+explain agency-specific services; the [roadmap](docs/roadmap.md) describes priorities.
+
+## Development
+
+```sh
+just setup
+just check
+```
+
+See [development setup and commands](docs/project.md#development),
+[contributing](CONTRIBUTING.md), and [architecture](docs/architecture.md).
+
+## License
+
+[Apache-2.0](LICENSE).

usdata-0.11.0/README.md

@@ -0,0 +1,64 @@
+# usdata
+
+Discover U.S. scientific datasets, fetch their files, and keep a reproducible
+record of where every input came from. Use the same Python SDK or CLI across
+supported NOAA and USGS datasets.
+
+**Pre-alpha.** These docs describe the current source checkout. Features marked
+**Unreleased** require a source installation; consult the
+[changelog](CHANGELOG.md) for published versions. Other providers are planned.
+
+Project home: [usdata.dev](https://usdata.dev/).
+[Documentation and getting started](https://docs.usdata.dev/).
+
+## Start here
+
+```sh
+pip install usdata
+usdata search precipitation --location Oklahoma
+usdata info noaa:ghcn-daily
+```
+
+Search uses a curated registry. Fetching contacts the upstream service; readers
+open the resulting local files. Provenance and manifests connect those steps.
+
+- [Quick start and documentation](docs/index.md)
+- [Fetch and analyze data](docs/guides/fetch-and-analyze.md)
+- [Runnable examples with saved outputs](examples/README.md)
+- [Readers](docs/reference/readers.md) and [reproducible manifests](docs/reference/manifests.md)
+
+## Source installation
+
+For features marked **Unreleased**, install this checkout with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/jakeryderv/usdata && cd usdata
+uv sync --extra pandas
+uv run usdata info noaa:coops-water-levels
+```
+
+Run source examples from this checkout with `uv run usdata` (CLI) or
+`uv run python` (Python). The pandas extra enables CSV reading; use `--extra radar`
+or `--extra netcdf` for those formats. For contribution checks, continue with
+[development setup](#development).
+
+## Providers
+
+Browse the [dataset catalog](docs/generated/catalog/index.md) for current support,
+release availability, and dataset details. [Provider access notes](docs/providers/README.md)
+explain agency-specific services; the [roadmap](docs/roadmap.md) describes priorities.
+
+## Development
+
+```sh
+just setup
+just check
+```
+
+See [development setup and commands](docs/project.md#development),
+[contributing](CONTRIBUTING.md), and [architecture](docs/architecture.md).
+
+## License
+
+[Apache-2.0](LICENSE).

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.9.0"
+version = "0.11.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"
@@ -39,7 +39,8 @@ netcdf = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/jakeryderv/usdata"
+Homepage = "https://usdata.dev/"
+Documentation = "https://docs.usdata.dev/"
 Repository = "https://github.com/jakeryderv/usdata"
 
 [project.scripts]
@@ -47,16 +48,20 @@ usdata = "usdata.cli:app"
 
 [dependency-groups]
 dev = [
+    "pre-commit>=4.6.0",
     "pyright>=1.1.380",
     "pytest>=8.0",
     "pytest-cov>=7.1.0",
     "respx>=0.23.1",
     "ruff>=0.6",
+    "towncrier>=26.9",
 ]
 docs = [
     "mkdocstrings-python>=2.0.8",
     "nbconvert>=7.17.1",
-    "zensical>=0.0.60",
+    "towncrier>=26.9",
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.7,<10",
 ]
 examples = [
     "ipykernel>=6.29",
@@ -126,3 +131,64 @@ markers = [
     "netcdf: optional NetCDF reader coverage",
 ]
 addopts = "-ra --strict-markers"
+
+[tool.towncrier]
+directory = "changes"
+filename = "CHANGELOG.md"
+start_string = """
+<!-- towncrier release notes start -->
+"""
+underlines = [
+    "",
+    "",
+    "",
+]
+title_format = "## [{version}](https://github.com/jakeryderv/usdata/releases/tag/v{version}) - {project_date}"
+issue_format = "[#{issue}](https://github.com/jakeryderv/usdata/issues/{issue})"
+template = "scripts/templates/changelog.md.jinja"
+wrap = false
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "documentation"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "development"
+name = "Development"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "internal"
+name = "Internal"
+showcontent = true

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.9.0"
+version = "0.11.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"
@@ -28,7 +28,8 @@ radar = ["xradar>=0.12.0"]
 netcdf = ["xarray>=2025.1", "h5netcdf[h5py]>=1.8.1"]
 
 [project.urls]
-Homepage = "https://github.com/jakeryderv/usdata"
+Homepage = "https://usdata.dev/"
+Documentation = "https://docs.usdata.dev/"
 Repository = "https://github.com/jakeryderv/usdata"
 
 [project.scripts]
@@ -36,16 +37,20 @@ usdata = "usdata.cli:app"
 
 [dependency-groups]
 dev = [
+    "pre-commit>=4.6.0",
     "pyright>=1.1.380",
     "pytest>=8.0",
     "pytest-cov>=7.1.0",
     "respx>=0.23.1",
     "ruff>=0.6",
+    "towncrier>=26.9",
 ]
 docs = [
     "mkdocstrings-python>=2.0.8",
     "nbconvert>=7.17.1",
-    "zensical>=0.0.60",
+    "towncrier>=26.9",
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.7,<10",
 ]
 examples = [
     "ipykernel>=6.29",
@@ -98,3 +103,58 @@ markers = [
     "netcdf: optional NetCDF reader coverage",
 ]
 addopts = "-ra --strict-markers"
+
+[tool.towncrier]
+directory = "changes"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+title_format = "## [{version}](https://github.com/jakeryderv/usdata/releases/tag/v{version}) - {project_date}"
+issue_format = "[#{issue}](https://github.com/jakeryderv/usdata/issues/{issue})"
+template = "scripts/templates/changelog.md.jinja"
+wrap = false
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "documentation"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "development"
+name = "Development"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "internal"
+name = "Internal"
+showcontent = true

{usdata-0.9.0 → usdata-0.11.0}/src/usdata/cli/app.py

@@ -16,7 +16,7 @@ from usdata.fetch import fetch as fetch_query
 from usdata.manifest import lockfile_path
 from usdata.providers import load_adapter
 from usdata.providers.base import NotImplementedProvider
-from usdata.pull import EmptySource, ManifestChanged, UnknownDatasets
+from usdata.pull import EmptySource, ManifestChanged, UnknownDatasets, UpstreamChanged
 from usdata.pull import pull as pull_manifest
 from usdata.pull import verify as verify_manifest
 from usdata.query import UnknownPlace
@@ -29,6 +29,20 @@ app = typer.Typer(
 )
 
 
+_QUERY_FLAGS = {
+    "location": "--location",
+    "bbox": "--bbox",
+    "lat": "--lat",
+    "lon": "--lon",
+    "radius_km": "--radius-km",
+    "start": "--start",
+    "end": "--end",
+    "variables": "--vars",
+    "text": None,
+    "provider": None,
+}
+
+
 def _version_callback(value: bool) -> None:
     if value:
         typer.echo(f"usdata {__version__}")
@@ -140,6 +154,19 @@ def fetch(
         if not sep:
             typer.secho(f"--param expects key=value, got {item!r}", err=True, fg="red")
             raise typer.Exit(code=2)
+        if key in _QUERY_FLAGS:
+            flag = _QUERY_FLAGS[key]
+            hint = (
+                f"use {flag} instead of --param"
+                if flag is not None
+                else "fetch does not support this option"
+            )
+            typer.secho(
+                f"{key} is a reserved query option; {hint}",
+                err=True,
+                fg="red",
+            )
+            raise typer.Exit(code=2)
         params[key] = value
     box = None
     if bbox:
@@ -198,12 +225,18 @@ def pull(
         bool,
         typer.Option(help="Ignore an existing lockfile: re-resolve every source and rewrite it."),
     ] = False,
+    update: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Asset or dataset id whose pin should follow current upstream bytes; repeatable."
+        ),
+    ] = None,
     no_progress: Annotated[bool, typer.Option(help="Disable terminal progress.")] = False,
 ) -> None:
     """Fetch every source in a manifest and write (or restore from) its lockfile."""
     try:
         with progress(disabled=no_progress):
-            result = pull_manifest(manifest, root=cache_dir, force=force)
+            result = pull_manifest(manifest, root=cache_dir, force=force, update=update or [])
     except EmptySource as e:
         typer.secho(str(e), err=True, fg="yellow")
         raise typer.Exit(code=1) from None
@@ -213,13 +246,27 @@ def pull(
     except NotImplementedProvider as e:
         typer.secho(str(e), err=True, fg="yellow")
         raise typer.Exit(code=3) from None
+    except UpstreamChanged as e:
+        for d in e.drift:
+            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.",
+            err=True,
+            fg="red",
+        )
+        raise typer.Exit(code=4) from None
     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)
     for f in result.fetched:
-        tag = "cached" if f.from_cache else "fetched"
+        tag = "updated" if f.asset.id in updated else "cached" if f.from_cache else "fetched"
         typer.echo(f"{f.path}\t{tag}\t{f.provenance.size} bytes")
-    mode = "restored from" if result.from_lockfile else "wrote"
+    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)