insitukit 0.1.0__py3-none-any.whl

insitukit/__init__.py

@@ -0,0 +1,24 @@
+"""Fetch, summarise and publish in situ ocean observations.
+
+- ``insitukit.coops``: NOAA CO-OPS (Tides and Currents) observations, tide predictions and station metadata.
+- ``insitukit.erddap``: a paced, budgeted ERDDAP tabledap client for any server.
+- ``insitukit.stats``: daily means with a coverage rule, exceedance, joint histograms, marine heatwave climatology.
+- ``insitukit.series``: the compact JSON form of a regular time series, and back.
+- ``insitukit.store``: where the JSON goes (a directory, Cloudflare Workers KV or Google Cloud Storage), behind a
+  guard on object names and sizes.
+
+Call ``identify`` once at start-up so every request names your application and a contact.
+"""
+
+__version__ = "0.1.0"
+
+
+def identify(user_agent: str, application: str | None = None) -> None:
+    """Name the caller on every request: ``user_agent`` as the HTTP User-Agent (include a URL or an address a data
+    provider can reach you at), and ``application`` as CO-OPS's ``application`` parameter (default: unchanged)."""
+    from . import coops
+
+    coops.USER_AGENT = user_agent
+    coops._session.headers["User-Agent"] = user_agent
+    if application is not None:
+        coops.APPLICATION = application

insitukit/coops.py

