Metadata-Version: 2.4
Name: usdata
Version: 0.9.0
Summary: Unified Python SDK and CLI for discovering, fetching, and tracking provenance of U.S. public scientific data
Keywords: noaa,usgs,nasa,open-data,scientific-data,provenance
Author: Jake Van Slyke
Author-email: Jake Van Slyke <jakervanslyke@gmail.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.18
Requires-Dist: xarray>=2025.1 ; extra == 'netcdf'
Requires-Dist: h5netcdf[h5py]>=1.8.1 ; extra == 'netcdf'
Requires-Dist: pandas>=3.0 ; extra == 'pandas'
Requires-Dist: xradar>=0.12.0 ; extra == 'radar'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/jakeryderv/usdata
Project-URL: Repository, https://github.com/jakeryderv/usdata
Provides-Extra: netcdf
Provides-Extra: pandas
Provides-Extra: radar
Description-Content-Type: text/markdown

# usdata

Discover U.S. scientific datasets, fetch their files, and keep a reproducible
record of where every input came from. Use the same Python SDK or CLI across
supported NOAA and USGS datasets.

**Pre-alpha.** These docs describe the current source checkout. Features marked
**Unreleased** require a source installation; consult the
[changelog](CHANGELOG.md) for published versions. Other providers are planned.

## Start here

```sh
pip install usdata
usdata search precipitation --location Oklahoma
usdata info noaa:ghcn-daily
```

Search uses a curated registry. Fetching contacts the upstream service; readers
open the resulting local files. Provenance and manifests connect those steps.

- [Quick start and documentation](docs/index.md)
- [Fetch and analyze data](docs/guides/fetch-and-analyze.md)
- [Runnable examples with saved outputs](examples/README.md)
- [Readers](docs/reference/readers.md) and [reproducible manifests](docs/reference/manifests.md)

## Providers

<!-- registry:start -->
| Provider | Available | Stub | Planned | Next up (unassigned) | Datasets |
|---|---:|---:|---:|---|---|
| [NOAA](docs/providers/noaa.md) | 6 | 0 | 23 | — | `ghcn-daily`, `gsom`, `storm-events`, `nexrad-level2`, `goes-abi`, `coastwatch-sst`, +23 planned |
| [USGS](docs/providers/usgs.md) | 1 | 0 | 2 | — | `water-daily`, +2 planned |
| [Census Bureau](docs/providers/census.md) | 0 | 0 | 1 | — | +1 planned |
| [EPA](docs/providers/epa.md) | 0 | 0 | 1 | — | +1 planned |
| [FEMA](docs/providers/fema.md) | 0 | 0 | 1 | — | +1 planned |
| [NASA](docs/providers/nasa.md) | 0 | 0 | 1 | — | +1 planned |
| [USDA](docs/providers/usda.md) | 0 | 0 | 1 | — | +1 planned |

Available datasets are in `code`, stubs in _italics_; planned ones are counted. Available means implemented in this source checkout; consult the [releases](https://github.com/jakeryderv/usdata/releases) for published support. Provider pages link access notes to the generated dataset catalog; [the roadmap](docs/roadmap.md) explains future priorities.
<!-- registry:end -->

## Development

Requires [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/).

`just setup` uses the tested Python 3.14.7 pin in `.python-version`. Older Linux
uv Python 3.14 builds can crash during NumPy array operations; see
[the upstream fix](https://github.com/astral-sh/python-build-standalone/issues/991).

```sh
git clone https://github.com/jakeryderv/usdata && cd usdata
just setup     # install toolchain and dependencies
just test      # all offline tests
just check     # format, lint, typecheck, offline tests, generated docs, release notices
just check-pandas  # install the CSV extra and run the same checks
just check-radar   # install the radar extra and run the same checks
just check-netcdf  # install the NetCDF4 extra and run the same checks
just notebooks    # launch the optional Jupyter examples environment
just run-notebooks # execute notebooks live in fresh kernels and temporary caches
just docs-serve # build and preview the documentation locally, with reload
just check-docs # validate generated content and build the site strictly
just build     # build wheel and sdist
just smoke     # exercise core and pandas wheel installations outside the checkout
just run search radar
```

Offline tests mechanically block network connections. Tests that hit
live services run with `just test-live`; see [testing levels and organization](docs/testing.md). CI checks Python 3.11 and 3.14 on
Linux with core-only, pandas, radar, and NetCDF dependency profiles. Installed-wheel
checks cover all four profiles on Linux, macOS, and Windows. The full offline and
live-service suites run on Linux. `just setup` restores a core-only development
environment; the `check-pandas`, `check-radar`, and `check-netcdf` commands install
their respective extras.

Releases: `just release minor` opens a version-bump PR; merging it publishes
to PyPI and creates the tag and GitHub release. See
[docs/versioning.md](docs/versioning.md).

See [provider access notes](docs/providers/README.md),
[docs/architecture.md](docs/architecture.md) for how the pieces fit,
[architecture decisions](docs/adr/README.md) for why, and [CONTRIBUTING.md](CONTRIBUTING.md) to add
a dataset.

## License

[Apache-2.0](LICENSE).
