refactor(waterdata): rename chunk_granularity -> parallel_chunks

Rename the public context manager chunk_granularity to parallel_chunks and the GranularityLevel type to ParallelChunksLevel (both exported from dataretrieval and dataretrieval.waterdata), plus internals (_resolve_level, _MAX_PARALLEL_CHUNKS, _LEVEL_CAPS, the _parallel_chunks ambient). 'parallel_chunks' names what the knob does — fan a query into more, parallel sub-requests — without colliding with API_USGS_CONCURRENT (the separate in-flight cap). Docstrings, NEWS, user guide, README, and tests updated to match. Pure rename; no behavior change.

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

Author: thodson-usgs

NEWS.md

@@ -1,4 +1,4 @@
-**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 costs little or no extra quota when each sub-request still spans many pages, 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 the *total* number of sub-requests the call is split into — `"low"` / `"medium"` / `"high"` cap at 2 / 8 / 32 overall, across every multi-value argument combined, not per argument. That ceiling is a granularity constant, deliberately independent of the fan-out concurrency (`API_USGS_CONCURRENT`): how finely a query splits is orthogonal to how many sub-requests run at once. Capping the aggressive end at 32 bounds the blast radius — an accidental `"high"` on a huge list, or a call with several multi-value arguments, 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`.
+**07/01/2026:** Added `waterdata.parallel_chunks(...)` — 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 costs little or no extra quota when each sub-request still spans many pages, 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.parallel_chunks("high"): df, md = waterdata.get_daily(monitoring_location_id=many_sites)`. The level is one of `"low"`, `"medium"`, or `"high"` — typed as `waterdata.ParallelChunksLevel` (a `typing.Literal`), so a type checker rejects any other value and an invalid string raises `ValueError` at the `with`. Each level caps the *total* number of sub-requests the call is split into — `"low"` / `"medium"` / `"high"` cap at 2 / 8 / 32 overall, across every multi-value argument combined, not per argument. That ceiling is a parallel_chunks constant, deliberately independent of the fan-out concurrency (`API_USGS_CONCURRENT`): how finely a query splits is orthogonal to how many sub-requests run at once. Capping the aggressive end at 32 bounds the blast radius — an accidental `"high"` on a huge list, or a call with several multi-value arguments, 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.parallel_chunks`.
 
 **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.
 

README.md

@@ -105,13 +105,13 @@ df, metadata = waterdata.get_continuous(
 print(f"Retrieved {len(df)} continuous gage height measurements")
 ```
 
-#### Speeding up large downloads with `chunk_granularity`
+#### Speeding up large downloads with `parallel_chunks`
 
 By default the getters split a multi-value request only as far as the server's
 ~8 KB URL limit forces — the fewest sub-requests. For a **large, paginated**
 pull that is needlessly conservative: every sub-request pages through its own
 results, so dividing the query into more, smaller sub-requests lets those pages
-be fetched **in parallel**. `chunk_granularity` opts a single call into that
+be fetched **in parallel**. `parallel_chunks` opts a single call into that
 finer split. It pays off only when the result is large enough to span many
 pages *and* the query has a multi-value argument to divide (such as a list of
 monitoring locations); on a small query — or one with nothing to split — it just
@@ -124,7 +124,7 @@ from dataretrieval import waterdata
 # enough to span many pages, so it profits from a finer split.
 sites, _ = waterdata.get_monitoring_locations(state="Ohio", site_type_code="ST")
 
-with waterdata.chunk_granularity("high"):        # "low" | "medium" | "high"
+with waterdata.parallel_chunks("high"):        # "low" | "medium" | "high"
     df, md = waterdata.get_daily(
         monitoring_location_id=sites["monitoring_location_id"].tolist(),
         parameter_code="00060",                  # discharge

dataretrieval/__init__.py

@@ -44,10 +44,10 @@
     URLTooLong,
 )
 