@@ -0,0 +1,198 @@
+"""Fetch observations and tide predictions from the NOAA CO-OPS data API (Tides and Currents).
+
+Every request asks for metric units and GMT; converting to other units is the caller's. The API answers HTTP 200 with an ``{"error": ...}`` body for a bad request, and "No data
+was found" when a station lacks the sensor or the window falls in a gap: that is an empty result,
+not a failure. Server errors and timeouts retry with backoff.
+
+Per-request range limits (checked against the live API, 2026-10):
+
+- 6-minute observations (``water_temperature``, ``air_temperature``, ``wind``, ``air_pressure``,
+  ``water_level``): 31 days. We ask for 30-day spans.
+- the same products with ``interval=h`` (the reading at the top of each hour), and ``hourly_height``:
+  365 days, compared by calendar date, so one calendar year (including a leap year) fits one request.
+
+Requests carry ``USER_AGENT`` and ``APPLICATION``; set your own with ``insitukit.identify``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timedelta, timezone
+
+import numpy as np
+import pandas as pd
+import requests
+
+from . import __version__
+
+BASE_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
+META_URL = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/{station}.json"
+USER_AGENT = f"insitukit/{__version__} (+https://github.com/lhzn-io/insitukit)"
+APPLICATION = "insitukit"
+SIX_MINUTE_SPAN = timedelta(days=30)
+# Value fields per product, renamed to the column names returned by fetch().
+FIELDS = {
+    "wind": {"s": "wind_speed", "d": "wind_direction", "g": "wind_gust"},
+}
+DATUM_PRODUCTS = {"water_level", "hourly_height", "high_low", "predictions"}
+
+# The API sits behind a gateway that answers 403 "Forbidden" (not 429) once a client sends too many
+# requests in a short period; a burst of about 300 requests in 10 minutes was enough. We pace every
+# request and treat 403 and 429 as throttling, retried with backoff like a server error.
+MIN_INTERVAL = 1.0
+THROTTLED = {403, 429}
+
+log = logging.getLogger(__name__)
+_session = requests.Session()
+_session.headers["User-Agent"] = USER_AGENT
+_last_request = 0.0
+# Requests sent since import (or since the caller reset it); used for logging and cost checks.
+request_count = 0
+
+
+class CoopsError(RuntimeError):
+    """The API rejected the request (bad station, product or date range)."""
+
+
+def _pace() -> None:
+    """Keep at least MIN_INTERVAL seconds between requests."""
+    global _last_request
+    wait = _last_request + MIN_INTERVAL - time.monotonic()
+    if wait > 0:
+        time.sleep(wait)
+    _last_request = time.monotonic()
+
+
+def _get(params: dict, retries: int = 4, timeout: int = 120) -> dict | None:
+    """GET the data API with retries; return None when the API reports no data for the window."""
+    global request_count
+    query = {"units": "metric", "time_zone": "gmt", "format": "json", "application": APPLICATION, **params}
+    delay = 5.0
+    for attempt in range(1, retries + 1):
+        request_count += 1
+        _pace()
+        try:
+            resp = _session.get(BASE_URL, params=query, timeout=timeout)
+        except requests.RequestException as exc:
+            log.warning("request failed (%s), attempt %d: %s", exc.__class__.__name__, attempt, params)
+        else:
+            if resp.status_code == 200:
+                body = resp.json()
+                err = (body.get("error") or {}).get("message") if isinstance(body, dict) else None
+                if err is None:
+                    return body
+                if "no data was found" in err.lower():
+                    return None
+                raise CoopsError(f"{err.strip()} ({params})")
+            if resp.status_code < 500 and resp.status_code not in THROTTLED:
+                raise CoopsError(f"HTTP {resp.status_code} ({params})")
+            log.warning("HTTP %d, attempt %d: %s", resp.status_code, attempt, params)
+        if attempt < retries:
+            time.sleep(delay)
+            delay *= 2
+    raise RuntimeError(f"giving up after {retries} attempts: {params}")
+
+
+def _stamp(ts: datetime) -> str:
+    return ts.astimezone(timezone.utc).strftime("%Y%m%d %H:%M")
+
+
+def spans(start: datetime, end: datetime, hourly: bool) -> list[tuple[datetime, datetime]]:
+    """Request windows covering ``[start, end)``: calendar years for hourly data, 30 days otherwise."""
+    out = []
+    lo = start
+    while lo < end:
+        if hourly:
+            hi = min(datetime(lo.year + 1, 1, 1, tzinfo=timezone.utc), end)
+        else:
+            hi = min(lo + SIX_MINUTE_SPAN, end)
+        out.append((lo, hi))
+        lo = hi
+    return out
+
+
+def fetch(
+    product: str,
+    station: str,
+    start: datetime,
+    end: datetime,
+    interval: str | None = None,
+    datum: str = "MLLW",
+) -> pd.DataFrame:
+    """Observations for ``start <= time < end`` with a UTC ``time`` column and float value columns.
+
+    Single-value products return one column named after the product; ``wind`` returns
+    ``wind_speed`` (m/s), ``wind_direction`` (degrees true) and ``wind_gust`` (m/s). Readings the
+    API flags as missing come back as NaN. Long windows are split to respect the range limits.
+    """
+    fields = FIELDS.get(product, {"v": product})
+    hourly = interval == "h" or product == "hourly_height"
+    frames = []
+    for lo, hi in spans(start, end, hourly):
+        # The API's end_date is inclusive; stop one minute short so adjacent spans do not overlap.
+        params = {"product": product, "station": station, "begin_date": _stamp(lo), "end_date": _stamp(hi - timedelta(minutes=1))}
+        if interval:
+            params["interval"] = interval
+        if product in DATUM_PRODUCTS:
+            params["datum"] = datum
+        body = _get(params)
+        rows = (body or {}).get("data") or []
+        log.info("%s %s %s..%s: %d rows", station, product, params["begin_date"], params["end_date"], len(rows))
+        if rows:
+            frames.append(pd.DataFrame(rows))
+    cols = ["time", *fields.values()]
+    if not frames:
+        return pd.DataFrame({c: pd.Series(dtype="datetime64[ns, UTC]" if c == "time" else float) for c in cols})
+    raw = pd.concat(frames, ignore_index=True)
+    df = pd.DataFrame({"time": pd.to_datetime(raw["t"], utc=True)})
+    for key, name in fields.items():
+        df[name] = pd.to_numeric(raw[key], errors="coerce") if key in raw.columns else np.nan
+    df = df[(df["time"] >= pd.Timestamp(start)) & (df["time"] < pd.Timestamp(end))]
+    return df.sort_values("time").drop_duplicates("time").reset_index(drop=True)
+
+
+def tide_events(station: str, start: datetime, end: datetime, datum: str = "MLLW") -> list[dict]:
+    """High and low tide predictions in ``[start, end)``: ``[{"time": Timestamp, "m": float, "type": "H"|"L"}]``."""
+    params = {
+        "product": "predictions",
+        "station": station,
+        "begin_date": _stamp(start),
+        "end_date": _stamp(end - timedelta(minutes=1)),
+        "interval": "hilo",
+        "datum": datum,
+    }
+    body = _get(params) or {}
+    out = []
+    for row in body.get("predictions") or []:
+        try:
+            out.append({"time": pd.Timestamp(row["t"], tz="UTC"), "m": float(row["v"]), "type": row["type"]})
+        except (KeyError, TypeError, ValueError):
+            continue
+    return out
+
+
+def predictions(station: str, start: datetime, end: datetime, datum: str = "MLLW") -> pd.Series:
+    """6-minute tide predictions (m above ``datum``) in ``[start, end)``, indexed by UTC time. A station's own
+    predictions taken from its observed water level give the surge without the phase shift of a nearby station's."""
+    vals: dict[pd.Timestamp, float] = {}
+    for lo, hi in spans(start, end, hourly=False):
+        body = _get({"product": "predictions", "station": station, "datum": datum, "interval": "6",
+                     "begin_date": _stamp(lo), "end_date": _stamp(hi - timedelta(minutes=1))}) or {}
+        for row in body.get("predictions") or []:
+            try:
+                vals[pd.Timestamp(row["t"], tz="UTC")] = float(row["v"])
+            except (KeyError, TypeError, ValueError):
+                continue
+    s = pd.Series(vals, dtype=float).sort_index()
+    return s[(s.index >= pd.Timestamp(start)) & (s.index < pd.Timestamp(end))]
+
+
+def metadata(station: str) -> dict:
+    """Station metadata with details and sensors (name, lat, lng, established, sensor list)."""
+    global request_count
+    request_count += 1
+    _pace()
+    resp = _session.get(META_URL.format(station=station), params={"expand": "details,sensors"}, timeout=60)
+    resp.raise_for_status()
+    return resp.json()["stations"][0]

