usdata 0.8.0__tar.gz → 0.9.0__tar.gz

usdata-0.9.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: usdata
+Version: 0.9.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)
+
+## Providers
+
+<!-- registry:start -->
+| Provider | Available | Stub | Planned | Next up (unassigned) | Datasets |
+|---|---:|---:|---:|---|---|
+| [NOAA](docs/providers/noaa.md) | 6 | 0 | 23 | — | `ghcn-daily`, `gsom`, `storm-events`, `nexrad-level2`, `goes-abi`, `coastwatch-sst`, +23 planned |
+| [USGS](docs/providers/usgs.md) | 1 | 0 | 2 | — | `water-daily`, +2 planned |
+| [Census Bureau](docs/providers/census.md) | 0 | 0 | 1 | — | +1 planned |
+| [EPA](docs/providers/epa.md) | 0 | 0 | 1 | — | +1 planned |
+| [FEMA](docs/providers/fema.md) | 0 | 0 | 1 | — | +1 planned |
+| [NASA](docs/providers/nasa.md) | 0 | 0 | 1 | — | +1 planned |
+| [USDA](docs/providers/usda.md) | 0 | 0 | 1 | — | +1 planned |
+
+Available datasets are in `code`, stubs in _italics_; planned ones are counted. Available means implemented in this source checkout; consult the [releases](https://github.com/jakeryderv/usdata/releases) for published support. Provider pages link access notes to the generated dataset catalog; [the roadmap](docs/roadmap.md) explains future priorities.
+<!-- registry:end -->
+
+## Development
+
+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
+git clone https://github.com/jakeryderv/usdata && cd usdata
+just setup     # install toolchain and dependencies
+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 run search radar
+```
+
+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` opens a version-bump PR; merging it 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.9.0/README.md

@@ -0,0 +1,87 @@
+# 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)
+
+## Providers
+
+<!-- registry:start -->
+| Provider | Available | Stub | Planned | Next up (unassigned) | Datasets |
+|---|---:|---:|---:|---|---|
+| [NOAA](docs/providers/noaa.md) | 6 | 0 | 23 | — | `ghcn-daily`, `gsom`, `storm-events`, `nexrad-level2`, `goes-abi`, `coastwatch-sst`, +23 planned |
+| [USGS](docs/providers/usgs.md) | 1 | 0 | 2 | — | `water-daily`, +2 planned |
+| [Census Bureau](docs/providers/census.md) | 0 | 0 | 1 | — | +1 planned |
+| [EPA](docs/providers/epa.md) | 0 | 0 | 1 | — | +1 planned |
+| [FEMA](docs/providers/fema.md) | 0 | 0 | 1 | — | +1 planned |
+| [NASA](docs/providers/nasa.md) | 0 | 0 | 1 | — | +1 planned |
+| [USDA](docs/providers/usda.md) | 0 | 0 | 1 | — | +1 planned |
+
+Available datasets are in `code`, stubs in _italics_; planned ones are counted. Available means implemented in this source checkout; consult the [releases](https://github.com/jakeryderv/usdata/releases) for published support. Provider pages link access notes to the generated dataset catalog; [the roadmap](docs/roadmap.md) explains future priorities.
+<!-- registry:end -->
+
+## Development
+
+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
+git clone https://github.com/jakeryderv/usdata && cd usdata
+just setup     # install toolchain and dependencies
+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 run search radar
+```
+
+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` opens a version-bump PR; merging it 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.8.0 → usdata-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.8.0"
+version = "0.9.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"
@@ -23,7 +23,7 @@ dependencies = [
     "httpx>=0.28.1",
     "pydantic>=2.7",
     "pyyaml>=6.0",
-    "typer>=0.12",
+    "typer>=0.18",
 ]
 
 [[project.authors]]
@@ -53,6 +53,11 @@ dev = [
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
+docs = [
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "zensical>=0.0.60",
+]
 examples = [
     "ipykernel>=6.29",
     "jupyterlab>=4.3",
@@ -108,5 +113,16 @@ venv = ".venv"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-markers = ["integration: hits live services; skipped unless --run-integration is passed"]
-addopts = "-ra"
+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"

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

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.8.0"
+version = "0.9.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"
@@ -19,7 +19,7 @@ dependencies = [
     "httpx>=0.28.1",
     "pydantic>=2.7",
     "pyyaml>=6.0",
-    "typer>=0.12",
+    "typer>=0.18",
 ]
 
 [project.optional-dependencies]
@@ -42,6 +42,11 @@ dev = [
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
+docs = [
+    "mkdocstrings-python>=2.0.8",
+    "nbconvert>=7.17.1",
+    "zensical>=0.0.60",
+]
 examples = [
     "ipykernel>=6.29",
     "jupyterlab>=4.3",
@@ -81,6 +86,15 @@ venv = ".venv"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = [
-    "integration: hits live services; skipped unless --run-integration is passed",
+    "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"
+addopts = "-ra --strict-markers"

{usdata-0.8.0 → usdata-0.9.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",
 ]
 

usdata-0.9.0/src/usdata/_radar.py

@@ -0,0 +1,123 @@
+"""Local NEXRAD Level II decoding behind the radar extra."""
+
+from __future__ import annotations
+
+import bz2
+import gzip
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from usdata.readers import MissingReaderDependency, RadarDecodeError
+
+# NOAA RDA/RPG ICD 2620002Y, Table XVII-I notes 21 and 30.
+MOMENT_FLAG_COUNTS = {
+    "DBZH": 2,
+    "VRADH": 2,
+    "WRADH": 2,
+    "ZDR": 2,
+    "PHIDP": 2,
+    "RHOHV": 2,
+    "CCORH": 8,
+}
+
+if TYPE_CHECKING:
+    from usdata.fetch import FetchedAsset
+
+
+def _check_sweeps(content: bytes, sweep: int | list[int] | None) -> None:
+    """Reject decoder tables that pair a sweep with another sweep's coordinates.
+
+    xradar 0.12 can omit an interior sweep without an end marker from its data
+    table while keeping its moment metadata. The coordinate list then shifts.
+    Compare record identities, not just ray counts: equal-length sweeps can
+    otherwise silently acquire another sweep's coordinates and timestamps.
+    """
+    backend = import_module("xradar.io.backends.nexrad_level2")
+    with backend.NEXRADLevel2File(content, loaddata=False) as volume:
+        # Parsing completeness also populates the per-sweep data tables.
+        _ = volume.incomplete_sweeps
+        moments = volume.msg_31_data_header
+        coordinates = volume.msg_31_header
+        requested = (
+            list(range(len(moments)))
+            if sweep is None
+            else (sweep if isinstance(sweep, list) else [sweep])
+        )
+        for index in requested:
+            if index >= len(moments):
+                raise ValueError(f"sweep {index} is outside this volume's {len(moments)} sweeps")
+            data = volume.data.get(index)
+            rays = coordinates[index] if index < len(coordinates) else []
+            # Non-radial messages may occur within a sweep or after its last
+            # received ray. Follow the decoder's traversal, excluding those
+            # records, instead of requiring record_end to be a radial message.
+            expected_records = []
+            if data is not None:
+                intermediate = {record["record_number"] for record in data["intermediate_records"]}
+                expected_records = [
+                    record
+                    for record in range(data["record_number"], data["record_end"] + 1)
+                    if record not in intermediate
+                ]
+            if (
+                data is None
+                or not rays
+                or moments[index]["record_number"] != data["record_number"]
+                or [ray["record_number"] for ray in rays] != expected_records
+            ):
+                raise RadarDecodeError(
+                    f"cannot safely decode sweep {index}: NEXRAD moment and coordinate records "
+                    "do not agree; select an unaffected sweep explicitly with open(sweep=...) "
+                    "or use another decoder. No sweeps were silently dropped."
+                )
+
+
+def open_nexrad(fetched: FetchedAsset, *, sweep: int | list[int] | None = None) -> Any:
+    """Decode a local volume into a fully loaded xarray DataTree."""
+    try:
+        xradar = import_module("xradar")
+    except ModuleNotFoundError as error:
+        if error.name != "xradar":
+            raise
+        raise MissingReaderDependency(
+            'NEXRAD reading requires xradar; install it with: pip install "usdata[radar]" '
+            '(or uv add "usdata[radar]")'
+        ) from error
+
+    # Bytes prevent remote URL interpretation and work across the backend's
+    # repeated sweep reads. Compressed source files stay unchanged in the cache.
+    content = fetched.path.read_bytes()
+    if content.startswith(b"\x1f\x8b"):
+        content = gzip.decompress(content)
+    elif content.startswith(b"BZh"):
+        content = bz2.decompress(content)
+    _check_sweeps(content, sweep)
+    radar = xradar.io.open_nexradlevel2_datatree(content, sweep=sweep, incomplete_sweep="pad")
+    try:
+        radar.load()
+    finally:
+        radar.close()
+    for node in radar.subtree:
+        for name, variable in node.ds.variables.items():
+            # The backend records the entire input byte string as `source`.
+            # Provenance below is the durable reference, not that decoder buffer.
+            variable.encoding.pop("source", None)
+            if name in MOMENT_FLAG_COUNTS and "range" in variable.dims:
+                scale = variable.encoding.get("scale_factor")
+                offset = variable.encoding.get("add_offset")
+                if scale is not None and offset is not None:
+                    # xradar 0.12 does not supply _FillValue for NEXRAD flags.
+                    # Compare using each moment's native scale, not fixed units.
+                    data = node[name]
+                    valid = data.notnull()
+                    for code in range(MOMENT_FLAG_COUNTS[name]):
+                        valid = valid & (data != offset + code * scale)
+                    masked = data.where(valid)
+                    masked.encoding = data.encoding.copy()
+                    node[name] = masked
+    radar.attrs["usdata"] = {
+        "asset_id": fetched.asset.id,
+        "provenance": fetched.provenance.model_dump(mode="json"),
+        "sweeps": [name.lstrip("/") for name in radar.groups if name.startswith("/sweep_")],
+    }
+    return radar

{usdata-0.8.0 → usdata-0.9.0}/src/usdata/fetch.py

@@ -34,6 +34,7 @@ class FetchedAsset(BaseModel):
         parse_dates: list[str] | None = None,
         usecols: list[str] | None = None,
         nrows: int | None = None,
+        sweep: int | list[int] | None = None,
     ) -> Any:
         """Open local data with an optional ``pandas``, ``radar``, or ``netcdf`` reader.
 
@@ -41,12 +42,19 @@ class FetchedAsset(BaseModel):
         in ``frame.attrs["usdata"]``. NEXRAD returns a xarray DataTree with provenance
         in ``radar.attrs["usdata"]``. NetCDF4 returns a loaded xarray Dataset with
         matching provenance in its attributes. See ``usdata.readers.open_asset`` for options.
+        Use ``sweep=0`` or ``sweep=[0, 2]`` to load selected zero-based radar sweeps.
         Cached files and provenance sidecars are never changed.
         """
         from usdata.readers import open_asset
 
         return open_asset(
-            self, reader=reader, dtype=dtype, parse_dates=parse_dates, usecols=usecols, nrows=nrows
+            self,
+            reader=reader,
+            dtype=dtype,
+            parse_dates=parse_dates,
+            usecols=usecols,
+            nrows=nrows,
+            sweep=sweep,
         )
 
 

{usdata-0.8.0 → usdata-0.9.0}/src/usdata/models.py

@@ -9,9 +9,9 @@ from __future__ import annotations
 
 import math
 import re
-from datetime import datetime
+from datetime import datetime, timedelta
 from enum import StrEnum
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -79,6 +79,12 @@ class BBox(BaseModel):
     @classmethod
     def from_point(cls, lat: float, lon: float, radius_km: float = 0.0) -> BBox:
         """Box around a point. Uses a flat-earth approximation, fine for small radii."""
+        if not math.isfinite(lat) or not -90 <= lat <= 90:
+            raise ValueError("lat must be finite and between -90 and 90")
+        if not math.isfinite(lon) or not -180 <= lon <= 180:
+            raise ValueError("lon must be finite and between -180 and 180")
+        if not math.isfinite(radius_km) or radius_km < 0:
+            raise ValueError("radius_km must be finite and nonnegative")
         dlat = radius_km / 111.0
         dlon = radius_km / (111.0 * max(math.cos(math.radians(lat)), 1e-6))
         return cls(
@@ -223,6 +229,22 @@ class Asset(BaseModel):
     bbox: BBox | None = None
 
 
+class TemporalSelection(BaseModel):
+    """A start-time selection and its explicit policy; not source provenance.
+
+    No match has ``asset=None``, ``offset_seconds=None``, and zero eligible
+    candidates. Counts refer to the supplied candidates, not a remote catalog.
+    """
+
+    target: datetime
+    tolerance: timedelta
+    direction: Literal["nearest", "at_or_before"]
+    asset: Asset | None
+    offset_seconds: float | None
+    candidate_count: int = Field(ge=0)
+    eligible_count: int = Field(ge=0)
+
+
 class Provenance(BaseModel):
     """Everything needed to say where a local file came from and re-fetch it."""
 

{usdata-0.8.0 → usdata-0.9.0}/src/usdata/protocols/s3.py

@@ -57,11 +57,24 @@ def list_objects(
     own = client is None
     client = client or http.client()
     params: dict[str, str | int] = {"list-type": 2, "prefix": prefix, "max-keys": page_size}
+    seen_tokens: set[str] = set()
     try:
         while True:
             resp = http.get(https_url(bucket), client, params=params)
             resp.raise_for_status()
             root = ET.fromstring(resp.text)
+            truncated = _text(root, "IsTruncated") == "true"
+            token = _text(root, "NextContinuationToken")
+            if truncated:
+                if not token or not token.strip():
+                    raise httpx.RemoteProtocolError(
+                        "Truncated S3 listing has no continuation token", request=resp.request
+                    )
+                if token in seen_tokens:
+                    raise httpx.RemoteProtocolError(
+                        "S3 listing repeated a continuation token", request=resp.request
+                    )
+                seen_tokens.add(token)
             for contents in root.iter(NS + "Contents"):
                 key = _text(contents, "Key")
                 if key is None:
@@ -74,9 +87,9 @@ def list_objects(
                     etag=etag.strip('"') if etag else None,
                     last_modified=datetime.fromisoformat(modified) if modified else None,
                 )
-            token = _text(root, "NextContinuationToken")
-            if _text(root, "IsTruncated") != "true" or not token:
+            if not truncated:
                 return
+            assert token is not None
             params["continuation-token"] = token
     finally:
         if own:

usdata-0.9.0/src/usdata/providers/_http.py

@@ -0,0 +1,27 @@
+"""Internal lifecycle shared by adapters using an injected or owned HTTP client."""
+
+from __future__ import annotations
+
+import httpx
+
+from usdata.models import Dataset
+from usdata.protocols import http
+from usdata.providers.base import Provider
+
+
+class _HttpProvider(Provider):
+    def __init__(self, dataset: Dataset, client: httpx.Client | None = None) -> None:
+        super().__init__(dataset)
+        self._client = client
+        self._owns_client = client is None
+
+    def _http(self) -> httpx.Client:
+        if self._client is None:
+            self._client = http.client()
+        return self._client
+
+    def close(self) -> None:
+        """Close owned connections; injected clients remain the caller's responsibility."""
+        if self._owns_client and self._client is not None:
+            self._client.close()
+            self._client = None

{usdata-0.8.0 → usdata-0.9.0}/src/usdata/providers/noaa/coastwatch.py

@@ -18,9 +18,10 @@ from typing import cast
 
 import httpx
 
-from usdata.models import Asset, BBox, Dataset, Protocol, Query, TimeRange
+from usdata.models import Asset, BBox, Protocol, Query, TimeRange
 from usdata.protocols import erddap, http
-from usdata.providers.base import Provider, QueryError
+from usdata.providers._http import _HttpProvider
+from usdata.providers.base import QueryError
 
 BASE = "https://coastwatch.noaa.gov/erddap"
 DATASET = "noaacwBLENDEDsstDNDaily"
@@ -42,25 +43,9 @@ def _spatial_slice(
     ), length
 
 
-class CoastwatchSst(Provider):
+class CoastwatchSst(_HttpProvider):
     """NOAA's 0.05-degree day/night analysis, including units and grid coordinates."""
 
-    def __init__(self, dataset: Dataset, client: httpx.Client | None = None) -> None:
-        super().__init__(dataset)
-        self._client = client
-        self._owns_client = client is None
-
-    def _http(self) -> httpx.Client:
-        if self._client is None:
-            self._client = http.client()
-        return self._client
-
-    def close(self) -> None:
-        """Release owned connections; injected clients remain the caller's responsibility."""
-        if self._owns_client and self._client is not None:
-            self._client.close()
-            self._client = None
-
     def list_assets(self, query: Query) -> list[Asset]:
         """Resolve a valid grid intersection into one stable, bounded CSV request."""
         if (

{usdata-0.8.0 → usdata-0.9.0}/src/usdata/providers/noaa/ghcnd.py

@@ -18,9 +18,10 @@ from typing import Any
 
 import httpx
 
-from usdata.models import Asset, Dataset, Protocol, Query, TimeRange
+from usdata.models import Asset, Protocol, Query, TimeRange
 from usdata.protocols import http
-from usdata.providers.base import Provider, QueryError
+from usdata.providers._http import _HttpProvider
+from usdata.providers.base import QueryError
 
 SEARCH_URL = "https://www.ncei.noaa.gov/access/services/search/v1/data"
 DATA_URL = "https://www.ncei.noaa.gov/access/services/data/v1"
@@ -45,27 +46,11 @@ def _stations_param(raw: Any) -> list[str]:
     return stations
 
 
-class GhcnDaily(Provider):
+class GhcnDaily(_HttpProvider):
     """GHCN-Daily adapter. Params: ``stations`` (list or comma string), ``units``."""
 
     ncei_dataset = NCEI_DATASET
 
-    def __init__(self, dataset: Dataset, client: httpx.Client | None = None) -> None:
-        super().__init__(dataset)
-        self._client = client
-        self._owns_client = client is None
-
-    def close(self) -> None:
-        """Close an internally created HTTP client; injected clients belong to the caller."""
-        if self._owns_client and self._client is not None:
-            self._client.close()
-            self._client = None
-
-    def _http(self) -> httpx.Client:
-        if self._client is None:
-            self._client = http.client()
-        return self._client
-
     def find_stations(self, query: Query) -> list[str]:
         """Station ids with data inside the query's bbox and time range."""
         if query.bbox is None or query.time is None: