feat(waterdata): add chunk_granularity to control OGC chunk fan-out

The OGC getters chunk a multi-value request only as far as the server's
~8 KB URL limit forces — the fewest sub-requests. But because every
sub-request paginates, splitting a large result further is usually
quota-neutral, so that conservative default can be needlessly coarse: ten
states pulled as one under-limit request page just as many times as ten
per-state requests would.

Add `waterdata.chunk_granularity(level)`, a context manager that lets a
caller who knows their pull is large opt into a finer split — trading the
same pages for more, smaller sub-requests (smoother progress, more even
concurrency, a smaller unit of retry/resume). The level is "low", "medium",
or "high" (typed as `GranularityLevel`, a Literal, so a type checker rejects
anything else; an invalid string raises ValueError at the `with`). Each level
caps how many sub-chunks a multi-value argument is split into, derived from
the default fan-out concurrency (`API_USGS_CONCURRENT`): high = the full
width, medium a quarter, low a sixteenth (32 / 8 / 2 by default). Capping the
aggressive end at the concurrency width bounds the blast radius so an
accidental "high" on a huge list can't explode into thousands of sub-requests.
There is no "off" level — not entering the block is off. It is a scoped `with`
block, not an env var, because the library can't tell in advance whether a
query is large (a short-window query might fit one page, where extra chunks
only burn quota).

Implementation: a soft `ChunkPlan._refine` pass runs after the hard byte
pass; it only ever splits further, so the url_limit invariant holds and it
never raises. The resolved per-axis cap is read from a contextvar (Ambient)
set by the context manager at plan-construction time. Exported (with the
`GranularityLevel` type) from `dataretrieval.waterdata` and the top-level
`dataretrieval` package.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,5 @@
+**07/01/2026:** Added `waterdata.chunk_granularity(...)` — a context manager to control how finely the OGC `waterdata` getters split multi-value requests. By default the getters chunk only as much as the server's ~8 KB URL limit forces (the fewest sub-requests). But because every sub-request paginates, splitting a large result further is usually quota-neutral, so a caller who *knows* their pull is large can opt into a finer split for smoother progress, more even concurrency, and a smaller unit of retry/resume: `with waterdata.chunk_granularity("high"): df, md = waterdata.get_daily(monitoring_location_id=many_sites)`. The level is one of `"low"`, `"medium"`, or `"high"` — typed as `waterdata.GranularityLevel` (a `typing.Literal`), so a type checker rejects any other value and an invalid string raises `ValueError` at the `with`. Each level caps how many sub-chunks a multi-value argument is split into, *derived* from the default fan-out concurrency (`API_USGS_CONCURRENT`) rather than hardcoded: `"high"` = the full width, `"medium"` a quarter, `"low"` a sixteenth (32 / 8 / 2 by default). Capping the aggressive end at the concurrency width bounds the blast radius — an accidental `"high"` on a huge list can't explode into thousands of sub-requests. There is no "off" level: not entering the block *is* off. It is deliberately a scoped `with` block rather than an automatic behavior or an environment variable, since the library can't tell in advance whether a query is large — a short-window query might fit in a single page, where extra chunks would only burn quota. Also exported at the top level as `dataretrieval.chunk_granularity`.
+
 **06/23/2026:** **Breaking change (1.2.0):** the minimum supported Python is now **3.10** (`requires-python = ">=3.10"`). 3.9 support was already effectively broken — the `waterdata` module's dependencies (`anyio`, the test stack) require 3.10+, and the `waterdata` test modules already skipped on <3.10. `anyio` is now declared as a direct dependency (it is imported directly by `waterdata`), and the CI/ruff/mypy targets move to 3.10. Also fully removed the deprecated `variable_info` metadata property: the `NWIS_Metadata` override only warned and returned `None` (it relied on the defunct `get_pmcodes`), and the `BaseMetadata` abstract is gone too since nothing implemented it — accessing `.variable_info` now raises `AttributeError`. `site_info` is unaffected.
 
 **06/23/2026:** **Breaking change (1.2.0):** removed the `nadp` module and the deprecated `samples` module ahead of the 1.2.0 release. `nadp` was deprecated on 05/01/2026 — NADP is not a USGS data source, so retrieve NADP data directly from https://nadp.slh.wisc.edu/. The `samples.get_usgs_samples` shim (a deprecated forward to the modern getter) is gone; use `waterdata.get_samples()` instead. `import dataretrieval.nadp` / `import dataretrieval.samples` now raise `ModuleNotFoundError`.