insitukit/erddap.py

@@ -0,0 +1,107 @@
+"""A small ERDDAP tabledap client.
+
+Requests run one at a time, at least ``min_interval`` apart; each attempt counts against a per-run budget; a 503 or
+429 with Retry-After is waited out; and a 404 whose body says "no matching results" is an empty window, not a missing
+dataset. After a run of failed connections the server is marked unreachable and later requests fail at once. The
+state lives on the instance, so two servers never share a budget or an unreachable flag.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import time
+from datetime import datetime, timezone
+
+import pandas as pd
+import requests
+
+from . import coops
+
+log = logging.getLogger(__name__)
+
+NERACOOS_URL = "https://data.neracoos.org/erddap"
+
+
+class Unreachable(RuntimeError):
+    """The server did not accept a connection on any retry earlier in this run."""
+
+
+class BudgetExceeded(RuntimeError):
+    """This run has made as many requests to the server as its budget allows."""
+
+
+class Erddap:
+    """One ERDDAP server. ``user_agent`` defaults to the one set with ``insitukit.identify``."""
+
+    def __init__(self, base_url: str, budget: int = 60, min_interval: float = 1.0, connect_timeout: int = 10,
+                 user_agent: str | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.budget = budget
+        self.min_interval = min_interval
+        self.connect_timeout = connect_timeout
+        self.requests = 0
+        self.bytes = 0
+        self.unreachable: str | None = None
+        self._last_start = 0.0
+        self._session = requests.Session()
+        self._session.headers["User-Agent"] = user_agent or coops.USER_AGENT
+
+    def summary(self) -> str:
+        return f"{self.base_url}: {self.requests} requests of a budget of {self.budget}, {self.bytes / 1e6:.1f} MB"
+
+    def _get(self, url: str, retries: int = 3, timeout: int = 90) -> requests.Response | None:
+        if self.unreachable:
+            raise Unreachable(f"{self.base_url} unreachable since {self.unreachable}; not tried: {url}")
+        delay = 5.0
+        connect_failures = 0
+        for attempt in range(1, retries + 1):
+            if self.requests >= self.budget:
+                raise BudgetExceeded(f"{self.requests} requests reached this run's budget; not sent: {url}")
+            wait = self._last_start + self.min_interval - time.monotonic()
+            if wait > 0:
+                time.sleep(wait)
+            self._last_start = time.monotonic()
+            self.requests += 1
+            try:
+                resp = self._session.get(url, timeout=(self.connect_timeout, timeout))
+            except requests.RequestException as exc:
+                if isinstance(exc, (requests.ConnectTimeout, requests.ConnectionError)) and not isinstance(exc, requests.ReadTimeout):
+                    connect_failures += 1
+                log.warning("request failed (%s), attempt %d: %s", exc.__class__.__name__, attempt, url)
+            else:
+                self.bytes += len(resp.content)
+                if resp.status_code == 200:
+                    return resp
+                if resp.status_code == 404 and "no matching results" in resp.text.lower():
+                    return None
+                log.warning("HTTP %d, attempt %d: %s", resp.status_code, attempt, url)
+                if resp.status_code == 404:
+                    raise RuntimeError(f"dataset not found: {url}")
+                if resp.status_code in (429, 503):
+                    try:
+                        delay = max(delay, min(60.0, float(resp.headers.get("Retry-After", ""))))
+                    except ValueError:
+                        pass
+            if attempt < retries:
+                time.sleep(delay)
+                delay *= 2
+        if connect_failures == retries:
+            self.unreachable = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+            raise Unreachable(f"no connection after {retries} attempts: {url}")
+        raise RuntimeError(f"giving up after {retries} attempts: {url}")
+
+    def fetch(self, dataset_id: str, start: datetime, end: datetime, columns: list[str]) -> pd.DataFrame:
+        """Rows for ``start <= time < end``: a UTC ``time`` column and the requested columns (floats where numeric).
+        Only the named columns are asked for (no ``depth`` unless listed: many datasets have none)."""
+        stamp = lambda ts: ts.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")  # noqa: E731
+        query = ",".join(["time", *columns])
+        url = f"{self.base_url}/tabledap/{dataset_id}.csv?{query}&time%3E={stamp(start)}&time%3C{stamp(end)}"
+        resp = self._get(url)
+        if resp is None:
+            return pd.DataFrame({c: pd.Series(dtype="datetime64[ns, UTC]" if c == "time" else float) for c in ["time", *columns]})
+        df = pd.read_csv(io.StringIO(resp.text), skiprows=[1])  # row 2 of an ERDDAP CSV holds units
+        df["time"] = pd.to_datetime(df["time"], utc=True)
+        for c in columns:
+            df[c] = pd.to_numeric(df[c], errors="coerce")
+        return df

insitukit/series.py

@@ -0,0 +1,78 @@
+"""The compact JSON form of a regular time series.
+
+One series::
+
+    {"t0": "2026-10-01T00:00:00Z", "step": 3600, "unit": "m", "values": [0.41, 0.44, null, 0.52]}
+
+Several series on one grid (a frame)::
+
+    {"t0": "2026-10-01T00:00:00Z", "step": 3600, "wind_kt": [8.1, 9.4], "dir_deg": [215.0, 220.0]}
+
+``t0`` is the first value's time in UTC, ``step`` the spacing in seconds, and a missing value is ``null``. The grid
+runs without a break from the first value to the last, so a reader rebuilds every time from ``t0``, ``step`` and the
+position alone. An empty series has ``t0`` null. Values are rounded on the way out, which with the implicit times
+keeps a year of hourly data to a few tens of kilobytes.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+
+
+def iso(ts: datetime | pd.Timestamp) -> str:
+    """A time as ``YYYY-MM-DDTHH:MM:SSZ`` in UTC."""
+    return pd.Timestamp(ts).tz_convert("UTC").strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _grid(index: pd.DatetimeIndex, step: int) -> pd.DatetimeIndex:
+    return pd.date_range(index[0], index[-1], freq=f"{step}s")
+
+
+def _rounded(values, places: int) -> list[float | None]:
+    return [None if pd.isna(v) else round(float(v), places) for v in values]
+
+
+def encode(s: pd.Series, unit: str, places: int, step: int = 3600) -> dict:
+    """A series on a UTC grid of ``step`` seconds (indexed on that grid already, gaps allowed) as JSON."""
+    s = s.dropna()
+    if s.empty:
+        return {"t0": None, "step": step, "unit": unit, "values": []}
+    full = s.reindex(_grid(s.index, step))
+    return {"t0": iso(full.index[0]), "step": step, "unit": unit, "values": _rounded(full, places)}
+
+
+def decode(obj: dict | None) -> pd.Series:
+    """The values of an encoded series that are present, indexed by UTC time."""
+    if not obj or not obj.get("t0") or not obj.get("values"):
+        return pd.Series(dtype=float, index=pd.DatetimeIndex([], tz="UTC"))
+    idx = pd.date_range(pd.Timestamp(obj["t0"]), periods=len(obj["values"]), freq=f"{obj.get('step', 3600)}s")
+    return pd.Series([np.nan if v is None else v for v in obj["values"]], index=idx, dtype=float).dropna()
+
+
+def encode_frame(frame: pd.DataFrame, places: dict[str, int] | int = 1, step: int = 3600) -> dict:
+    """Columns on one UTC grid of ``step`` seconds as JSON, each rounded to ``places`` (one number, or per column
+    with 1 for any not named)."""
+    frame = frame.dropna(how="all")
+    if frame.empty:
+        return {"t0": None, "step": step}
+    full = frame.reindex(_grid(frame.index, step))
+    out: dict = {"t0": iso(full.index[0]), "step": step}
+    for col in full.columns:
+        p = places if isinstance(places, int) else places.get(col, 1)
+        out[col] = _rounded(full[col], p)
+    return out
+
+
+def decode_frame(obj: dict | None, skip: tuple[str, ...] = ()) -> pd.DataFrame:
+    """The rows of an encoded frame with any value present. Every list is a column except those named in ``skip``
+    (lists a writer added beside the columns, such as indices of flagged values)."""
+    if not obj or not obj.get("t0"):
+        return pd.DataFrame(index=pd.DatetimeIndex([], tz="UTC"), dtype=float)
+    cols = [k for k, v in obj.items() if isinstance(v, list) and k not in skip]
+    if not cols:
+        return pd.DataFrame(index=pd.DatetimeIndex([], tz="UTC"), dtype=float)
+    idx = pd.date_range(pd.Timestamp(obj["t0"]), periods=len(obj[cols[0]]), freq=f"{obj.get('step', 3600)}s")
+    return pd.DataFrame({c: pd.to_numeric(pd.Series(obj[c], index=idx), errors="coerce") for c in cols}).dropna(how="all")

