usdata 0.23.0__tar.gz → 0.24.0__tar.gz

{usdata-0.23.0 → usdata-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usdata
-Version: 0.23.0
+Version: 0.24.0
 Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
 Keywords: noaa,usgs,open-data,scientific-data,provenance,reproducible-research,weather,climate,meteorology
 Author: Jake Van Slyke
@@ -112,7 +112,7 @@ breaking changes.
 | [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
 | [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
 
-Twenty-five datasets are available today and twenty more are planned, grouped
+Twenty-six datasets are available today and twenty more are planned, grouped
 by agency and product family in the [catalog](docs/providers/README.md).
 
 ## How this compares

{usdata-0.23.0 → usdata-0.24.0}/README.md

@@ -67,7 +67,7 @@ breaking changes.
 | [docs.usdata.dev](https://docs.usdata.dev/) | How to use it: [install](https://docs.usdata.dev/install/), [getting started](https://docs.usdata.dev/getting-started/), guides, dataset notes, and reference |
 | [Severe-weather case study](https://usdata.dev/examples/severe-weather-case-study/) | One tornado, six sources, one manifest and lockfile, ending in a citation |
 
-Twenty-five datasets are available today and twenty more are planned, grouped
+Twenty-six datasets are available today and twenty more are planned, grouped
 by agency and product family in the [catalog](docs/providers/README.md).
 
 ## How this compares

{usdata-0.23.0 → usdata-0.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.23.0"
+version = "0.24.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.23.0 → usdata-0.24.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usdata"
-version = "0.23.0"
+version = "0.24.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.23.0 → usdata-0.24.0}/src/usdata/data/registry.yaml

@@ -641,6 +641,47 @@ datasets:
     limits: { max_window: P366D }
     adapter: usdata.providers.noaa.coops:CoopsTidePredictions
 
+  - id: noaa:coops-currents
+    provider: noaa
+    status: available
+    system: noaa:coops
+    domain: ocean-physics
+    since: "0.24"
+    title: CO-OPS Observed Currents
+    description: >-
+      Native six-minute current speed and direction from the anonymous CO-OPS
+      Data API. Select one alphanumeric station, a positive bin, units, and a
+      UTC interval of at most 28 days. Raw CSV preserves gaps and blank values.
+      Bin depths can change between deployments; the CSV carries bin number,
+      not depth or a verification-quality flag. Predictions, all-bin queries,
+      station discovery, and resampling are not included.
+    keywords: [currents, current speed, current direction, coastal, ocean, coops, ports, stations, bin]
+    protocol: http
+    homepage: https://api.tidesandcurrents.noaa.gov/api/prod/
+    license: US Government Work (public domain)
+    capabilities: { spatial_subset: false, temporal_subset: true, variable_subset: false }
+    summary: Coastal current speed and direction
+    formats: [CSV]
+    selection: Native six-minute observations for one station and explicit bin; at most 28 days
+    inputs: Alphanumeric station, positive bin, and both minute-aligned timestamps
+    reader: pandas
+    guide: docs/providers/noaa-coops-currents.md
+    examples:
+      - examples/coastal-currents/example.ipynb
+    resolution:
+      spatial: One current-meter station and bin per request; bin depths depend on deployment
+      temporal: Six-minute observations
+    citation: >-
+      NOAA National Ocean Service, CO-OPS observed currents, accessed via usdata
+    terms: https://tidesandcurrents.noaa.gov/disclaimers.html
+    variables:
+      - { name: "Date Time", units: "UTC", description: "Observation time, requested with time_zone=gmt" }
+      - { name: "Speed", units: "cm/s", description: "Observed current speed in metric units; knots with english units" }
+      - { name: "Direction", units: "degrees", description: "Observed current direction" }
+      - { name: "Bin", description: "Requested bin number, not a depth measurement" }
+    limits: { max_window: P28D }
+    adapter: usdata.providers.noaa.coops:CoopsCurrents
+
   - id: noaa:gsom
     provider: noaa
     status: available

{usdata-0.23.0 → usdata-0.24.0}/src/usdata/providers/noaa/coops.py

@@ -1,17 +1,21 @@
-"""CO-OPS observed water levels and tide predictions as raw CSV.
+"""CO-OPS observed water levels, currents, and tide predictions as raw CSV.
 
-Both datasets share one station model: one seven-digit ``station``, an explicit
+Water levels and tide predictions share one station model: one seven-digit ``station``, an explicit
 ``datum``, optional ``units`` (metric or english), and both timestamps at minute
 precision, requested in UTC; a bare end date means 23:59 on that day.
 Observations span at most 28 days; predictions
 span at most a year on any ``interval`` (six-minute by default, another minute
 step, hourly, or high/low), within NOAA's own limits.
+Currents instead name an alphanumeric station and explicit positive bin, with
+no datum or interval selector. Their native six-minute observations share the
+28-day window and use cm/s (metric) or knots (english).
 """
 
 from __future__ import annotations
 
 import csv
 import hashlib
+import math
 from collections.abc import Iterator
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
@@ -25,7 +29,7 @@ from usdata.models import Asset, Protocol, Query, TimeRange
 from usdata.protocols import http
 from usdata.providers.base import QueryError
 from usdata.providers.http import HttpProvider
-from usdata.providers.params import choice
+from usdata.providers.params import choice, positive_int
 from usdata.query import LAST_INSTANT
 
 DATA_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
@@ -44,6 +48,7 @@ OBSERVATION_COLUMNS = {
     "Quality",
 }
 PREDICTION_COLUMNS = {"Date Time", "Prediction"}
+CURRENTS_COLUMNS = {"Date Time", "Speed", "Direction", "Bin"}
 
 
 def _rows(path: Path, asset: Asset, required: set[str]) -> Iterator[dict[str, str]]:
@@ -150,6 +155,29 @@ class CoopsPredictionParams(CoopsParams):
         return token
 
 
+class CoopsCurrentsParams(BaseModel):
+    """One current-meter station and bin; a bin is not a permanent depth."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    station: str = Field(
+        description="Required alphanumeric CO-OPS currents station id, for example 'cb0102'."
+    )
+    bin: Annotated[int, positive_int()] = Field(
+        description="Required positive bin number; 0 (all bins) is not supported."
+    )
+    units: Annotated[str, choice("metric", "english")] = Field(
+        default="metric", description="metric (default, cm/s) or english (knots)."
+    )
+
+    @field_validator("station", mode="before")
+    @classmethod
+    def _one_station_id(cls, value: object) -> object:
+        if not isinstance(value, str) or not value.isascii() or not value.isalnum():
+            raise ValueError("must be an alphanumeric string, for example 'cb0102'")
+        return value
+
+
 class _CoopsStation(HttpProvider):
     """Shared window, request, and validation rules for CO-OPS station products."""
 
@@ -255,3 +283,38 @@ class CoopsTidePredictions(_CoopsStation):
     def _validate(self, path: Path, asset: Asset) -> None:
         interval = httpx.URL(asset.href).params.get("interval", "6")
         _validate_predictions(path, asset, interval)
+
+
+class CoopsCurrents(_CoopsStation):
+    """One station's observed current speed and direction at an explicit bin."""
+
+    product = "currents"
+    label = "current"
+    params_model = CoopsCurrentsParams
+
+    def list_assets(self, query: Query) -> list[Asset]:
+        """Describe one native-interval CSV request; check availability on fetch."""
+        params = self.parse_params(query, CoopsCurrentsParams)
+        self.reject(query, "bbox", "text", "variables", hint="CO-OPS requires an explicit station")
+        start, end = self._window(query, MAX_INTERVAL)
+        request = {"bin": str(params.bin), "units": params.units}
+        return [self._asset(params.station, start, end, request)]
+
+    def _validate(self, path: Path, asset: Asset) -> None:
+        expected_bin = int(httpx.URL(asset.href).params["bin"])
+        count = 0
+        for row in _rows(path, asset, CURRENTS_COLUMNS):
+            token = row["Bin"]
+            if not token.isascii() or not token.isdigit() or int(token) != expected_bin:
+                raise ValueError("record does not match the requested bin")
+            # Preserve blank measurements and missing timestamps, not invented values.
+            for field in ("Speed", "Direction"):
+                if row[field]:
+                    value = float(row[field])
+                    if not math.isfinite(value) or value < 0:
+                        raise ValueError(f"invalid current {field.lower()}")
+                    if field == "Direction" and value > 360:
+                        raise ValueError("current direction must be between 0 and 360 degrees")
+            count += 1
+        if not count:
+            raise ValueError("no current observations returned")