docs: copy-edit docstrings/comments and fix doc/code accuracy gaps

A review pass over the package's docstrings and inline comments for spelling,
grammar, clarity, and accuracy against the implementation.

Spelling & grammar:
- Typos ("Times series" -> "Time series", "datetme", "conatining", "indeces"
  -> "indices", "ESPSG" -> "EPSG", "NDAP" -> "NADP") plus articles,
  subject-verb agreement, duplicated words, and punctuation. codespell-clean
  ("gage" is the intentional USGS spelling).

R-language cruft -> Python:
- bbox `c(xmin,ymin,xmax,ymax)` -> `[xmin, ymin, xmax, ymax]`; "(numeric)
  vector"/"a vector of requested columns" -> list wording; `limit : numeric`
  -> `int`; `thresholds : numeric` -> `number`.

Accuracy (docs that disagreed with the code):
- Broken `Returns` cross-references to a nonexistent
  `dataretrieval.utils.Metadata` -> the real classes (`nwis.NWIS_Metadata`,
  `wqp.WQP_Metadata`, `utils.BaseMetadata`).
- get_monitoring_locations: three params typed `float` -> string/iterable.
- nwis.query_waterdata / query_waterservices: `service` examples listed values
  the functions reject -> the accepted sets; removed a duplicated `ssl_check`
  block and a `bBox` documented as a HUC.
- waterdata/utils: _switch_properties_id docstring described a dict (copied from
  _switch_arg_id); _handle_stats_nesting / _combine_chunk_frames notes
  corrected to match the code.
- get_time_series_metadata: replaced the stale `properties` list (copied from
  get_daily) with the collection's real queryables.
- Added missing pieces: `nadp` module deprecation note; `Raises` on
  `utils.query` and `streamstats.get_watershed` (plus its `format` param and
  dual return type); `get_channel` params; `get_stats_por` /
  `get_stats_date_range` `Returns` sections.
- Dropped bogus `Returns` blocks from `__init__` methods (they return None).