insitukit/stats.py

@@ -0,0 +1,77 @@
+"""Summaries of a long record: daily means with a coverage rule, exceedance, a joint histogram of two series measured
+at nearly the same times, and a marine heatwave climatology as Hobday et al. (2016) build theirs
+(doi:10.1016/j.pocean.2015.12.014).
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import pandas as pd
+
+
+def day_means(s: pd.Series, per_day: int, digits: int, how: str = "mean", tz: str = "UTC") -> pd.Series:
+    """Daily means (or another resampler such as ``"max"``) in ``tz`` of a series indexed by aware times, kept only for
+    a day with at least half its ``per_day`` records."""
+    s = s.dropna()
+    s.index = s.index.tz_convert(tz)
+    g = s.resample("D")
+    out = getattr(g, how)().where(g.count() >= per_day / 2)
+    return out.round(digits)
+
+
+def exceedance(values, xs: list[float]) -> list[float | None]:
+    """The share of the finite values above each x (to 4 decimals); None for each x when there are none."""
+    v = np.asarray(values, dtype=float)
+    v = v[np.isfinite(v)]
+    return [round(float((v > x).mean()), 4) if v.size else None for x in xs]
+
+
+def joint(a: pd.Series, b: pd.Series, a_edges: list[float], b_edges: list[float], pair_s: int) -> list[list[int]]:
+    """Counts of ``a`` by its bins (rows) against ``b`` at the nearest time within ``pair_s`` seconds (columns).
+    Bins are ``[edge, next edge)``; the last is open, and a value below the first edge counts in the first."""
+    counts = np.zeros((len(a_edges), len(b_edges)), dtype=int)
+    if a.empty or b.empty:
+        return counts.tolist()
+    left = pd.DataFrame({"a": a}).sort_index()
+    right = pd.DataFrame({"b": b}).sort_index()
+    m = pd.merge_asof(left, right, left_index=True, right_index=True, direction="nearest",
+                      tolerance=pd.Timedelta(seconds=pair_s)).dropna()
+    i = np.clip(np.searchsorted(a_edges, m["a"].to_numpy(), side="right") - 1, 0, len(a_edges) - 1)
+    j = np.clip(np.searchsorted(b_edges, m["b"].to_numpy(), side="right") - 1, 0, len(b_edges) - 1)
+    np.add.at(counts, (i, j), 1)
+    return counts.tolist()
+
+
+def climatology(days: pd.Series, window: int = 5, smooth: int = 31) -> dict:
+    """A day-of-year climatology from daily means indexed by date: for each day, every daily mean within ``window``
+    days of it across the years, then the mean, standard deviation and 90th percentile, each smoothed with a
+    ``smooth``-day running mean (Hobday et al. 2016 use 5 and 31).
+
+    Returns 366 values of each (``mean``, ``sd``, ``p90``, ``n``): day 60 (29 February) repeats 28 February's, so a
+    reader can index by day of year in any year.
+    """
+    d = days.dropna()
+    # Days 1 to 365: in a leap year 29 February joins 28 February and every later day moves back one.
+    idx = pd.DatetimeIndex(d.index)
+    day = np.asarray(idx.day_of_year)
+    doy = day - (np.asarray(idx.is_leap_year) & (day >= 60))
+    vals = d.to_numpy()
+    mean, sd, p90, n = [], [], [], []
+    for k in range(1, 366):
+        dist = np.minimum(np.abs(doy - k), 365 - np.abs(doy - k))
+        w = vals[dist <= window]
+        n.append(int(w.size))
+        mean.append(float(w.mean()) if w.size else math.nan)
+        sd.append(float(w.std(ddof=1)) if w.size > 1 else math.nan)
+        p90.append(float(np.percentile(w, 90)) if w.size else math.nan)
+
+    def smoothed(x: list[float]) -> list[float | None]:
+        s = pd.Series(x * 3).rolling(smooth, center=True, min_periods=smooth // 2).mean().iloc[365:730]
+        return [None if pd.isna(v) else round(float(v), 2) for v in s]
+
+    def leap(x: list) -> list:
+        return x[:59] + [x[58]] + x[59:]
+
+    return {"mean": leap(smoothed(mean)), "sd": leap(smoothed(sd)), "p90": leap(smoothed(p90)), "n": leap(n)}

insitukit/store.py

@@ -0,0 +1,98 @@
+"""Where published JSON goes: a local directory, Cloudflare Workers KV (``kv://<account_id>/<namespace_id>``, token in
+``CLOUDFLARE_API_TOKEN``), or a ``gs://`` prefix.
+
+Writes pass a cost guard: an object name must match the caller's ``writable`` pattern and stay under ``max_bytes``, so
+a misbehaving loop can rewrite the same few objects but never multiply them. Each site passes its own pattern.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from urllib.parse import quote
+
+log = logging.getLogger(__name__)
+
+KV_API = "https://api.cloudflare.com/client/v4/accounts/{account}/storage/kv/namespaces/{ns}/values/{key}"
+MAX_OBJECT_BYTES = 8 * 1024 * 1024
+
+
+class Store:
+    def __init__(self, root: str, writable: re.Pattern[str], max_bytes: int = MAX_OBJECT_BYTES):
+        self.root = root.rstrip("/")
+        self.writable = writable
+        self.max_bytes = max_bytes
+        self._bucket = None
+        self._kv = None
+        if self.root.startswith("kv://"):
+            import requests
+
+            account, _, ns = self.root[5:].partition("/")
+            token = os.environ["CLOUDFLARE_API_TOKEN"].strip()
+            self._kv = (account, ns, requests.Session())
+            self._kv[2].headers["Authorization"] = f"Bearer {token}"
+        elif self.root.startswith("gs://"):
+            from google.cloud import storage
+
+            bucket, _, prefix = self.root[5:].partition("/")
+            self._bucket = storage.Client().bucket(bucket)
+            self._prefix = prefix
+
+    def _blob(self, rel: str):
+        name = f"{self._prefix}/{rel}" if self._prefix else rel
+        return self._bucket.blob(name)
+
+    def _kv_url(self, rel: str) -> str:
+        account, ns, _ = self._kv
+        return KV_API.format(account=account, ns=ns, key=quote(rel, safe=""))
+
+    def read_json(self, rel: str) -> dict | None:
+        if self._kv is not None:
+            resp = self._kv[2].get(self._kv_url(rel), timeout=60)
+            if resp.status_code == 404:
+                return None
+            resp.raise_for_status()
+            return resp.json()
+        if self._bucket is not None:
+            blob = self._blob(rel)
+            return json.loads(blob.download_as_text()) if blob.exists() else None
+        path = Path(self.root) / rel
+        return json.loads(path.read_text()) if path.exists() else None
+
+    def read_bytes(self, rel: str) -> bytes | None:
+        if self._kv is not None:
+            resp = self._kv[2].get(self._kv_url(rel), timeout=60)
+            if resp.status_code == 404:
+                return None
+            resp.raise_for_status()
+            return resp.content
+        if self._bucket is not None:
+            blob = self._blob(rel)
+            return blob.download_as_bytes() if blob.exists() else None
+        path = Path(self.root) / rel
+        return path.read_bytes() if path.exists() else None
+
+    def write_json(self, rel: str, obj: dict, max_age: int) -> None:
+        text = json.dumps(obj, separators=(",", ":"), allow_nan=False)
+        self.write_bytes(rel, text.encode(), max_age, content_type="application/json")
+
+    def write_bytes(self, rel: str, data: bytes, max_age: int, content_type: str = "application/octet-stream") -> None:
+        if not self.writable.fullmatch(rel):
+            raise ValueError(f"refusing to write unexpected object name: {rel}")
+        if len(data) > self.max_bytes:
+            raise ValueError(f"refusing to write {rel}: {len(data)} bytes exceeds {self.max_bytes}")
+        if self._kv is not None:
+            resp = self._kv[2].put(self._kv_url(rel), data=data, headers={"Content-Type": content_type}, timeout=120)
+            resp.raise_for_status()
+        elif self._bucket is not None:
+            blob = self._blob(rel)
+            blob.cache_control = f"public, max-age={max_age}"
+            blob.upload_from_string(data, content_type=content_type)
+        else:
+            path = Path(self.root) / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(data)
+        log.info("wrote %s/%s (%d bytes)", self.root, rel, len(data))

