Clarify chunker docstrings to match URL+body sizing

Copilot review surfaced that ``_plan_chunks`` and ``multi_value_chunked``
docstrings advertised the budget as URL length, but the implementation
gates on ``_request_bytes`` (URL + body) so POST routes are sized
correctly. The public ``url_limit`` parameter name is kept for API
stability; only the prose is updated to honestly describe what's
measured. Also tightened ``_worst_case_args`` wording from "URL probe"
to "request-size probe" for consistency.

No behavior change.

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

Author: thodson-usgs

dataretrieval/waterdata/chunking.py

@@ -240,8 +240,9 @@ def _worst_case_args(
     each dim's largest chunk (by URL-encoded bytes), against the
     ``probe_args`` already returned by ``_filter_aware_probe_args``
     (so any chunkable filter is at the inner chunker's bail-floor
-    size). Driving the URL probe with this args dict tells the
-    planner whether the *biggest* sub-request it would emit fits."""
+    size). Driving the request-size probe with this args dict tells
+    the planner whether the *biggest* sub-request it would emit fits
+    the byte budget (URL + body, per ``_request_bytes``)."""
     out = dict(probe_args)
     for k, chunks in plan.items():
         out[k] = max(chunks, key=_chunk_bytes)
@@ -254,7 +255,12 @@ def _plan_chunks(
     url_limit: int,
     max_chunks: int | None = None,
 ) -> dict[str, list[list[Any]]] | None:
-    """Greedy halving until the worst-case sub-request URL fits.
+    """Greedy halving until the worst-case sub-request fits ``url_limit``.
+
+    The budget is total request bytes (URL + body, via ``_request_bytes``)
+    so POST routes are sized correctly — the public parameter name
+    ``url_limit`` is kept for API stability even though it caps URL +
+    body, not URL alone.
 
     Returns ``None`` when no chunking is needed (request as-is fits or
     no chunkable lists). Raises ``RequestTooLarge`` when:
@@ -341,12 +347,19 @@ def multi_value_chunked(
     quota_safety_floor: int | None = None,
 ) -> Callable[[_FetchOnce], _FetchOnce]:
     """Decorator that splits multi-value list params across sub-requests
-    so each URL fits ``url_limit`` bytes (defaults to
-    ``filters._WATERDATA_URL_BYTE_LIMIT``) and the cartesian-product
-    plan stays ≤ ``max_chunks`` sub-requests (defaults to
-    ``_DEFAULT_MAX_CHUNKS``). All defaults are resolved at call time so
-    tests/users that patch the module constants affect this decorator
-    uniformly.
+    so each sub-request fits ``url_limit`` bytes (URL + body, per
+    ``_request_bytes``; defaults to ``filters._WATERDATA_URL_BYTE_LIMIT``)
+    and the cartesian-product plan stays ≤ ``max_chunks`` sub-requests
+    (defaults to ``_DEFAULT_MAX_CHUNKS``). All defaults are resolved at
+    call time so tests/users that patch the module constants affect
+    this decorator uniformly.
+
+    ``url_limit`` caps total request bytes — the parameter name reflects
+    the dominant GET case where body is empty, but POST routes (e.g.
+    ``monitoring-locations`` via CQL2 JSON) are sized against URL + body
+    so they chunk correctly. Sizing against URL+body when the upstream
+    limit is URL-only is conservative-safe (no false passes) but can
+    over-chunk POSTs at the body's actual ceiling.
 
     Between sub-requests the wrapper reads ``x-ratelimit-remaining`` from
     each response. If it drops below ``quota_safety_floor`` (default