Code fixes surfaced by the review:
- Removed the non-functional `time` parameter from `get_monitoring_locations`
  and `get_time_series_metadata`. Their OGC collections have no `time`
  queryable (verified via the collections' queryables and a live 400), so
  `time=...` only produced an opaque server error; with no `**kwargs`, removal
  now yields a clear `TypeError`. The observation getters' `time` is valid and
  untouched.
- Fixed a malformed URL in the nwis seriesCatalogOutput deprecation warning
  (`waterdata.usgs.gov.nwis/qwdata` -> `waterdata.usgs.gov/nwis/qwdata`).

ruff check + ruff format clean; mypy --strict clean; tests pass; live-API
behavior verified.

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

Author: thodson-usgs

dataretrieval/__init__.py

@@ -11,7 +11,8 @@
     df, meta = nwis.get_dv(sites="05427718")
 
 Available service modules: ``waterdata``, ``wqp`` (Water Quality Portal),
-``nldi``, ``samples``, ``streamstats``, ``nadp``, and the deprecated ``nwis``.
+``nldi``, ``samples``, ``streamstats``, and the deprecated ``nwis`` and
+``nadp``.
 
 ``nldi`` requires geopandas (``pip install dataretrieval[nldi]``) and is
 imported on demand: ``from dataretrieval import nldi``.

dataretrieval/codes/states.py

@@ -1,4 +1,9 @@
-"""List of 2-digit state codes with commented full names."""
+"""State code lookups keyed by full state name.
+
+``state_codes`` maps each state name to its two-letter postal abbreviation
+(e.g. ``"Alabama": "al"``); ``fips_codes`` maps it to its two-digit FIPS
+code (e.g. ``"Alabama": "01"``).
+"""
 
 state_codes = {
     "Alabama": "al",

dataretrieval/nadp.py

@@ -1,11 +1,18 @@
 """
 Tools for retrieving data from the National Atmospheric Deposition Program
-(NADP) including the National Trends Network (NTN), the Mercury Deposition
-Network (MDN).
+(NADP), including the National Trends Network (NTN) and the Mercury
+Deposition Network (MDN).
+
+.. deprecated::
+
+    The ``nadp`` module is deprecated and will be removed from
+    ``dataretrieval`` on or after 2026-11-01. NADP is not a USGS data
+    source; please retrieve NADP data directly from
+    https://nadp.slh.wisc.edu/.
 
 National Trends Network
 -----------------------
-The  NTN provides long-term records of precipitation chemistry across the
+The NTN provides long-term records of precipitation chemistry across the
 United States. See https://nadp.slh.wisc.edu/ntn for more info.
 
 Mercury Deposition Network
@@ -89,7 +96,7 @@ def tif(self) -> bytes:
 
 
 def get_annual_MDN_map(measurement_type: str, year: str, path: str) -> str:
-    """Download a MDN map from NDAP.
+    """Download an MDN map from NADP.
 
     This function looks for a zip file containing gridded information at:
     https://nadp.slh.wisc.edu/maps-data/mdn-gradient-maps/.
@@ -143,7 +150,7 @@ def get_annual_NTN_map(
     year: str | None = None,
     path: str = ".",
 ) -> str:
-    """Download a NTN map from NDAP.
+    """Download an NTN map from NADP.
 
     This function looks for a zip file containing gridded information at:
     https://nadp.slh.wisc.edu/maps-data/ntn-gradient-maps/.
@@ -158,11 +165,11 @@ def get_annual_NTN_map(
 
     Parameters
     ----------
-    measurement : string
-        The measured constituent to return.
     measurement_type : string
         The type of measurement, 'conc', 'dep', or 'Precip', which represent
         concentration, deposition, or precipitation respectively.
+    measurement : string
+        The measured constituent to return.
     year : string
         Year as a string 'YYYY'
     path : string

dataretrieval/nldi.py

@@ -135,15 +135,15 @@ def get_basin(
     as_json: bool = False,
 ) -> gpd.GeoDataFrame | dict[str, Any]:
     """Gets the aggregated basin for the specified feature in WGS84 lat/lon
-    as GeoDataFrame or as JSON conatining a polygon geometry.
+    as GeoDataFrame or as JSON containing a polygon geometry.
 
     Parameters
     ----------
     feature_source: string, name of the feature source
     feature_id: string, identifier of the feature
     simplified: bool, simplified, default is True
     split_catchment: bool, split catchment, default is False
-    as_json: bool, return basin as JSON is set to True, otherwise return
+    as_json: bool, return basin as JSON if set to True, otherwise return
              as GeoDataFrame, default is False
 
     Returns
@@ -299,8 +299,8 @@ def get_features(
     return gdf
 
 
-# TODO: This function can cause timeout error for some data sources
-#  - may be we shouldn't provide this function?
+# TODO: This function can cause a timeout error for some data sources
+#  - maybe we shouldn't provide this function?
 def get_features_by_data_source(data_source: str) -> gpd.GeoDataFrame:
     """Gets all features found for the specified data source as
     points in WGS84 lat/long coordinates as GeoDataFrame containing a point geometry.

dataretrieval/nwis.py

@@ -251,8 +251,8 @@ def get_discharge_peaks(
     Returns
     -------
     df: ``pandas.DataFrame``
-        Times series data from the NWIS JSON
-    md: :obj:`dataretrieval.utils.Metadata`
+        Time series data from the NWIS JSON
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -331,7 +331,7 @@ def get_stats(
     -------
     df: ``pandas.DataFrame``
         Statistics data from the statistics service
-    md: :obj:`dataretrieval.utils.Metadata`
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     .. todo::
@@ -372,7 +372,7 @@ def query_waterdata(
     Parameters
     ----------
     service: string
-        Name of the service to query: 'site', 'stats', etc.
+        Name of the service to query: 'peaks' or 'ratings'.
     ssl_check: bool, optional
         If True, check SSL certificates, if False, do not check SSL,
         default is True
@@ -424,10 +424,7 @@ def query_waterservices(
     Parameters
     ----------
     service: string
-        Name of the service to query: 'site', 'stats', etc.
-    ssl_check: bool, optional
-        If True, check SSL certificates, if False, do not check SSL,
-        default is True
+        Name of the service to query: 'dv', 'iv', 'site', or 'stat'.
     ssl_check: bool, optional
         If True, check SSL certificates, if False, do not check SSL,
         default is True
@@ -437,7 +434,9 @@ def query_waterservices(
     Keyword Arguments
     ----------------
     bBox: string
-        7-digit Hydrologic Unit Code (HUC)
+        Bounding box of decimal latitude and longitude values, given as
+        west longitude, south latitude, east longitude, north latitude,
+        separated by commas
     startDT: string
         Start date (e.g., '2017-12-31')
     endDT: string
@@ -484,7 +483,7 @@ def get_dv(
     """
     Get daily values data from NWIS and return it as a ``pandas.DataFrame``.
 
-    .. note:
+    .. note::
 
         If no start or end date are provided, only the most recent record
         is returned.
@@ -511,8 +510,8 @@ def get_dv(
     Returns
     -------
     df: ``pandas.DataFrame``
-        Times series data from the NWIS JSON
-    md: :obj:`dataretrieval.utils.Metadata`
+        Time series data from the NWIS JSON
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -580,7 +579,7 @@ def get_info(
         A contiguous range of decimal latitude and longitude, starting with the
         west longitude, then the south latitude, then the east longitude, and
         then the north latitude with each value separated by a comma. The
-        product of the range of latitude range and longitude cannot exceed 25
+        product of the range of latitude and longitude cannot exceed 25
         degrees. Whole or decimal degrees must be specified, up to six digits
         of precision. Minutes and seconds are not allowed.
     countyCd: string or list of strings
@@ -625,7 +624,7 @@ def get_info(
     -------
     df: ``pandas.DataFrame``
         Site data from the NWIS web service
-    md: :obj:`dataretrieval.utils.Metadata`
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -645,7 +644,7 @@ def get_info(
             (
                 "WARNING: Starting in March 2024, the NWIS qw data endpoint is "
                 "retiring and no longer receives updates. For more information, "
-                "refer to https://waterdata.usgs.gov.nwis/qwdata and "
+                "refer to https://waterdata.usgs.gov/nwis/qwdata and "
                 "https://doi-usgs.github.io/dataRetrieval/articles/Status.html "
                 "or email CompTools@usgs.gov."
             ),
@@ -701,8 +700,8 @@ def get_iv(
     Returns
     -------
     df: ``pandas.DataFrame``
-        Times series data from the NWIS JSON
-    md: :obj:`dataretrieval.utils.Metadata`
+        Time series data from the NWIS JSON
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -734,7 +733,7 @@ def get_iv(
 
 
 def get_pmcodes(**kwargs: Any) -> NoReturn:
-    """Defunct: use ``get_reference_table(collection='parameter-codes')``."""
+    """Defunct: use ``waterdata.get_reference_table(collection='parameter-codes')``."""
     raise NameError(
         "`nwis.get_pmcodes` has been replaced "
         "with `get_reference_table(collection='parameter-codes')`."
@@ -762,7 +761,7 @@ def get_ratings(
     Parameters
     ----------
     site: string, optional, default is None
-        USGS site number.  This is usually an 8 digit number as a string.
+        USGS site number. This is usually an 8 digit number as a string.
         If the nwis parameter site_no is supplied, it will overwrite the site
         parameter
     file_type: string, default is "base"
@@ -773,11 +772,11 @@ def get_ratings(
     **kwargs: optional
         If supplied, will be used as query parameters
 
-    Return
-    ------
+    Returns
+    -------
     df: ``pandas.DataFrame``
         Formatted requested data
-    md: :obj:`dataretrieval.utils.Metadata`
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -819,11 +818,11 @@ def what_sites(
     **kwargs: optional
         Accepts the same parameters as :obj:`dataretrieval.nwis.get_info`
 
-    Return
-    ------
+    Returns
+    -------
     df: ``pandas.DataFrame``
         Formatted requested data
-    md: :obj:`dataretrieval.utils.Metadata`
+    md: :obj:`dataretrieval.nwis.NWIS_Metadata`
         A custom metadata object
 
     Examples
@@ -870,7 +869,7 @@ def get_record(
     Parameters
     ----------
     sites: string or list of strings, optional, default is None
-        List or comma delimited string of site.
+        List or comma delimited string of sites.
     start: string, optional, default is None
         Starting date of record (YYYY-MM-DD)
     end: string, optional, default is None
@@ -882,7 +881,7 @@ def get_record(
         If True, return data in wide format with multiple samples per row and
         one row per time, default is True
     datetime_index : bool, optional
-        If True, create a datetime index. default is True
+        If True, create a datetime index. Default is True
     state: string, optional, default is None
         full name, abbreviation or id
     service: string, default is 'iv'
@@ -893,7 +892,7 @@ def get_record(
         - 'peaks': discharge peaks
         - 'gwlevels': (defunct) use `waterdata.get_continuous`,
           `waterdata.get_daily`, or `waterdata.get_field_measurements`
-        - 'pmcodes': (defunct) use `get_reference_table`
+        - 'pmcodes': (defunct) use `waterdata.get_reference_table`
         - 'water_use': (defunct) no replacement available
         - 'ratings': get rating table
         - 'stat': get statistics
@@ -1021,9 +1020,7 @@ def _read_json(json: dict[str, Any]) -> pd.DataFrame:
     Returns
     -------
     df: ``pandas.DataFrame``
-        Times series data from the NWIS JSON
-    md: :obj:`dataretrieval.utils.Metadata`
-        A custom metadata object
+        Time series data from the NWIS JSON
 
     """
     all_site_dfs = []
@@ -1033,7 +1030,7 @@ def _read_json(json: dict[str, Any]) -> pd.DataFrame:
     ]
 
     # create a list of indexes for each change in site no
-    # for example, [0, 21, 22] would be the first and last indeces
+    # for example, [0, 21, 22] would be the first and last indices
     index_list = [0]
     index_list.extend(
         [i + 1 for i, (a, b) in enumerate(zip(site_list[:-1], site_list[1:])) if a != b]
@@ -1127,7 +1124,7 @@ class NWIS_Metadata(BaseMetadata):
     ----------
     url : str
         Response url
-    query_time: datetme.timedelta
+    query_time: datetime.timedelta
         Response elapsed time
     header: httpx.Headers
         Response headers
@@ -1152,11 +1149,6 @@ def __init__(self, response: httpx.Response, **parameters: Any) -> None:
         parameters: unpacked dictionary
             Unpacked dictionary of the parameters supplied in the request
 
-        Returns
-        -------
-        md: :obj:`dataretrieval.nwis.NWIS_Metadata`
-            A ``dataretrieval`` custom :obj:`dataretrieval.nwis.NWIS_Metadata` object.
-
         """
         super().__init__(response)
 
@@ -1177,8 +1169,8 @@ def site_info(self) -> tuple[pd.DataFrame, BaseMetadata] | None:
         ``huc``, ``countyCd`` or ``bBox`` (``site_no`` is preferred over
         ``sites`` if both are present); ``None`` otherwise.
 
-        Return
-        ------
+        Returns
+        -------
         df: ``pandas.DataFrame``
             Formatted requested data from calling `nwis.what_sites`
         md: :obj:`dataretrieval.nwis.NWIS_Metadata`