Merge pull request #12 from bio-oracle/release/v1.0.0

Release v1.0.0: modernize deps + biooracler parity

Author: vinisalazar

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pypi-publish.yml

@@ -22,35 +22,31 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v3
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.12"
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
-        pip install .
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+        python -m pip install -e ".[dev,xarray]"
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
+    - name: Test with pytest (unit tests only)
       run: |
-        pytest
+        pytest -m "not integration"
   deploy:
     runs-on: ubuntu-latest
     needs:
       - test
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v5
       with:
         python-version: '3.x'
     - name: Install dependencies

.github/workflows/python-app.yml

@@ -1,45 +1,62 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+# Install Python dependencies, lint, and run tests across supported versions.
+# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
 
 name: Python application
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 permissions:
   contents: read
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v3
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest pytest-cov
-        python -m pip install -e .
-        if [ -f requirements.txt ]; then python -m pip install -r requirements.txt; fi
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with coverage
+        python -m pip install -e ".[dev,xarray]"
+    - name: Lint with ruff
+      run: ruff check pyo_oracle tests
+    - name: Lint with flake8 (syntax errors only)
+      run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+    - name: Test with coverage (unit tests only)
       run: |
-        python -m pytest --cov=pyo_oracle --cov-report=html --cov-report=term-missing tests/
+        python -m pytest -m "not integration" \
+          --cov=pyo_oracle --cov-report=html --cov-report=term-missing tests/
     - name: Upload coverage report
+      if: matrix.python-version == '3.12'
       uses: actions/upload-artifact@v4
       with:
         name: coverage-report
         path: htmlcov/
+
+  integration:
+    # Tests that hit the live Bio-ORACLE ERDDAP server. Blocking: a failure here
+    # gates the PR.
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[dev,xarray]"
+    - name: Run integration tests
+      run: python -m pytest -m integration tests/

.gitignore

@@ -6,8 +6,11 @@
 **/.DS_Store
 **/*.ini
 build/
+dist/
 pyo_oracle/data
 .coverage
 coverage.*
 htmlcov/
 .venv/
+.pytest_cache/
+site/

CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-02
+
+First stable release. Modernizes dependencies, reaches feature parity with the
+R package [`biooracler`](https://github.com/bio-oracle/biooracler), and adds new
+functionality.
+
+### Added
+
+- **`info_layer(dataset_id)`** — inspect a layer's dimension ranges (time,
+  latitude, longitude, depth) and its variables with units and long names
+  (parity with `biooracler::info_layer`).
+- **`load_layer(dataset_id, ...)`** — load a layer directly into memory as a
+  `pandas.DataFrame` (default) or `xarray.Dataset` (`fmt="xarray"`).
+- **`build_constraints(...)`** — build griddap constraints from friendly
+  `(min, max)` bounds and strides, with optional validation against the
+  dataset's real ranges.
+- **`variables=`** argument on `download_layers` to download a subset of
+  variables.
+- Optional dependency extras: `xarray`, `docs`, `dev`.
+- MkDocs Material documentation site (quickstart, tutorials, API reference) with
+  a GitHub Pages deploy workflow.
+- `respx` and `ruff` to the dev toolchain; `integration` pytest marker to
+  separate live-server tests from offline unit tests.
+- `CLAUDE.md` contributor guide and this changelog.
+
+### Changed
+
+- Declared explicit dependencies (`erddapy>=2.2`, `pandas>=2.0`, `httpx>=0.27`)
+  and raised the Python floor to `>=3.9`.
+- Refactored griddap server construction into a single shared
+  `_build_griddap_server` helper used by downloads, in-memory loading, and
+  metadata lookups.
+- CI now tests a Python 3.9–3.13 matrix, lints with ruff, and runs offline unit
+  tests by default with a separate (non-blocking) integration job.
+
+### Fixed
+
+- Replaced unsafe `eval()` parsing of the `skip_confirmation` config value with a
+  safe boolean coercion (`_as_bool`), which also handles strings like `"false"`.
+- Hardened handling of erddapy's private `_constraints_original` attribute.
+
+## [0.2.0]
+
+- Previous release.

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## What this is
+
+`pyo_oracle` is the Python client for the **Bio-ORACLE** ERDDAP server
+(<https://erddap.bio-oracle.org/erddap/>). It is the Python counterpart of the R
+package [`biooracler`](https://github.com/bio-oracle/biooracler) and is built on
+top of [`erddapy`](https://github.com/ioos/erddapy).
+
+## Layout
+
+- `pyo_oracle/__init__.py` — public namespace; re-exports the API.
+- `pyo_oracle/main.py` — public functions: `list_layers`, `info_layer`,
+  `load_layer`, `download_layers`, `list_local_data`.
+- `pyo_oracle/utils.py` — internals: `_build_griddap_server` (the single shared
+  griddap setup path), `_layer_info`, `_layer_dataframe`, `build_constraints`,
+  `_as_bool`, download helpers.
+- `pyo_oracle/_config.py` — configparser-based config (data dir, server URL,
+  `skip_confirmation`). `config.ini` is generated and git-ignored.
+- `tests/` — `test_utils.py` (offline), `test_main.py` (mostly live), `test_config.py`.
+- `docs/` + `mkdocs.yml` — MkDocs Material site (mkdocstrings API ref).
+
+## Public API parity with `biooracler`
+
+`list_layers`, `info_layer`, `download_layers` mirror the R package. Python adds
+`load_layer` (in-memory pandas/xarray) and `build_constraints` (friendly
+subsetting helper).
+
+## Dev environment
+
+All development happens in the conda env named **`pyo_oracle`**:
+
+```bash
+conda env create -n pyo_oracle -f environment-dev.yaml   # or `mamba`
+conda activate pyo_oracle
+pip install -e ".[dev,xarray,docs]"
+```
+
+## Tests
+
+Two kinds, separated by the `integration` marker:
+
+```bash
+pytest -m "not integration"   # offline unit tests (fast, used in CI by default)
+pytest                        # full suite incl. tests that hit the live server
+pytest -m integration         # only the live-server tests
+```
+
+The exit goal for changes is a **fully green `pytest`** in the `pyo_oracle` env.
+
+## Lint & docs
+
+```bash
+ruff check pyo_oracle tests
+mkdocs serve          # live preview
+mkdocs build --strict # must pass (CI deploys to GitHub Pages)
+```
+
+## Release flow
+
+1. Bump `version` in `pyproject.toml` and update `CHANGELOG.md`.
+2. Ensure `pytest`, `ruff`, and `mkdocs build --strict` pass.
+3. `python -m build` and inspect the artifacts.
+4. Push a tag — `.github/workflows/pypi-publish.yml` builds and publishes to PyPI
+   (package name `pyo-oracle`).
+
+## Gotchas
+
+- **erddapy private API**: `_build_griddap_server` relies on
+  `ERDDAP._constraints_original`. It is guarded with `getattr`/`hasattr` but
+  watch this if bumping erddapy (verified against erddapy 3.2.x).
+- Requires `erddapy>=2.2`, `pandas>=2.0`, Python `>=3.9`. xarray loading needs
+  the optional `xarray` extra (`xarray` + `netCDF4`).
+- `download_layers` with no constraints downloads the entire global layer and
+  prompts for confirmation unless `skip_confirmation=True`.