Metadata-Version: 2.4
Name: pyo_oracle
Version: 1.0.0
Summary: Python client for the Bio-ORACLE ERDDAP server.
Author-email: Vini Salazar <vinicius.salazar@unimelb.edu.au>
License: MIT
Project-URL: Homepage, https://github.com/bio-oracle/pyo_oracle
Project-URL: Documentation, https://bio-oracle.github.io/pyo_oracle/
Project-URL: Bug Tracker, https://github.com/bio-oracle/pyo_oracle/issues
Keywords: bio-oracle,erddap,oceanography,marine,climate,sdm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Oceanography
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: erddapy>=2.2
Requires-Dist: pandas>=2.0
Requires-Dist: httpx>=0.27
Provides-Extra: xarray
Requires-Dist: xarray>=2023.1.0; extra == "xarray"
Requires-Dist: netCDF4>=1.6; extra == "xarray"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# pyo_oracle

**Python client for the [Bio-ORACLE](https://bio-oracle.org/) ERDDAP server.**

Discover, inspect, subset, download, and load Bio-ORACLE marine environmental
layers (temperature, salinity, nutrients, sea ice, and more) from Python.
`pyo_oracle` is the Python counterpart of the R package
[`biooracler`](https://github.com/bio-oracle/biooracler) and is built on
[`erddapy`](https://github.com/ioos/erddapy).

📖 **Documentation:** <https://bio-oracle.github.io/pyo_oracle/>

## Installation

```bash
# With pip
pip install pyo-oracle

# Load layers as xarray (optional extra)
pip install "pyo-oracle[xarray]"

# With conda
conda create -n pyo_oracle conda-forge::pyo-oracle
```

## Quick start

```python
import pyo_oracle as pyo

# 1. List available layers (filter by search term, variable, scenario, depth, ...)
pyo.list_layers(search="Temperature")

# 2. Inspect a layer: dimension ranges + variables and units
pyo.info_layer("thetao_baseline_2000_2019_depthsurf")

# 3. Build constraints from friendly bounds (no hand-written dicts)
constraints = pyo.build_constraints(
    "thetao_baseline_2000_2019_depthsurf",
    time=("2000-01-01T00:00:00Z", "2010-01-01T00:00:00Z"),
    latitude=(0, 10),
    longitude=(0, 10),
)

# 4a. Load directly into memory (pandas or xarray)
df = pyo.load_layer(
    "thetao_baseline_2000_2019_depthsurf",
    constraints=constraints,
    variables=["thetao_mean"],
)
ds = pyo.load_layer(
    "thetao_baseline_2000_2019_depthsurf",
    constraints=constraints,
    fmt="xarray",
)

# 4b. Or download to a file (NetCDF by default)
pyo.download_layers(
    "thetao_baseline_2000_2019_depthsurf",
    constraints=constraints,
    variables=["thetao_mean"],
)

# 5. See local data
pyo.list_local_data()
```

## Key functions

| Function | Purpose |
|----------|---------|
| `list_layers` | List/filter available layers |
| `info_layer` | Inspect a layer's dimensions and variables |
| `build_constraints` | Build griddap constraints from `(min, max)` bounds + strides |
| `load_layer` | Load a layer into memory (`pandas` or `xarray`) |
| `download_layers` | Download a layer (NetCDF/CSV), optionally a variable subset |
| `list_local_data` | List downloaded files |

## Contributing

See [`CLAUDE.md`](CLAUDE.md) for the dev setup, testing, and release flow.
Please open an issue if you experience any problems.
