usdata 0.8.0__tar.gz → 0.10.0__tar.gz

usdata-0.10.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.10.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://github.com/jakeryderv/usdata
+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.
+
+## 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
+
+From a [source checkout](#source-installation), requires [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/).
+
+`just setup` uses the tested Python 3.14.7 pin in `.python-version`. Older Linux
+uv Python 3.14 builds can crash during NumPy array operations; see
+[the upstream fix](https://github.com/astral-sh/python-build-standalone/issues/991).
+
+```sh
+just setup     # install toolchain and dependencies
+just hooks-install # optional: install fast staged-file checks
+just test      # all offline tests
+just check     # format, lint, typecheck, offline tests, generated docs, release notices
+just check-pandas  # install the CSV extra and run the same checks
+just check-radar   # install the radar extra and run the same checks
+just check-netcdf  # install the NetCDF4 extra and run the same checks
+just notebooks    # launch the optional Jupyter examples environment
+just run-notebooks # execute notebooks live in fresh kernels and temporary caches
+just docs-serve # build and preview the documentation locally, with reload
+just check-docs # validate generated content and build the site strictly
+just build     # build wheel and sdist
+just smoke     # exercise core and pandas wheel installations outside the checkout
+just changes   # preview upcoming release notes
+just cleanup 123 # from main: remove PR #123's merged branch and clean worktree
+just run search radar
+```
+
+Commit hooks fix and format staged Python files using the locked Ruff version,
+and check configuration, merge conflicts, and GitHub Actions workflows. Full
+validation remains `just check`; `just check-hooks` runs the non-mutating config
+and workflow checks alone. Hooks do not rewrite notebooks or raw data fixtures.
+The first hook run downloads its isolated tools and requires network access.
+
+Offline tests mechanically block network connections. Tests that hit
+live services run with `just test-live`; see [testing levels and organization](docs/testing.md). CI checks Python 3.11 and 3.14 on
+Linux with core-only, pandas, radar, and NetCDF dependency profiles. Installed-wheel
+checks cover all four profiles on Linux, macOS, and Windows. The full offline and
+live-service suites run on Linux. `just setup` restores a core-only development
+environment; the `check-pandas`, `check-radar`, and `check-netcdf` commands install
+their respective extras.
+
+Releases: `just release minor` prepares a release branch. Update release notices,
+then `just release-pr` validates and opens a draft for review. Merging the reviewed
+PR publishes to PyPI and creates the tag and GitHub release. See
+[docs/versioning.md](docs/versioning.md).
+
+See [provider access notes](docs/providers/README.md),
+[docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[architecture decisions](docs/adr/README.md) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
+
+## License
+
+[Apache-2.0](LICENSE).

usdata-0.10.0/README.md

@@ -0,0 +1,102 @@
+# 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.
+
+## 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
+
+From a [source checkout](#source-installation), requires [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/).
+
+`just setup` uses the tested Python 3.14.7 pin in `.python-version`. Older Linux
+uv Python 3.14 builds can crash during NumPy array operations; see
+[the upstream fix](https://github.com/astral-sh/python-build-standalone/issues/991).
+
+```sh
+just setup     # install toolchain and dependencies
+just hooks-install # optional: install fast staged-file checks
+just test      # all offline tests
+just check     # format, lint, typecheck, offline tests, generated docs, release notices
+just check-pandas  # install the CSV extra and run the same checks
+just check-radar   # install the radar extra and run the same checks
+just check-netcdf  # install the NetCDF4 extra and run the same checks
+just notebooks    # launch the optional Jupyter examples environment
+just run-notebooks # execute notebooks live in fresh kernels and temporary caches
+just docs-serve # build and preview the documentation locally, with reload
+just check-docs # validate generated content and build the site strictly
+just build     # build wheel and sdist
+just smoke     # exercise core and pandas wheel installations outside the checkout
+just changes   # preview upcoming release notes
+just cleanup 123 # from main: remove PR #123's merged branch and clean worktree
+just run search radar
+```
+
+Commit hooks fix and format staged Python files using the locked Ruff version,
+and check configuration, merge conflicts, and GitHub Actions workflows. Full
+validation remains `just check`; `just check-hooks` runs the non-mutating config
+and workflow checks alone. Hooks do not rewrite notebooks or raw data fixtures.
+The first hook run downloads its isolated tools and requires network access.
+
+Offline tests mechanically block network connections. Tests that hit
+live services run with `just test-live`; see [testing levels and organization](docs/testing.md). CI checks Python 3.11 and 3.14 on
+Linux with core-only, pandas, radar, and NetCDF dependency profiles. Installed-wheel
+checks cover all four profiles on Linux, macOS, and Windows. The full offline and
+live-service suites run on Linux. `just setup` restores a core-only development
+environment; the `check-pandas`, `check-radar`, and `check-netcdf` commands install
+their respective extras.
+
+Releases: `just release minor` prepares a release branch. Update release notices,
+then `just release-pr` validates and opens a draft for review. Merging the reviewed
+PR publishes to PyPI and creates the tag and GitHub release. See
+[docs/versioning.md](docs/versioning.md).
+
+See [provider access notes](docs/providers/README.md),
+[docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[architecture decisions](docs/adr/README.md) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
+
+## License
+
+[Apache-2.0](LICENSE).

usdata-0.10.0/pyproject.toml

@@ -0,0 +1,193 @@
+[project]
+name = "usdata"
+version = "0.10.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"
+requires-python = ">=3.11"
+keywords = [
+    "noaa",
+    "usgs",
+    "nasa",
+    "open-data",
+    "scientific-data",
+    "provenance",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "typer>=0.18",
+]
+
+[[project.authors]]
+name = "Jake Van Slyke"
+email = "jakervanslyke@gmail.com"
+
+[project.optional-dependencies]
+pandas = ["pandas>=3.0"]
+radar = ["xradar>=0.12.0"]
+netcdf = [
+    "xarray>=2025.1",
+    "h5netcdf[h5py]>=1.8.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jakeryderv/usdata"
+Repository = "https://github.com/jakeryderv/usdata"
+
+[project.scripts]
+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 = [
+    "tomli-w>=1.2.0",
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "towncrier>=26.9",
+    "zensical>=0.0.60",
+]
+examples = [
+    "ipykernel>=6.29",
+    "jupyterlab>=4.3",
+    "matplotlib>=3.9",
+    "nbclient>=0.10",
+    "pandas>=3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "D",
+]
+ignore = [
+    "D105",
+    "D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"scripts/**" = ["D"]
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "l0: pure in-memory logic",
+    "l1: in-process components with controlled transport",
+    "l2: local functional tests with filesystem or real decoders",
+    "l3: controlled service deployment (currently unused)",
+    "l4: production or upstream-live compatibility",
+    "live: hits upstream services; requires --run-live",
+    "integration: compatibility alias for live",
+    "pandas: optional CSV reader coverage",
+    "radar: optional radar reader coverage",
+    "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.10.0/pyproject.toml.orig

@@ -0,0 +1,159 @@
+[project]
+name = "usdata"
+version = "0.10.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"
+authors = [
+    { name = "Jake Van Slyke", email = "jakervanslyke@gmail.com" }
+]
+requires-python = ">=3.11"
+keywords = ["noaa", "usgs", "nasa", "open-data", "scientific-data", "provenance"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "typer>=0.18",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=3.0"]
+radar = ["xradar>=0.12.0"]
+netcdf = ["xarray>=2025.1", "h5netcdf[h5py]>=1.8.1"]
+
+[project.urls]
+Homepage = "https://github.com/jakeryderv/usdata"
+Repository = "https://github.com/jakeryderv/usdata"
+
+[project.scripts]
+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 = [
+    "tomli-w>=1.2.0",
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "towncrier>=26.9",
+    "zensical>=0.0.60",
+]
+examples = [
+    "ipykernel>=6.29",
+    "jupyterlab>=4.3",
+    "matplotlib>=3.9",
+    "nbclient>=0.10",
+    "pandas>=3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "D"]
+# Docstrings are required on the public API only; magic methods and __init__ are exempt.
+ignore = ["D105", "D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+"scripts/**" = ["D"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "l0: pure in-memory logic",
+    "l1: in-process components with controlled transport",
+    "l2: local functional tests with filesystem or real decoders",
+    "l3: controlled service deployment (currently unused)",
+    "l4: production or upstream-live compatibility",
+    "live: hits upstream services; requires --run-live",
+    "integration: compatibility alias for live",
+    "pandas: optional CSV reader coverage",
+    "radar: optional radar reader coverage",
+    "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.8.0 → usdata-0.10.0}/src/usdata/__init__.py

@@ -10,10 +10,11 @@ try:
 except PackageNotFoundError:  # running from a source tree without an install
     __version__ = "0.0.0"
 
-from usdata.models import Asset, BBox, Dataset, Provenance, Query, TimeRange
+from usdata.models import Asset, BBox, Dataset, Provenance, Query, TemporalSelection, TimeRange
 from usdata.pull import pull, verify
 from usdata.query import build_query
 from usdata.registry import DatasetNotFound, Registry, SearchResult, default_registry
+from usdata.selection import select_by_time
 
 __all__ = [
     "Asset",
@@ -24,6 +25,7 @@ __all__ = [
     "Query",
     "Registry",
     "SearchResult",
+    "TemporalSelection",
     "TimeRange",
     "__version__",
     "build_query",
@@ -31,6 +33,7 @@ __all__ = [
     "get",
     "pull",
     "search",
+    "select_by_time",
     "verify",
 ]