dataretrieval/__init__.py

@@ -44,6 +44,11 @@
     URLTooLong,
 )
 
+# Chunk-granularity control (a context manager) and its level type. Defined with
+# the chunker in ``dataretrieval.ogc.chunking``; surfaced here for a stable
+# public path ``from dataretrieval import chunk_granularity``.
+from dataretrieval.ogc.chunking import GranularityLevel, chunk_granularity
+
 # Resumable chunk-interruption exceptions. They are defined in
 # ``dataretrieval.ogc.interruptions`` rather than ``dataretrieval.exceptions``
 # because they carry pandas/httpx state and a resumable ``ChunkedCall`` handle,
@@ -93,5 +98,8 @@
     "ChunkInterrupted",
     "QuotaExhausted",
     "ServiceInterrupted",
+    # chunk-granularity control (defined in ogc.chunking)
+    "chunk_granularity",
+    "GranularityLevel",
     "__version__",
 ]

dataretrieval/ogc/chunking.py

@@ -9,6 +9,17 @@
 cartesian product of chunks. Requests that already fit get a trivial
 single-step plan — ``ChunkedCall`` has one code path either way.
 
+Granularity: the planner is conservative by default — it splits only as far
+as the byte limit forces, minimizing sub-requests. A caller who knows their
+result is large can widen that split via the ``chunk_granularity`` context
+manager (``"low"`` / ``"medium"`` / ``"high"``): because every sub-request
+paginates, a finer split of a large result is usually quota-neutral, and buys
+smoother progress, more even concurrency, and a smaller unit of retry/resume.
+It is a scoped ``with`` block — not an env var like ``API_USGS_CONCURRENT`` —
+precisely so an aggressive setting can't leak past the call it was meant for
+and burn quota on a query that would have fit in one page. The level drives
+:meth:`ChunkPlan._refine`; see ``chunk_granularity`` for the full rationale.
+
 This module owns the *execution* half — the event loop and bounded
 concurrency that drive a plan to completion (``ChunkedCall``) plus the
 public ``multi_value_chunked`` decorator. The neighboring concerns live in
@@ -69,8 +80,9 @@
 import functools
 import os
 from collections.abc import Callable, Iterator
+from contextlib import contextmanager
 from contextvars import copy_context
-from typing import Any, cast
+from typing import Any, Literal, cast
 
 import httpx
 import pandas as pd
@@ -172,6 +184,128 @@ def get_active_client() -> httpx.AsyncClient | None:
     return _chunked_client.get()
 
 