-# Chunk-granularity control (a context manager) and its level type. Defined with
+# Parallel-chunks 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
+# public path ``from dataretrieval import parallel_chunks``.
+from dataretrieval.ogc.chunking import ParallelChunksLevel, parallel_chunks
 
 # Resumable chunk-interruption exceptions. They are defined in
 # ``dataretrieval.ogc.interruptions`` rather than ``dataretrieval.exceptions``
@@ -98,8 +98,8 @@
     "ChunkInterrupted",
     "QuotaExhausted",
     "ServiceInterrupted",
-    # chunk-granularity control (defined in ogc.chunking)
-    "chunk_granularity",
-    "GranularityLevel",
+    # parallel-chunks control (defined in ogc.chunking)
+    "parallel_chunks",
+    "ParallelChunksLevel",
     "__version__",
 ]

dataretrieval/ogc/chunking.py

@@ -9,11 +9,11 @@
 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
+Parallel chunks: the planner is conservative by default — it splits only as far as
 the byte limit forces. A caller who knows their result is large can opt into a
-finer split via the ``chunk_granularity`` context manager
+finer split via the ``parallel_chunks`` context manager
 (``"low"`` / ``"medium"`` / ``"high"``); the resolved cap drives
-:meth:`ChunkPlan._refine`. See ``chunk_granularity`` for the why and the when.
+:meth:`ChunkPlan._refine`. See ``parallel_chunks`` for the why and the when.
 
 This module owns the *execution* half — the event loop and bounded
 concurrency that drive a plan to completion (``ChunkedCall``) plus the
