From ca5926c430440cf3496319908b277e3d9ee05df3 Mon Sep 17 00:00:00 2001
From: thodson-usgs <thodson@usgs.gov>
Date: Sun, 31 May 2026 21:55:08 -0400
Subject: [PATCH] refactor(api)!: expose service submodules, not a flattened
 top-level namespace

`dataretrieval/__init__.py` star-imported every service module, flattening all
their public functions into the top-level package namespace. That:
  - leaked one large, ambiguous namespace (`dataretrieval.get_dv`,
    `dataretrieval.get_results`, ...), and
  - silently collided on names defined by more than one service: `get_ratings`
    (nwis vs waterdata) and `what_sites` (nwis vs wqp) resolved to whichever
    module was star-imported last; the other was shadowed.

Replace the star-imports with submodule imports, so callers reach each service
through its own module -- the pattern the README, the docs (per-module
autodoc), and the tests already use:

    from dataretrieval import waterdata
    df, meta = waterdata.get_ratings(...)

    from dataretrieval import nwis
    df, meta = nwis.get_ratings(...)

`dataretrieval.<name>` and `from dataretrieval import <name>` still work for
every service module, and `__version__` is unchanged. `nldi` remains
import-on-demand (it pulls in the optional geopandas dependency). The collision
is now impossible -- each `get_ratings` / `what_sites` lives only under its
module.

BREAKING CHANGE: top-level function access (e.g. `dataretrieval.get_dv`) is
removed; use the service module (`dataretrieval.nwis.get_dv`). Exception and
helper classes likewise move under their modules (e.g.
`dataretrieval.utils.NoSitesError`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dataretrieval/__init__.py | 46 +++++++++++++++++++++++++++++++++------
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/dataretrieval/__init__.py b/dataretrieval/__init__.py
index ca302ce0..cca267f8 100644
--- a/dataretrieval/__init__.py
+++ b/dataretrieval/__init__.py
@@ -1,3 +1,22 @@
+"""Discover and retrieve water data from U.S. federal hydrologic web services.
+
+Access each service through its submodule::
+
+    from dataretrieval import waterdata  # modern USGS Water Data API
+
+    df, meta = waterdata.get_daily(monitoring_location_id="USGS-05427718")
+
+    from dataretrieval import nwis  # legacy NWIS services
+
+    df, meta = nwis.get_dv(sites="05427718")
+
+Available service modules: ``waterdata``, ``wqp`` (Water Quality Portal),
+``nldi``, ``samples``, ``streamstats``, ``nadp``, and the deprecated ``nwis``.
+
+``nldi`` requires geopandas (``pip install dataretrieval[nldi]``) and is
+imported on demand: ``from dataretrieval import nldi``.
+"""
+
 from importlib.metadata import PackageNotFoundError, version
 
 try:
@@ -5,10 +24,23 @@
 except PackageNotFoundError:
     __version__ = "version-unknown"
 
-from dataretrieval.nadp import *
-from dataretrieval.nwis import *
-from dataretrieval.samples import *
-from dataretrieval.streamstats import *
-from dataretrieval.utils import *
-from dataretrieval.waterdata import *
-from dataretrieval.wqp import *
+from . import (
+    nadp,
+    nwis,
+    samples,
+    streamstats,
+    utils,
+    waterdata,
+    wqp,
+)
+
+__all__ = [
+    "nadp",
+    "nwis",
+    "samples",
+    "streamstats",
+    "utils",
+    "waterdata",
+    "wqp",
+    "__version__",
+]