usdata 0.2.0__tar.gz → 0.2.1__tar.gz

{usdata-0.2.0 → usdata-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -102,11 +102,13 @@ just run search radar
 
 Integration tests that hit live services run with `just test-integration`.
 
-Releases are published to PyPI by tagging: create a GitHub release and the
-`publish.yml` workflow uploads via trusted publishing.
+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 [docs/architecture.md](docs/architecture.md) for how the pieces fit and
-[docs/adr/](docs/adr/) for why.
+See [docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[docs/adr/](docs/adr/) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
 
 ## License
 

{usdata-0.2.0 → usdata-0.2.1}/README.md

@@ -81,11 +81,13 @@ just run search radar
 
 Integration tests that hit live services run with `just test-integration`.
 
-Releases are published to PyPI by tagging: create a GitHub release and the
-`publish.yml` workflow uploads via trusted publishing.
+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 [docs/architecture.md](docs/architecture.md) for how the pieces fit and
-[docs/adr/](docs/adr/) for why.
+See [docs/architecture.md](docs/architecture.md) for how the pieces fit,
+[docs/adr/](docs/adr/) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
+a dataset.
 
 ## License
 

{usdata-0.2.0 → usdata-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.2.0"
+version = "0.2.1"
 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"
@@ -41,6 +41,7 @@ usdata = "usdata.cli:app"
 dev = [
     "pyright>=1.1.380",
     "pytest>=8.0",
+    "pytest-cov>=7.1.0",
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
@@ -66,7 +67,19 @@ select = [
     "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 = [

{usdata-0.2.0 → usdata-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.2.0"
+version = "0.2.1"
 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"
@@ -33,6 +33,7 @@ usdata = "usdata.cli:app"
 dev = [
     "pyright>=1.1.380",
     "pytest>=8.0",
+    "pytest-cov>=7.1.0",
     "respx>=0.23.1",
     "ruff>=0.6",
 ]
@@ -47,7 +48,16 @@ target-version = "py311"
 src = ["src", "tests"]
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+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"]

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/cache.py

@@ -12,6 +12,7 @@ ENV_VAR = "USDATA_CACHE_DIR"
 
 
 def cache_dir() -> Path:
+    """Cache root: $USDATA_CACHE_DIR, else $XDG_CACHE_HOME/usdata, else ~/.cache/usdata."""
     if override := os.environ.get(ENV_VAR):
         return Path(override).expanduser()
     xdg = os.environ.get("XDG_CACHE_HOME")
@@ -20,12 +21,14 @@ def cache_dir() -> Path:
 
 
 def asset_path(asset: Asset, root: Path | None = None) -> Path:
+    """Where an asset lives in the cache: <root>/<provider>/<dataset>/<asset id>."""
     provider, name = asset.dataset_id.split(":", 1)
     safe_id = asset.id.replace("/", "_")
     return (root or cache_dir()) / provider / name / safe_id
 
 
 def sha256_file(path: Path, chunk_size: int = 1 << 20) -> str:
+    """Hex sha256 of a file, prefixed 'sha256:' to match Asset.checksum."""
     h = hashlib.sha256()
     with path.open("rb") as f:
         while chunk := f.read(chunk_size):

usdata-0.2.1/src/usdata/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface. The Typer app lives in ``usdata.cli.app``."""
+
+from usdata.cli.app import app
+
+__all__ = ["app"]

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/cli/app.py

@@ -1,3 +1,5 @@
+"""Typer application: argument parsing and exit codes only; logic lives in the library."""
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -34,6 +36,7 @@ def main(
         typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
     ] = None,
 ) -> None:
+    """usdata: discover, fetch, and track provenance of U.S. public scientific data."""
     pass
 
 

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/fetch.py

@@ -13,10 +13,14 @@ from usdata.providers import load_adapter
 
 
 class ChecksumMismatch(RuntimeError):
+    """A fetched file's sha256 did not match the checksum the adapter declared."""
+
     pass
 
 
 class FetchedAsset(BaseModel):
+    """One asset on disk with its provenance and whether the cache satisfied it."""
+
     asset: Asset
     path: Path
     provenance: Provenance

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/manifest.py

@@ -26,6 +26,7 @@ class SourceSpec(BaseModel):
     params: dict[str, Any] = Field(default_factory=dict)
 
     def to_query(self) -> Query:
+        """Build the Query this source resolves to."""
         return build_query(
             location=self.location,
             bbox=self.bbox,
@@ -37,12 +38,15 @@ class SourceSpec(BaseModel):
 
 
 class Manifest(BaseModel):
+    """A declarative list of inputs a project needs: usdata pull fetches them."""
+
     name: str
     version: str = "1.0"
     sources: list[SourceSpec] = Field(min_length=1)
 
     @classmethod
     def load(cls, path: Path) -> Manifest:
+        """Parse a manifest YAML file."""
         return cls.model_validate(yaml.safe_load(path.read_text()) or {})
 
     def validate_against(self, registry: Registry | None = None) -> list[str]:
@@ -52,22 +56,29 @@ class Manifest(BaseModel):
 
 
 class LockedAsset(BaseModel):
+    """One resolved asset and the provenance of the copy that was fetched."""
+
     asset: Asset
     provenance: Provenance
 
 
 class Lockfile(BaseModel):
+    """Exactly what a manifest resolved to, with checksums, so it can be reproduced."""
+
     manifest: str
     generated_at: datetime
     assets: list[LockedAsset] = Field(default_factory=list)
 
     @classmethod
     def load(cls, path: Path) -> Lockfile:
+        """Read a lockfile written by ``save``."""
         return cls.model_validate_json(path.read_text())
 
     def save(self, path: Path) -> None:
+        """Write the lockfile as indented JSON."""
         path.write_text(self.model_dump_json(indent=2))
 
 
 def lockfile_path(manifest_path: Path) -> Path:
+    """The lockfile that pairs with a manifest: <manifest stem>.lock.json."""
     return manifest_path.with_suffix(".lock.json")

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/models.py

@@ -56,6 +56,7 @@ class BBox(BaseModel):
         )
 
     def intersects(self, other: BBox) -> bool:
+        """True if the boxes share any area, edges included."""
         return not (
             other.west > self.east
             or other.east < self.west
@@ -64,9 +65,11 @@ class BBox(BaseModel):
         )
 
     def contains_point(self, lat: float, lon: float) -> bool:
+        """True if the point lies inside or on the edge of the box."""
         return self.west <= lon <= self.east and self.south <= lat <= self.north
 
     def as_tuple(self) -> tuple[float, float, float, float]:
+        """The box as (west, south, east, north)."""
         return (self.west, self.south, self.east, self.north)
 
 
@@ -85,6 +88,7 @@ class TimeRange(BaseModel):
         return self
 
     def overlaps(self, other: TimeRange) -> bool:
+        """True if the ranges share any instant; open bounds match everything on that side."""
         starts_after = self.start is not None and other.end is not None and self.start > other.end
         ends_before = self.end is not None and other.start is not None and self.end < other.start
         return not (starts_after or ends_before)
@@ -125,6 +129,7 @@ class Dataset(BaseModel):
 
     @property
     def name(self) -> str:
+        """The dataset name without the provider prefix."""
         return self.id.split(":", 1)[1]
 
 

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/protocols/http.py

@@ -1,3 +1,5 @@
+"""Shared HTTP client configuration and streaming download."""
+
 from __future__ import annotations
 
 from pathlib import Path

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/protocols/s3.py

@@ -21,6 +21,8 @@ NS = "{http://s3.amazonaws.com/doc/2006-03-01/}"
 
 
 class S3Object(BaseModel):
+    """One key from a bucket listing."""
+
     key: str
     size: int
     etag: str | None = None
@@ -28,6 +30,7 @@ class S3Object(BaseModel):
 
 
 def parse_s3_url(url: str) -> tuple[str, str]:
+    """Split 's3://bucket/key' into (bucket, key)."""
     if not url.startswith("s3://"):
         raise ValueError(f"not an s3:// URL: {url}")
     bucket, _, key = url[5:].partition("/")
@@ -35,6 +38,7 @@ def parse_s3_url(url: str) -> tuple[str, str]:
 
 
 def https_url(bucket: str, key: str = "") -> str:
+    """The virtual-hosted HTTPS URL for a bucket key, with the key percent-encoded."""
     return f"https://{bucket}.s3.amazonaws.com/{quote(key)}"
 
 

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/provenance.py

@@ -27,14 +27,17 @@ def record(dataset: Dataset, asset: Asset, path: Path) -> Provenance:
 
 
 def sidecar_path(path: Path) -> Path:
+    """The provenance JSON file that sits beside a cached file."""
     return path.with_name(path.name + SIDECAR_SUFFIX)
 
 
 def write(prov: Provenance, path: Path) -> Path:
+    """Write a provenance record beside ``path`` and return the sidecar path."""
     out = sidecar_path(path)
     out.write_text(prov.model_dump_json(indent=2))
     return out
 
 
 def read(path: Path) -> Provenance:
+    """Load the provenance record stored beside ``path``."""
     return Provenance.model_validate_json(sidecar_path(path).read_text())

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/providers/base.py

@@ -1,3 +1,5 @@
+"""The Provider interface every dataset adapter implements, and how adapters are loaded."""
+
 from __future__ import annotations
 
 import importlib
@@ -31,6 +33,7 @@ class Provider(ABC):
 
 
 def load_adapter(dataset: Dataset) -> Provider:
+    """Instantiate the Provider named by a dataset's ``adapter`` dotted path."""
     module_name, _, class_name = dataset.adapter.partition(":")
     module = importlib.import_module(module_name)
     cls = getattr(module, class_name)

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/providers/noaa/coastwatch.py

@@ -9,8 +9,12 @@ from usdata.providers.base import NotImplementedProvider, Provider
 
 
 class CoastwatchSst(Provider):
+    """Placeholder adapter; see issue #5."""
+
     def list_assets(self, query: Query) -> list[Asset]:
+        """Not implemented yet."""
         raise NotImplementedProvider(f"{self.dataset.id} adapter is not implemented yet")
 
     def fetch(self, asset: Asset, dest: Path) -> Path:
+        """Not implemented yet."""
         raise NotImplementedProvider(f"{self.dataset.id} adapter is not implemented yet")

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/providers/noaa/ghcnd.py

@@ -39,6 +39,8 @@ def _stations_param(raw: Any) -> list[str]:
 
 
 class GhcnDaily(Provider):
+    """GHCN-Daily adapter. Params: ``stations`` (list or comma string), ``units``."""
+
     def __init__(self, dataset: Dataset, client: httpx.Client | None = None) -> None:
         super().__init__(dataset)
         self._client = client
@@ -83,6 +85,7 @@ class GhcnDaily(Provider):
         return found
 
     def list_assets(self, query: Query) -> list[Asset]:
+        """One CSV asset per chunk of up to STATIONS_PER_ASSET stations for the query window."""
         if query.time is None or query.time.start is None or query.time.end is None:
             raise QueryError(f"{self.dataset.id} requires both start and end dates")
         if "stations" in query.params:
@@ -125,4 +128,5 @@ class GhcnDaily(Provider):
         return assets
 
     def fetch(self, asset: Asset, dest: Path) -> Path:
+        """Stream the CSV response to ``dest``."""
         return http.download(asset.href, dest, self._http())

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/providers/noaa/nexrad.py

@@ -42,6 +42,8 @@ def scan_time(key: str) -> datetime | None:
 
 
 class NexradLevel2(Provider):
+    """NEXRAD Level II adapter. Params: ``site``/``sites`` (ICAO ids), ``nearest`` (int)."""
+
     def __init__(self, dataset: Dataset, client: httpx.Client | None = None) -> None:
         super().__init__(dataset)
         self._client = client
@@ -52,6 +54,7 @@ class NexradLevel2(Provider):
         return self._client
 
     def select_sites(self, query: Query) -> list[str]:
+        """Radar site ids the query refers to; see the module docstring for the rules."""
         raw = query.params.get("sites", query.params.get("site"))
         if raw is not None:
             ids = _sites_param(raw)
@@ -70,6 +73,7 @@ class NexradLevel2(Provider):
         return [s.id for s in sites.nearest(lat, lon, 1)]
 
     def list_assets(self, query: Query) -> list[Asset]:
+        """Every volume scan for the selected sites inside the query's UTC time window."""
         if query.time is None or query.time.start is None or query.time.end is None:
             raise QueryError(f"{self.dataset.id} requires both start and end times")
         start = query.time.start.astimezone(UTC)
@@ -99,4 +103,5 @@ class NexradLevel2(Provider):
         return assets
 
     def fetch(self, asset: Asset, dest: Path) -> Path:
+        """Download one scan object anonymously to ``dest``."""
         return s3.download(asset.href, dest, self._http())

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/providers/noaa/sites.py

@@ -15,6 +15,8 @@ EARTH_RADIUS_KM = 6371.0
 
 
 class RadarSite(BaseModel):
+    """A radar site from the bundled table. ``type`` is NEXRAD, TDWR, or TEST."""
+
     model_config = ConfigDict(frozen=True)
 
     id: str
@@ -26,6 +28,7 @@ class RadarSite(BaseModel):
     type: str
 
     def distance_km(self, lat: float, lon: float) -> float:
+        """Great-circle distance from this site to a point, in kilometres."""
         p1, p2 = math.radians(self.lat), math.radians(lat)
         dphi = p2 - p1
         dlam = math.radians(lon - self.lon)
@@ -35,6 +38,7 @@ class RadarSite(BaseModel):
 
 @lru_cache(maxsize=1)
 def all_sites() -> dict[str, RadarSite]:
+    """The bundled site table keyed by ICAO id."""
     text = (resources.files("usdata.data") / "nexrad_sites.csv").read_text()
     sites = {}
     for row in csv.DictReader(text.splitlines()):
@@ -45,6 +49,7 @@ def all_sites() -> dict[str, RadarSite]:
 
 
 def get_site(site_id: str) -> RadarSite:
+    """Look up a site by ICAO id, case-insensitively."""
     try:
         return all_sites()[site_id.upper()]
     except KeyError:
@@ -52,6 +57,7 @@ def get_site(site_id: str) -> RadarSite:
 
 
 def sites_in(bbox: BBox, *, types: tuple[str, ...] = ("NEXRAD",)) -> list[RadarSite]:
+    """Sites of the given types whose location lies inside ``bbox``, sorted by id."""
     return sorted(
         (s for s in all_sites().values() if s.type in types and bbox.contains_point(s.lat, s.lon)),
         key=lambda s: s.id,
@@ -61,5 +67,6 @@ def sites_in(bbox: BBox, *, types: tuple[str, ...] = ("NEXRAD",)) -> list[RadarS
 def nearest(
     lat: float, lon: float, n: int = 1, *, types: tuple[str, ...] = ("NEXRAD",)
 ) -> list[RadarSite]:
+    """The ``n`` closest sites of the given types to a point, nearest first."""
     candidates = [s for s in all_sites().values() if s.type in types]
     return sorted(candidates, key=lambda s: s.distance_km(lat, lon))[:n]

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/query.py

@@ -13,6 +13,8 @@ from usdata.models import BBox, Query, TimeRange
 
 
 class UnknownPlace(ValueError):
+    """A place name that is not in the bundled place table."""
+
     pass
 
 

{usdata-0.2.0 → usdata-0.2.1}/src/usdata/registry.py

@@ -21,10 +21,14 @@ _TOKEN = re.compile(r"[a-z0-9]+")
 
 
 class DatasetNotFound(KeyError):
+    """No registry entry has the requested id."""
+
     pass
 
 
 class SearchResult(BaseModel):
+    """A dataset and its keyword-match score."""
+
     model_config = ConfigDict(frozen=True)
 
     dataset: Dataset
@@ -56,6 +60,8 @@ def _score(dataset: Dataset, terms: set[str]) -> float:
 
 
 class Registry:
+    """An in-memory collection of datasets addressable by id and searchable by keyword."""
+
     def __init__(self, datasets: Iterable[Dataset]) -> None:
         self._by_id: dict[str, Dataset] = {}
         for ds in datasets:
@@ -65,11 +71,13 @@ class Registry:
 
     @classmethod
     def from_yaml(cls, path: Path) -> Registry:
+        """Load a registry from a YAML file with a top-level ``datasets`` list."""
         raw = yaml.safe_load(path.read_text()) or {}
         return cls(Dataset.model_validate(d) for d in raw.get("datasets", []))
 
     @classmethod
     def bundled(cls) -> Registry:
+        """The registry shipped inside the package."""
         with resources.as_file(resources.files("usdata.data") / "registry.yaml") as p:
             return cls.from_yaml(p)
 
@@ -83,12 +91,14 @@ class Registry:
         return dataset_id in self._by_id
 
     def get(self, dataset_id: str) -> Dataset:
+        """Return the dataset with this id or raise DatasetNotFound."""
         try:
             return self._by_id[dataset_id]
         except KeyError:
             raise DatasetNotFound(dataset_id) from None
 
     def providers(self) -> set[str]:
+        """The set of provider names present in the registry."""
         return {ds.provider for ds in self}
 
     def search(self, query: Query) -> list[SearchResult]:
@@ -111,4 +121,5 @@ class Registry:
 
 @lru_cache(maxsize=1)
 def default_registry() -> Registry:
+    """The bundled registry, loaded once per process."""
     return Registry.bundled()

usdata-0.2.0/src/usdata/cli/__init__.py

@@ -1,3 +0,0 @@
-from usdata.cli.app import app
-
-__all__ = ["app"]