insitukit-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: insitukit
+Version: 0.1.0
+Summary: Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a compact JSON time-series format.
+Project-URL: Issues, https://github.com/lhzn-io/insitukit/issues
+Project-URL: Source, https://github.com/lhzn-io/insitukit
+Author-email: Long Horizon Observatory <dfry@lhzn.io>
+License: MIT License
+        
+        Copyright (c) 2026 Long Horizon Observatory
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: requests>=2.32
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.18; extra == 'gcs'
+Description-Content-Type: text/markdown
+
+# insitukit
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Fetch, summarise and publish in situ ocean observations: NOAA CO-OPS and ERDDAP clients, record statistics, and a
+compact JSON time-series format.
+
+forcingkit prepares what drives a coastal model and topobathykit builds the ground it runs on; insitukit handles what
+the instruments in the water actually measured. It reads tide gauges and buoys from NOAA CO-OPS and any ERDDAP server
+with care for the provider: requests are paced, budgeted and identified, and an empty window is an empty result, not
+an error. It reduces long records to the summaries people read: daily means only where a day is at least half
+covered, exceedance curves, joint histograms, and marine heatwave climatologies after Hobday et al. (2016). And it
+writes them as small JSON series behind a guard that refuses unexpected object names or sizes, so a web page can draw
+years of data from a few files.
+
+## Install
+
+```bash
+pip install insitukit            # CO-OPS, ERDDAP, statistics, the JSON form, local and Workers KV storage
+pip install "insitukit[gcs]"     # also Google Cloud Storage
+```
+
+## Use
+
+```python
+from datetime import datetime, timezone
+
+import insitukit
+from insitukit import coops, series, stats
+from insitukit.erddap import Erddap
+
+insitukit.identify("my-site/1.0 (+https://example.org; data@example.org)", application="my-site")
+
+start, end = datetime(2026, 10, 1, tzinfo=timezone.utc), datetime(2026, 11, 1, tzinfo=timezone.utc)
+
+# Observed water level and the station's own predictions; their difference is the surge.
+level = coops.fetch("water_level", "8419870", start, end).set_index("time")["water_level"]
+surge = level - coops.predictions("8419870", start, end).reindex(level.index)
+
+# A buoy's temperature from an ERDDAP server, at most 20 requests this run.
+server = Erddap("https://data.neracoos.org/erddap", budget=20)
+temp = server.fetch("UNH_CML", start, end, ["temperature"]).set_index("time")["temperature"]
+
+daily = stats.day_means(temp, per_day=24, digits=2, tz="America/New_York")
+hourly = series.encode(surge.resample("h").mean(), unit="m", places=3)  # {"t0": ..., "step": 3600, ...}
+```
+
+## Modules
+
+| Module | Contents |
+| :--- | :--- |
+| `insitukit.coops` | `fetch` (observations; long windows split to the API's limits), `predictions` (6-minute tides), `tide_events` (highs and lows), `metadata`. Metric units and UTC throughout. |
+| `insitukit.erddap` | `Erddap(base_url, budget, min_interval)`: tabledap CSV into a DataFrame, with a per-run request budget and an unreachable flag. |
+| `insitukit.stats` | `day_means` (coverage rule), `exceedance`, `joint` (two series paired by nearest time), `climatology` (Hobday et al. 2016: 11-day window, 31-day smoothing, mean, SD, 90th percentile). |
+| `insitukit.series` | `encode` and `decode` for one series, `encode_frame` and `decode_frame` for several on one grid, `iso`. |
+| `insitukit.store` | `Store(root, writable, max_bytes)`: JSON and bytes to a directory, `kv://<account>/<namespace>` (Cloudflare Workers KV, token in `CLOUDFLARE_API_TOKEN`) or `gs://bucket/prefix`, refusing names outside `writable` and objects over `max_bytes`. |
+
+## Etiquette
+
+CO-OPS requests are at least 1 s apart, and 403 and 429 answers are treated as throttling and retried with backoff.
+ERDDAP requests are at least `min_interval` apart and stop at the run's `budget`. Both send the User-Agent given to
+`identify`; include a way for the provider to reach you.
+
+## Reference
+
+Hobday, A. J., et al. (2016). A hierarchical approach to defining marine heatwaves. *Progress in Oceanography*, 141,
+227-238. doi:10.1016/j.pocean.2015.12.014
+
+## License
+
+MIT. Copyright (c) 2026 Long Horizon Observatory.

insitukit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+insitukit/__init__.py,sha256=awu_kR3V_nS4nxQTMcdYXgxkN04rkHk7XTlpQiFBHIc,1204
+insitukit/coops.py,sha256=_55rOEGY6zu1VCFTeo_p4QJewOqSJsOSfJpOJXcqlwo,8638
+insitukit/erddap.py,sha256=8bg_s3fJrcDmioSxKIBTpLreiyWVQi8hEzn1-UC-wCs,5039
+insitukit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+insitukit/series.py,sha256=SsqSRpBHoHJxJ8cPweY3BLcjw69HzPxV9gVfOe9yn1o,3596
+insitukit/stats.py,sha256=wfcVCyDOLaHg3EF8TcwyJMz6_9laTYshqLy0cxrrhNc,3732
+insitukit/store.py,sha256=g0VJ4ZFyT2RE-vGNKNrHRarwklM-vgaZWzbTkbuHmUk,4142
+insitukit-0.1.0.dist-info/METADATA,sha256=DmdPLY_m17t621irGIL0iD-QLT0XoZGLWNudzEVYuuY,6059
+insitukit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+insitukit-0.1.0.dist-info/licenses/LICENSE,sha256=VqXVp0x0MUmTZo0dT3YluvQiXyrUVAIhd5gEv_BdA28,1081
+insitukit-0.1.0.dist-info/RECORD,,

insitukit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

insitukit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Long Horizon Observatory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.