refactor(errors)!: a lean, idiomatic DataRetrievalError taxonomy

NEWS.md

@@ -1,3 +1,5 @@
+**06/03/2026:** The request-error hierarchy is now unified. Every module (`nwis`, `wqp`, `nldi`, `waterdata`, `nadp`, `streamstats`) raises a subclass of `dataretrieval.DataRetrievalError` on a failed request, so a single `except dataretrieval.DataRetrievalError` spans them all. An HTTP error status surfaces as an `HTTPError` carrying `.status_code` (inspect it to branch on a specific code); the retryable 429/5xx subset is `TransientError` (`RateLimited` / `ServiceUnavailable`, carrying `.retry_after`); and a request too large to satisfy is a `RequestTooLarge` (`URLTooLong` for an over-long single request, `Unchunkable` when the Water Data chunker cannot split a call small enough). Connection-level failures (timeouts, DNS, refused connections) are wrapped as a `NetworkError`, with the underlying `httpx` exception on `__cause__`. Every `DataRetrievalError` also exposes `.status_code` (`None` when there is no HTTP status), `.retry_after`, and `.retryable`, so a single `except dataretrieval.DataRetrievalError as e` clause can branch on the status or retry transient failures without knowing the concrete subclass. **Breaking change:** these exceptions no longer multiply-inherit a built-in — code that caught request failures with `except ValueError` or `except RuntimeError` should switch to `except dataretrieval.DataRetrievalError` (or a specific subclass). A no-data result is **not** an error: the modern getters (`waterdata`, `wqp`, `nldi`) return an empty DataFrame when nothing matches. Only the deprecated `nwis` (waterservices) path still raises `NoSitesError` on no data.
+
 **05/17/2026:** The OGC `waterdata` getters (`get_daily`, `get_continuous`, `get_field_measurements`, and the rest of the multi-value-capable functions) now transparently chunk requests whose URLs would otherwise exceed the server's ~8 KB byte limit.
 
 **05/16/2026:** Fixed silent truncation in the paginated `waterdata` request loops (`_walk_pages` and `get_stats_data`). Mid-pagination failures (HTTP 429, 5xx, network error) were previously swallowed — pagination would quietly stop and the function would return whatever rows it had collected, leaving callers with truncated DataFrames they had no way to detect. The loops now status-check every page like the initial request and raise `RuntimeError` on any failure, with the upstream exception chained as `__cause__` and a short menu of recovery actions (wait and retry, reduce the request, or obtain an API token) in the message. **Behavior change**: callers that previously consumed partial DataFrames on transient upstream blips will now see an exception; retry the call (possibly with a smaller `limit` or narrower query).

dataretrieval/__init__.py

@@ -17,8 +17,9 @@
 ``nldi`` requires geopandas (``pip install dataretrieval[nldi]``) and is
 imported on demand: ``from dataretrieval import nldi``.
 
-Every request failure raises a subclass of :class:`dataretrieval.DataRetrievalError`;
-the taxonomy lives in ``dataretrieval.exceptions``.
+A failed request raises a subclass of :class:`dataretrieval.DataRetrievalError`
+(the taxonomy lives in ``dataretrieval.exceptions``); connection-level failures
+(timeouts, DNS) are wrapped as :class:`dataretrieval.NetworkError`.
 """
 
 from importlib.metadata import PackageNotFoundError, version
@@ -29,10 +30,10 @@
     __version__ = "version-unknown"
 
 from dataretrieval.exceptions import (
-    BadRequestError,
     DataRetrievalError,
+    HTTPError,
+    NetworkError,
     NoSitesError,
-    NotFoundError,
     RateLimited,
     RequestTooLarge,
     ServiceUnavailable,
@@ -64,10 +65,10 @@
     # error taxonomy (canonical home: ``dataretrieval.exceptions``), re-exported
     # so callers can ``except dataretrieval.DataRetrievalError``
     "exceptions",
-    "BadRequestError",
     "DataRetrievalError",
+    "HTTPError",
+    "NetworkError",
     "NoSitesError",
-    "NotFoundError",
     "RateLimited",
     "RequestTooLarge",
     "ServiceUnavailable",