"""The settings the Water Data adapter reads -- its configuration profile.
A file of its own because :mod:`dataretrieval.waterdata` is a package rather than a
single module; every other adapter declares its class in the module a caller imports.
Either way the point is the same: a setting's definition is in the module that reads it,
so adding one no longer edits a service-neutral file (ADR 0011).
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import ClassVar
from dataretrieval.configuration import (
BaseConfiguration,
_Chunked,
_Concurrent,
_Redirectable,
_register,
_Retrying,
_Versioned,
)
__all__ = ["WaterdataConfiguration"]
[docs]
@dataclass(frozen=True)
class WaterdataConfiguration(
_Chunked, _Concurrent, _Redirectable, _Retrying, _Versioned, BaseConfiguration
):
"""Settings for Water Data calls alone.
Pass one to :func:`dataretrieval.configure` to narrow a setting to this
adapter, leaving every other adapter on whatever the sources below it
resolve::
with dataretrieval.configure(WaterdataConfiguration(concurrency=8)):
df, md = waterdata.get_daily(monitoring_location_id=sites)
Parameters
----------
retries : int, optional
Retries attempted after a transient failure; ``0`` disables retrying.
stall_timeout : float, optional
Seconds a call may go without receiving any data before retrying stops.
base_url : str, optional
Root to send Water Data requests to, instead of the service's own. The package
appends its own paths, so one value redirects all four families together --
``/ogcapi/<api_version>``, ``/samples-data``, ``/statistics/v0`` and
``/stac/v0``. Code only: setting it in the configuration file or through an
environment variable raises ``ConfigurationError``. The API key is scoped to
the host that accepts it, so a redirected call sends no key.
api_version : str, optional
Version of the Water Data API to request, as the segment of its path:
``"v1"``, which this release is written against, or ``"v0"`` while the
service keeps it online (until June 2027). It replaces that one segment,
so the Samples, Statistics and STAC families -- versioned separately, with
no v1 -- are unaffected. Set it here or in the ``[waterdata]`` table of
the configuration file. Under another version, getters return that
version's columns as the service sends them.
concurrency : int or str, optional
Cap on simultaneous sub-requests, or ``"unbounded"``.
parallel_chunks : int, optional
Baseline fan-out for multi-value queries. Each sub-request spends
rate-limit quota, so raise it only for pulls you know are large.
"""
# The settings this service reads, named by the groups they come from:
# every adapter's retry settings, a redirectable base, a versioned API, and
# -- because Water Data queries divide along a URL byte budget and are
# executed concurrently -- both fan-out settings. Each group declares the
# setting itself once, in :mod:`dataretrieval.configuration`, which also
# defines its grammar and its coercion.
adapter: ClassVar[str] = "waterdata"
_register(WaterdataConfiguration)