refactor(api)!: access services via submodules, not the flattened top-level namespace

[thodson-usgs]

Problem

dataretrieval/__init__.py star-imports every service module:

from dataretrieval.nwis import *
from dataretrieval.waterdata import *
from dataretrieval.wqp import *
...

This flattens all of their public functions into the top-level package namespace, so dataretrieval.get_dv, dataretrieval.get_results, etc. all resolve at the top level. Two problems:

1. One large, ambiguous top-level namespace — every service's functions share a single flat namespace.
2. Silent name collisions — get_ratings is defined in both nwis and waterdata, and what_sites in both nwis and wqp. With import *, whichever module is imported last wins and the other is silently shadowed. (mypy flags this as an incompatible re-import — see chore(typing): set up mypy and tighten the package to mypy --strict #314, which only suppressed it.)

Change

Expose the service submodules instead of flattening their contents:

from . import nadp, nwis, samples, streamstats, utils, waterdata, wqp

Callers go through the owning module — the pattern the README, docs, and tests already use:

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

from dataretrieval import nwis
df, meta = nwis.get_ratings(...)        # legacy — now unambiguous

• dataretrieval.<module> and from dataretrieval import <module> work for every service.
• __version__ is unchanged.
• nldi stays import-on-demand (it requires the optional geopandas), exactly as before — from dataretrieval import nldi.
• The get_ratings / what_sites collision is now structurally impossible — each lives only under its module. This resolves at the source what chore(typing): set up mypy and tighten the package to mypy --strict #314 had to suppress with a # type: ignore.

Breaking change

Top-level function access is removed:

Before	After
dataretrieval.get_dv(...)	dataretrieval.nwis.get_dv(...)
dataretrieval.get_results(...)	dataretrieval.wqp.get_results(...)
dataretrieval.get_ratings(...)	dataretrieval.waterdata.get_ratings(...) (or nwis)
dataretrieval.NoSitesError	dataretrieval.utils.NoSitesError

If a softer migration is preferred, a module-level __getattr__ shim could keep the old names working for one release with a DeprecationWarning — happy to add that instead of the hard removal.

Verification

• New access pattern asserted directly: top-level functions are gone; both get_ratings and both what_sites are reachable via their modules; from dataretrieval import waterdata and explicit nldi import work; __version__ preserved.
• Full test suite: 469 passed, 2 skipped — the tests already use module-qualified access, so nothing needed changing.
• README and docs (per-module automodule directives) already use this pattern.

🤖 Generated with Claude Code