+# Chunk-granularity dial: opt-in to fan a query out *more finely* than the byte
+# limit alone requires. Scoped to a ``with chunk_granularity(...):`` block (a
+# ContextVar), deliberately NOT an env var — unlike ``API_USGS_CONCURRENT`` /
+# ``API_USGS_RETRIES``, a persistent process-wide setting here would be a quota
+# footgun (see :func:`chunk_granularity`). The ambient holds the resolved cap on
+# sub-chunks per axis; ``0`` (the default, outside any block) means "chunk only
+# as much as the byte limit needs".
+_granularity: Ambient[int] = Ambient("ogc_chunk_granularity", 0)
+
+#: The three accepted granularity levels, as a typing ``Literal`` so a type
+#: checker rejects any other value at the call site.
+GranularityLevel = Literal["low", "medium", "high"]
+
+# Each level caps the sub-chunks a multi-value axis is split into, derived from
+# the default fan-out width ``_CONCURRENCY_DEFAULT`` (``API_USGS_CONCURRENT``)
+# rather than hardcoded — past that many in-flight sub-requests the extra chunks
+# mostly just queue, so it's a natural ceiling for the most aggressive level,
+# and deriving from the same constant keeps the two in step if it moves. Levels
+# are spaced 4x apart: ``"high"`` = the full width, ``"medium"`` = a quarter,
+# ``"low"`` = a sixteenth (floored at 1 so a tiny width can't yield a 0 cap).
+_GRANULARITY_LEVELS: dict[str, int] = {
+    "low": max(1, _CONCURRENCY_DEFAULT // 16),
+    "medium": max(1, _CONCURRENCY_DEFAULT // 4),
+    "high": _CONCURRENCY_DEFAULT,
+}
+
+
+def _resolve_granularity(level: GranularityLevel) -> int:
+    """
+    Map a granularity level name to its per-axis sub-chunk cap.
+
+    Parameters
+    ----------
+    level : {"low", "medium", "high"}
+        The user-supplied level.
+
+    Returns
+    -------
+    int
+        The maximum sub-chunks per multi-value axis for that level
+        (``4`` / ``16`` / ``32``).
+
+    Raises
+    ------
+    ValueError
+        If ``level`` is anything other than ``"low"``, ``"medium"``, or
+        ``"high"`` — raised eagerly (at the ``with`` statement) so a typo fails
+        loudly rather than silently doing nothing.
+    """
+    try:
+        return _GRANULARITY_LEVELS[level]
+    except (KeyError, TypeError):
+        valid = ", ".join(map(repr, _GRANULARITY_LEVELS))
+        raise ValueError(
+            f"chunk_granularity level must be one of {valid}; got {level!r}."
+        ) from None
+
+
+@contextmanager
+def chunk_granularity(level: GranularityLevel) -> Iterator[None]:
+    """
+    Scope how finely the OGC getters chunk multi-value requests.
+
+    By default the Water Data / NGWMN getters chunk a request only as much as
+    the server's ~8 KB URL-byte limit forces — the fewest sub-requests that
+    fit. That is the safe default, but it can be *needlessly* conservative:
+    because every sub-request paginates, splitting a large result further is
+    usually quota-neutral (ten states pulled as one under-limit request page
+    just as many times as ten per-state requests would). This context manager
+    lets a caller who *knows* their pull is large ask for that finer split —
+    trading the same pages for more, smaller sub-requests, which gives smoother
+    progress, more even concurrency, and a smaller unit of retry/resume.
+
+    Because the library can't tell in advance whether a query is large (ten
+    states over a short window might fit in a single page, where extra chunks
+    would only burn quota), this is a *deliberate* per-call knob rather than an
+    automatic behavior or a process-wide environment variable — scoping it to a
+    ``with`` block keeps an aggressive setting from leaking into unrelated calls
+    and accidentally spending quota. Outside any block the getters use the
+    conservative default; there is no "off" level because *not* entering the
+    block is off.
+
+    Parameters
+    ----------
+    level : {"low", "medium", "high"}
+        How aggressively to chunk within the block. Each level caps how many
+        sub-chunks a single multi-value argument is split into, as a fraction
+        of the default fan-out width (``API_USGS_CONCURRENT``, ``32``):
+        ``"high"`` up to the full width, ``"medium"`` a quarter, and ``"low"`` a
+        sixteenth of it — ``32`` / ``8`` / ``2`` by default — or one value per
+        sub-request once the argument has fewer values than the cap. Tying the
+        ceiling to the concurrency width is a guardrail: extra chunks beyond it
+        mostly just queue, and it keeps an accidental ``"high"`` on a very long
+        list from exploding into thousands of sub-requests. (With several
+        multi-value arguments the per-argument counts still multiply.)
+
+    Yields
+    ------
+    None
+
+    Raises
+    ------
+    ValueError
+        If ``level`` isn't ``"low"``, ``"medium"``, or ``"high"`` — raised on
+        ``with`` entry, before any request is issued.
+
+    Examples
+    --------
+    >>> from dataretrieval import waterdata
+    >>> with waterdata.chunk_granularity("high"):
+    ...     df, md = waterdata.get_daily(
+    ...         monitoring_location_id=many_sites, parameter_code="00060"
+    ...     )  # doctest: +SKIP
+
+    See Also
+    --------
+    ChunkPlan._refine : the planning-side effect of the level.
+    """
+    with _granularity(_resolve_granularity(level)):
+        yield
+
+
 class ChunkedCall:
     """
     Stateful handle for a chunked call.
@@ -591,8 +725,9 @@ def multi_value_chunked(
     ``async def fetch(args) -> (df, response)``, and drives it to
     completion via :meth:`ChunkedCall.resume`. The plan splits multi-value
     list params and the cql-text filter so each sub-request URL fits the
-    byte limit; an already-fitting request is a one-step plan. See the
-    module docstring for the concurrency model.
+    byte limit; an already-fitting request is a one-step plan, unless an
+    active :func:`chunk_granularity` block asks the plan to fan out more
+    finely. See the module docstring for the concurrency model.
 
     Parameters
     ----------
@@ -636,7 +771,14 @@ def wrapper(
             finalize: _Finalize = _passthrough_result,
         ) -> tuple[pd.DataFrame, Any]:
             limit = _OGC_URL_BYTE_LIMIT if url_limit is None else url_limit
-            plan = ChunkPlan(args, build_request, limit)
+            # Read the granularity dial from the ambient set by
+            # ``chunk_granularity`` (0 = off outside any such block; otherwise the
+            # per-axis sub-chunk cap). It only affects *planning*, done here up
+            # front, so a later resume — which re-issues the already-planned
+            # sub-requests — needs no snapshot.
+            plan = ChunkPlan(
+                args, build_request, limit, max_chunks_per_axis=_granularity.get()
+            )
             retry_policy = RetryPolicy.from_env()
             # The concurrency cap is resolved inside ``resume()`` from
             # ``API_USGS_CONCURRENT``; ``1`` is a sequential gather,

dataretrieval/ogc/planning.py

@@ -288,6 +288,21 @@ def _extract_axes(args: dict[str, Any]) -> list[_Axis]:
     return axes
 
 
+def _split_at(chunks: list[list[str]], idx: int) -> None:
+    """Replace ``chunks[idx]`` in place with its two contiguous halves.
+
+    The single primitive both planning passes use to fan an axis out. It
+    preserves the partition invariants every consumer relies on: *coverage*
+    (each atom survives, exactly once) and *contiguous, deterministic order*
+    (resume and :meth:`ChunkPlan.iter_sub_args` depend on it). Kept in one
+    place so those invariants can't drift between :meth:`ChunkPlan._plan`
+    (byte-driven) and :meth:`ChunkPlan._refine` (granularity-driven).
+    """
+    chunk = chunks[idx]
+    mid = len(chunk) // 2
+    chunks[idx : idx + 1] = [chunk[:mid], chunk[mid:]]
+
+
 class ChunkPlan:
     """
     Strategy for issuing one user-level request as a sequence of
@@ -312,7 +327,17 @@ class ChunkPlan:
         Factory that turns a kwargs dict into a sized httpx request,
         e.g. ``_construct_api_requests``.
     url_limit : int
-        Byte budget for the request (URL + body).
+        Byte budget for the request (URL + body) — a hard ceiling every
+        sub-request must fit.
+    max_chunks_per_axis : int, optional
+        Soft cap on sub-chunks per multi-value axis (default ``0`` = off).
+        ``0`` chunks only as much as ``url_limit`` requires — the most
+        conservative plan, fewest sub-requests. A positive cap fans each axis
+        out into up to ``min(len(atoms), max_chunks_per_axis)`` pieces (never
+        fewer than the byte budget already forces), so a large multi-page pull
+        is issued as more, smaller sub-requests. Set from the resolved
+        :func:`~dataretrieval.ogc.chunking.chunk_granularity` level; see
+        :meth:`_refine`.
 
     Attributes
     ----------
@@ -344,6 +369,7 @@ def __init__(
         args: dict[str, Any],
         build_request: Callable[..., httpx.Request],
         url_limit: int,
+        max_chunks_per_axis: int = 0,
     ) -> None:
         self.args = args
         self.axes: list[_Axis] = []
@@ -352,10 +378,10 @@ def __init__(
 
         axes = _extract_axes(args)
         if not axes:
-            # No chunkable axis: nothing to split. If the single request fits,
-            # run it verbatim (the common passthrough). ``_safe_request_bytes``
-            # treats an un-constructable URL (httpx.InvalidURL, > 64 KB) as over
-            # budget.
+            # No chunkable axis: nothing to split, and ``granularity`` has
+            # nothing to act on either. If the single request fits, run it
+            # verbatim (the common passthrough). ``_safe_request_bytes`` treats
+            # an un-constructable URL (httpx.InvalidURL, > 64 KB) as over budget.
             if _safe_request_bytes(build_request, args, url_limit) <= url_limit:
                 return
             # Over budget. A filter the chunker doesn't manage — cql-json — is
@@ -388,14 +414,29 @@ def __init__(
         except httpx.InvalidURL:
             initial_request = None
 
+        fits = False
         if initial_request is not None:
             self.canonical_url = str(initial_request.url)
-            if _request_bytes(initial_request) <= url_limit:
-                return
+            fits = _request_bytes(initial_request) <= url_limit
+
+        # A request that already fits and hasn't opted into finer chunking is
+        # the common passthrough: leave ``axes``/``chunks`` empty so
+        # ``total == 1`` and ``iter_sub_args`` yields the original args
+        # verbatim. Only when ``max_chunks_per_axis`` asks for extra fan-out do
+        # we set the axes up to be refined below.
+        if fits and max_chunks_per_axis <= 0:
+            return
 
         self.axes = axes
         self.chunks = {axis.arg_key: [list(axis.atoms)] for axis in axes}
-        self._plan(build_request, url_limit)
+        if not fits:
+            # Hard pass: greedy-halve until every worst-case sub-request fits
+            # the byte budget (may raise ``Unchunkable``).
+            self._plan(build_request, url_limit)
+        # Soft pass: optionally split further than the byte budget requires.
+        # Purely additive — never re-raises, and the byte budget stays
+        # satisfied; a no-op at ``max_chunks_per_axis <= 0``.
+        self._refine(max_chunks_per_axis)
 
         if self.canonical_url is None:
             # Original URL was un-constructable (httpx.InvalidURL); fall
@@ -447,10 +488,42 @@ def _plan(
                     f"sub-request). Reduce input sizes, shorten or simplify "
                     f"the filter, or split the call manually."
                 )
-            axis_chunks = self.chunks[biggest_axis.arg_key]
-            chunk = axis_chunks[biggest_idx]
-            mid = len(chunk) // 2
-            axis_chunks[biggest_idx : biggest_idx + 1] = [chunk[:mid], chunk[mid:]]
+            _split_at(self.chunks[biggest_axis.arg_key], biggest_idx)
+
+    def _refine(self, max_chunks_per_axis: int) -> None:
+        """
+        Fan each axis out more finely than the byte budget alone requires —
+        the granularity dial (see
+        :func:`~dataretrieval.ogc.chunking.chunk_granularity` for why a caller
+        would want this).
+
+        Each axis is split until it holds at least
+        ``min(len(atoms), max_chunks_per_axis)`` chunks — up to the cap, or one
+        atom per chunk for a shorter axis. Purely additive — only ever *splits*
+        existing chunks, so the byte pass's work and the ``url_limit`` invariant
+        are both preserved (an axis the byte pass already split past the cap is
+        left alone), and it never raises. A no-op at ``max_chunks_per_axis <= 0``.
+
+        Parameters
+        ----------
+        max_chunks_per_axis : int
+            Soft cap on sub-chunks per axis (``0`` = off), the resolved
+            granularity level. A shorter axis simply saturates at one atom per
+            chunk.
+        """
+        if max_chunks_per_axis <= 0:
+            return
+        for axis in self.axes:
+            chunks = self.chunks[axis.arg_key]
+            target = min(len(axis.atoms), max_chunks_per_axis)
+            # ``target <= len(atoms)`` guarantees some chunk still holds >1 atom
+            # each iteration, so the loop reaches exactly ``target`` pieces and
+            # terminates. ``enumerate`` keeps the key closed over its own
+            # argument (not the loop-mutated ``chunks``); ties take the lowest
+            # index, so the split stays deterministic.
+            while len(chunks) < target:
+                idx, _ = max(enumerate(chunks), key=lambda kv: len(kv[1]))
+                _split_at(chunks, idx)
 
     def _worst_case_args(self) -> dict[str, Any]:
         """

dataretrieval/waterdata/__init__.py

@@ -9,6 +9,7 @@
 
 from __future__ import annotations
 
+from dataretrieval.ogc.chunking import GranularityLevel, chunk_granularity
 from dataretrieval.ogc.filters import FILTER_LANG
 
 # Public API exports
@@ -50,6 +51,8 @@
     "PROFILE_LOOKUP",
     "SERVICES",
     "WATERDATA_SERVICES",
+    "GranularityLevel",
+    "chunk_granularity",
     "get_channel",
     "get_codes",
     "get_combined_metadata",