Metadata-Version: 2.4
Name: gagely
Version: 0.1.0
Summary: Tools for retrieving US weather, streamflow, and rainfall gage data from services such as Contrail and USGS.
Author-email: Gyan Basyal <gyanbasyalz@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Gyan Basyal
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: contrail,dss,gage,hydrology,rainfall,streamflow,usgs,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dataretrieval>=1.0
Requires-Dist: pandas>=1.5
Requires-Dist: pydsstools>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# gagely

`gagely` provides Python utilities for retrieving US weather, streamflow,
rainfall, and related gage data from services such as Contrail and USGS, with
helpers for writing time-series data to HEC-DSS through `pydsstools`.

The Python import package is named `gagely`.

## Installation

Install from a local checkout:

```console
python -m pip install .
```

For development:

```console
python -m pip install -e ".[dev]"
```

## Versioning

Package versions are derived from git tags with `setuptools-scm`.

Use tags such as:

```console
git tag 0.1.0
```

Then build/install from that tagged checkout.

## Basic Usage

### USGS

The USGS package wraps `dataretrieval.waterdata` and adds DSS-write
helpers. Set the personal access token once per process, then go
through the `daily` or `continuous` submodule:

```python
from gagely.usgs import configure_usgs, daily, continuous

configure_usgs("YOUR_USGS_API_KEY")
```

**Daily values to DSS** (period-mean, written as a regular `1DAY`
series — each row is shifted to the period-end timestamp DSS expects):

```python
daily.flow_to_dss(
    output="flow.dss",
    site_id="08354900",
    sdate="2000-01-01",
)
```

**Continuous (instantaneous) values to DSS** (sampling interval is
inferred per site from the data, e.g. `15MIN` for a typical 15-minute
gage; internal time gaps are filled with the no-data sentinel
`UNDEFINED`):

```python
continuous.to_dss(
    output="iv.dss",
    site_id="12362500",
    param="flow",
    sdate="2026-01-01",
)
```

**Returning a DataFrame instead of writing to DSS:**

```python
df_daily = daily.get_flow("08354900", sdate="2020-01-01")
df_iv    = continuous.get_flow("12362500", sdate="2026-01-01")
```

`site_id` accepts a single id, a list, or a dict mapping label → id
(the dict keys become the DSS APART). Bare USGS ids (`"08354900"`) and
prefixed ones (`"USGS-08354900"`) are both accepted.

Each submodule exposes the same helper set: `get_flow`, `get_stage`,
`to_dss`, `flow_to_dss`, `stage_to_dss`, plus the canonical
endpoint-name function (`get_daily` or `get_continuous`) for arbitrary
parameter / statistic combinations. The endpoint-name functions are
also re-exported at the package level: `from gagely.usgs import
get_daily, get_continuous`.

### Contrail

```python
from gagely.contrail import configure_contrail, fetch_to_dss

configure_contrail(url="https://contrail.example.com", system_key="YOUR_KEY")
fetch_to_dss(
    output="rainfall.dss",
    sensor_class=10,
    sdate="2000-01-01",
    or_site_id=200,
)
```

Resolve gage names to Contrail `or_site_id` values before fetching:

```python
from gagely.contrail import get_site_metadata, validate_gages

site_meta = get_site_metadata()
gage_to_or_id = validate_gages(
    ["Station 2", "City Hall"],
    site_meta,
)
```

**Site and sensor metadata** can also be queried directly, filtered by
`site_id` or `or_site_id` (and, for sensors, `sensor_class`):

```python
from gagely.contrail import get_site_metadata, get_sensor_metadata

# Omit site_id / or_site_id to get metadata for every site/sensor
# accessible under the configured URL/system key.
site_meta = get_site_metadata(or_site_id="200")
sensor_meta = get_sensor_metadata(or_site_id="200", sensor_class=10)
```

Both return a list of dicts, one per `<row>` in the XML response (each
dict maps child-element tag → text).

## Contributing

Bug reports, feature requests, and pull requests are welcome — see
[CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This project follows the
[Code of Conduct](CODE_OF_CONDUCT.md).

## License

`gagely` is licensed under the [MIT License](LICENSE).
