dataretrieval-python/dataretrieval/__init__.py at f18d310278f8a55a5815c06a050dfea4128f40ed · DOI-USGS/dataretrieval-python · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
"""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),
``wateruse`` (NWDC water-use data), ``nldi``, ``streamstats``, and the
deprecated ``nwis``.

``nldi`` requires geopandas (``pip install dataretrieval[nldi]``) and is
imported on demand: ``from dataretrieval import nldi``.

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`. A large
request interrupted mid-stream raises :class:`dataretrieval.ChunkInterrupted`,
whose ``.call.resume()`` continues from the work already completed.
"""

from importlib.metadata import PackageNotFoundError, version

try:
    __version__ = version("dataretrieval")
except PackageNotFoundError:
    __version__ = "version-unknown"

from dataretrieval.exceptions import (
    DataRetrievalError,
    HTTPError,
    NetworkError,
    NoSitesError,
    RateLimited,
    RequestTooLarge,
    ServiceUnavailable,
    TransientError,
    Unchunkable,
    URLTooLong,
)

# Parallel-chunks control (a context manager). Defined with the chunker in
# ``dataretrieval.ogc.chunking``; surfaced here for a stable public path
# ``from dataretrieval import parallel_chunks``.
from dataretrieval.ogc.chunking import parallel_chunks

# Resumable chunk-interruption exceptions. They are defined in
# ``dataretrieval.ogc.interruptions`` rather than ``dataretrieval.exceptions``
# because they carry pandas/httpx state and a resumable ``ChunkedCall`` handle,
# which would pull heavy dependencies into the lightweight exceptions module.
# Surfaced here so callers get a stable public path:
# ``from dataretrieval import ChunkInterrupted``.
from dataretrieval.ogc.interruptions import (
    ChunkInterrupted,
    QuotaExhausted,
    ServiceInterrupted,
)

from . import (
    exceptions,
    ngwmn,
    nwis,
    streamstats,
    utils,
    waterdata,
    wateruse,
    wqp,
)

__all__ = [
    # service modules
    "ngwmn",
    "nwis",
    "streamstats",
    "utils",
    "waterdata",
    "wateruse",
    "wqp",
    # error taxonomy (canonical home: ``dataretrieval.exceptions``), re-exported
    # so callers can ``except dataretrieval.DataRetrievalError``
    "exceptions",
    "DataRetrievalError",
    "HTTPError",
    "NetworkError",
    "NoSitesError",
    "RateLimited",
    "RequestTooLarge",
    "ServiceUnavailable",
    "TransientError",
    "URLTooLong",
    "Unchunkable",
    # resumable chunk-interruption exceptions (defined in ogc.interruptions)
    "ChunkInterrupted",
    "QuotaExhausted",
    "ServiceInterrupted",
    # parallel-chunks control (defined in ogc.chunking)
    "parallel_chunks",
    "__version__",
]