@@ -179,43 +179,43 @@ 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 (see :func:`chunk_granularity` for
+# Parallel-chunks dial: opt-in to fan a query out *more finely* than the byte
+# limit alone requires. Scoped to a ``with parallel_chunks(...):`` block (a
+# ContextVar), deliberately NOT an env var (see :func:`parallel_chunks` for
 # why). The ambient holds the resolved cap on the plan's total sub-request
 # count; ``0`` (the default, outside any block) means "chunk only as much as
 # the byte limit needs".
-_granularity: Ambient[int] = Ambient("ogc_chunk_granularity", 0)
+_parallel_chunks: Ambient[int] = Ambient("ogc_parallel_chunks", 0)
 
-#: The three accepted granularity levels, as a typing ``Literal`` so a type
+#: The three accepted parallel_chunks levels, as a typing ``Literal`` so a type
 #: checker rejects any other value at the call site.
-GranularityLevel = Literal["low", "medium", "high"]
+ParallelChunksLevel = Literal["low", "medium", "high"]
 
-#: Valid levels derived from the type, so ``GranularityLevel`` stays the single
-#: source of truth for what ``_resolve_granularity`` accepts (mirrors the
+#: Valid levels derived from the type, so ``ParallelChunksLevel`` stays the single
+#: source of truth for what ``_resolve_level`` accepts (mirrors the
 #: ``get_args``-based ``_VALID_ON_TIE`` / ``_VALID_FILE_TYPES`` in sibling
 #: modules).
-_VALID_LEVELS: tuple[GranularityLevel, ...] = get_args(GranularityLevel)
+_VALID_LEVELS: tuple[ParallelChunksLevel, ...] = get_args(ParallelChunksLevel)
 
-# Granularity's own ceiling on the plan's total sub-request count —
+# The parallel_chunks ceiling on the plan's total sub-request count —
 # deliberately NOT tied to the concurrency default: fan-out *volume* (how many
 # sub-requests a query becomes) is orthogonal to how many run at once
 # (``API_USGS_CONCURRENT``). 32 is a sane ceiling on the whole call (across
 # every axis, not per axis — see ``ChunkPlan._refine``) that bounds the blast
 # radius of an accidental ``"high"`` on a very long list or several multi-value
 # arguments at once; the milder levels are a quarter and a sixteenth of it (the
 # three are spaced 4x apart).
-_GRANULARITY_MAX_CHUNKS = 32
-_GRANULARITY_LEVELS: dict[str, int] = {
-    "low": _GRANULARITY_MAX_CHUNKS // 16,  # 2
-    "medium": _GRANULARITY_MAX_CHUNKS // 4,  # 8
-    "high": _GRANULARITY_MAX_CHUNKS,  # 32
+_MAX_PARALLEL_CHUNKS = 32
+_LEVEL_CAPS: dict[str, int] = {
+    "low": _MAX_PARALLEL_CHUNKS // 16,  # 2
+    "medium": _MAX_PARALLEL_CHUNKS // 4,  # 8
+    "high": _MAX_PARALLEL_CHUNKS,  # 32
 }
 
 
-def _resolve_granularity(level: GranularityLevel) -> int:
+def _resolve_level(level: ParallelChunksLevel) -> int:
     """
-    Map a granularity level name to its total sub-request cap.
+    Map a parallel_chunks level name to its total sub-request cap.
 
     Parameters
     ----------
@@ -237,13 +237,13 @@ def _resolve_granularity(level: GranularityLevel) -> int:
     """
     if level not in _VALID_LEVELS:
         raise ValueError(
-            f"chunk_granularity level must be one of {_VALID_LEVELS}; got {level!r}."
+            f"parallel_chunks level must be one of {_VALID_LEVELS}; got {level!r}."
         )
-    return _GRANULARITY_LEVELS[level]
+    return _LEVEL_CAPS[level]
 
 
 @contextmanager
-def chunk_granularity(level: GranularityLevel) -> Iterator[None]:
+def parallel_chunks(level: ParallelChunksLevel) -> Iterator[None]:
     """
     Scope how finely the OGC getters chunk multi-value requests.
 
@@ -301,7 +301,7 @@ def chunk_granularity(level: GranularityLevel) -> Iterator[None]:
     Examples
     --------
     >>> from dataretrieval import waterdata
-    >>> with waterdata.chunk_granularity("high"):
+    >>> with waterdata.parallel_chunks("high"):
     ...     df, md = waterdata.get_daily(
     ...         monitoring_location_id=many_sites, parameter_code="00060"
     ...     )  # doctest: +SKIP
@@ -310,7 +310,7 @@ def chunk_granularity(level: GranularityLevel) -> Iterator[None]:
     --------
     ChunkPlan._refine : the planning-side effect of the level.
     """
-    with _granularity(_resolve_granularity(level)):
+    with _parallel_chunks(_resolve_level(level)):
         yield
 
 
@@ -734,7 +734,7 @@ def multi_value_chunked(
     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, unless an
-    active :func:`chunk_granularity` block asks the plan to fan out more
+    active :func:`parallel_chunks` block asks the plan to fan out more
     finely. See the module docstring for the concurrency model.
 
     Parameters
@@ -779,13 +779,13 @@ def wrapper(
             finalize: _Finalize = _passthrough_result,
         ) -> tuple[pd.DataFrame, Any]:
             limit = _OGC_URL_BYTE_LIMIT if url_limit is None else url_limit
-            # Read the granularity dial from the ambient set by
-            # ``chunk_granularity`` (0 = off outside any such block; otherwise the
+            # Read the parallel_chunks dial from the ambient set by
+            # ``parallel_chunks`` (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()
+                args, build_request, limit, max_chunks_per_axis=_parallel_chunks.get()
             )
             retry_policy = RetryPolicy.from_env()
             # The concurrency cap is resolved inside ``resume()`` from

dataretrieval/ogc/planning.py

@@ -296,7 +296,7 @@ def _split_at(chunks: list[list[str]], idx: int) -> None:
     (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).
+    (byte-driven) and :meth:`ChunkPlan._refine` (fan-out-driven).
     """
     chunk = chunks[idx]
     mid = len(chunk) // 2
@@ -337,7 +337,7 @@ class ChunkPlan:
         cartesian product across axes, never fewer than the byte budget
         already forces) — capped as a whole, not per axis, so several
         multi-value axes can't multiply past the cap. Set from the resolved
-        :func:`~dataretrieval.ogc.chunking.chunk_granularity` level; see
+        :func:`~dataretrieval.ogc.chunking.parallel_chunks` level; see
         :meth:`_refine`.
 
     Attributes
@@ -379,7 +379,7 @@ def __init__(
 
         axes = _extract_axes(args)
         if not axes:
-            # No chunkable axis: nothing to split, and ``granularity`` has
+            # No chunkable axis: nothing to split, and ``parallel_chunks`` 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.
@@ -494,8 +494,8 @@ def _plan(
     def _refine(self, max_chunks_per_axis: int) -> None:
         """
         Fan the plan out more finely than the byte budget alone requires —
-        the granularity dial (see
-        :func:`~dataretrieval.ogc.chunking.chunk_granularity` for why a caller
+        the parallel_chunks dial (see
+        :func:`~dataretrieval.ogc.chunking.parallel_chunks` for why a caller
         would want this).
 
         Caps the plan's *total* sub-request count (:attr:`total`, the
@@ -514,7 +514,7 @@ def _refine(self, max_chunks_per_axis: int) -> None:
         ----------
         max_chunks_per_axis : int
             Soft cap on the plan's total sub-request count (``0`` = off),
-            the resolved granularity level. Despite the name — kept for the
+            the resolved parallel_chunks level. Despite the name — kept for the
             public dial's "sub-chunks per multi-value argument" framing,
             which matches this cap exactly in the common single-axis case —
             multi-axis plans are capped on the product, not per axis.

dataretrieval/waterdata/__init__.py

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

docs/source/userguide/errors.rst

@@ -106,7 +106,7 @@ extra quota *as long as each sub-request still spans many pages* (ten states
 pulled as one request then page nearly as many times as ten per-state requests
 would; a split that leaves each sub-request only a page or two adds its partial
 final page). So if you *know* your pull is large you can ask for a finer split
-with ``chunk_granularity`` -- trading roughly the same pages for more, smaller
+with ``parallel_chunks`` -- trading roughly the same pages for more, smaller
 sub-requests, which gives smoother progress, more even concurrency, and a
 smaller unit of retry/resume. It is a scoped ``with``
 block, so an aggressive setting can't leak into unrelated calls and
@@ -116,7 +116,7 @@ accidentally spend quota:
 
     from dataretrieval import waterdata
 
-    with waterdata.chunk_granularity("high"):
+    with waterdata.parallel_chunks("high"):
         df, md = waterdata.get_daily(
             monitoring_location_id=many_sites, parameter_code="00060"
         )

tests/utils_test.py

@@ -208,21 +208,21 @@ def test_chunk_interruptions_exported_at_top_level(self):
             dataretrieval.ChunkInterrupted, dataretrieval.DataRetrievalError
         )
 
-    def test_chunk_granularity_exported_at_top_level_and_waterdata(self):
-        """The ``chunk_granularity`` context manager and its ``GranularityLevel``
+    def test_parallel_chunks_exported_at_top_level_and_waterdata(self):
+        """The ``parallel_chunks`` context manager and its ``ParallelChunksLevel``
         type are reachable both from the top level (``from dataretrieval import
-        chunk_granularity``) and from the user-facing ``dataretrieval.waterdata``
+        parallel_chunks``) and from the user-facing ``dataretrieval.waterdata``
         namespace, and both resolve to the single objects defined in
         ``dataretrieval.ogc.chunking``."""
         import dataretrieval
         from dataretrieval import waterdata
         from dataretrieval.ogc import chunking
 
-        assert dataretrieval.chunk_granularity is chunking.chunk_granularity
-        assert waterdata.chunk_granularity is chunking.chunk_granularity
-        assert dataretrieval.GranularityLevel is chunking.GranularityLevel
-        assert waterdata.GranularityLevel is chunking.GranularityLevel
-        for name in ("chunk_granularity", "GranularityLevel"):
+        assert dataretrieval.parallel_chunks is chunking.parallel_chunks
+        assert waterdata.parallel_chunks is chunking.parallel_chunks
+        assert dataretrieval.ParallelChunksLevel is chunking.ParallelChunksLevel
+        assert waterdata.ParallelChunksLevel is chunking.ParallelChunksLevel
+        for name in ("parallel_chunks", "ParallelChunksLevel"):
             assert name in dataretrieval.__all__
             assert name in waterdata.__all__