Release/v1.5.0

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/build.yml

@@ -1,45 +1,57 @@
 name: build
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: build-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build:
-      runs-on: ${{ matrix.os }}
-
-      strategy:
-        matrix:
-          os: [ubuntu-latest]
-
-      env:
-        OS: ${{ matrix.os }}
-        PYTHON: '3.9'
-
-      steps:
-
-        - uses: actions/checkout@v1
-
-        - name: Set up Python
-          uses: actions/setup-python@master
-          with:
-            python-version: 3.9
-
-        - name: Install dependencies
-          run: |
-            sudo apt-get update -y
-            sudo apt-get install -y libxml2-dev
-            sudo snap install libxslt
-            python -m pip install --upgrade pip
-            pip install click
-            python setup.py install
-
-        - name: Test and generate coverage report on Linux
-          run: |
-            pip install pytest
-            pip install pytest-cov
-            pytest --cov=./ --cov-report=xml
-
-        - name: Upload coverage to Codecov
-          uses: codecov/codecov-action@v1
-          with:
-            file: ./coverage.xml
-            fail_ci_if_error: true
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install system libraries
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y libxml2-dev libxslt1-dev
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest --cov=gcamreader --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package with docs extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: sphinx-build -b html -W docs docs/_build/html
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: lint
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install linters
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff black
+
+      - name: Run ruff
+        run: ruff check .
+
+      - name: Run black
+        run: black --check .

.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Check distribution contents
+        run: |
+          python -m pip install twine
+          twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gcamreader/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,3 +1,12 @@
+# pyenv
+.python-version
+
+# development plans
+plans/
+
+# local files
+.local/
+
 # pycharm
 .idea
 

CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [1.5.0] - 2026-06-15
+
+This release modernizes the package without changing its computational results.
+A behavioral baseline captured from v1.4.0 is preserved in `benchmarks/` and is
+used as a regression gate to guarantee identical query outputs.
+
+### Added
+
+- Behavioral baseline harness and regression test suite in `benchmarks/` that
+  lock query, scenario, `importdata`, and CLI outputs to the v1.4.0 results.
+- `pyproject.toml` as the single source of build metadata and configuration.
+- `CHANGELOG.md` to track project changes.
+
+### Changed
+
+- Migrated packaging from `setup.py` and `setup.cfg` to `pyproject.toml`
+  (setuptools backend).
+- Raised the minimum supported Python version to 3.11.
+- Replaced the Click based command line interface (and the
+  `click-default-group-wheel` dependency) with a Typer based CLI.
+- Relaxed the pinned `requests~=2.20.0` requirement to a modern minimum and
+  refreshed the `pandas` and `lxml` minimum versions.
+- Modernized `querymi.py`: removed Python 2 and Python 3.5 compatibility
+  branches, replaced `pkg_resources` with `importlib.resources`, and added type
+  hints and complete docstrings.
+- Moved the test suite to a top level `tests/` directory and the example
+  notebooks to a top level `notebooks/` directory.
+
+### Fixed
+
+- Result parsing in `_parserslt` now aggregates with `dropna=False`, so rows
+  that contain missing values in one or more grouping columns are retained
+  instead of being silently dropped during the `groupby().sum()` step (PR #40).
+
+### Removed
+
+- `setup.py`, `setup.cfg`, `requirements.txt`, and `MANIFEST.in` (superseded by
+  `pyproject.toml`).
+
+### Release verification
+
+**Result: PASS — v1.5.0 reproduces the v1.4.0 outputs exactly.**
+
+A behavioral baseline captured from v1.4.0 (`benchmarks/baseline/`) is re-run
+against the v1.5.0 code by `benchmarks/test_regression.py`. Every fixture
+matches: CSV outputs are compared byte-for-byte by SHA-256 checksum, and
+DataFrame outputs are compared with `pandas.testing.assert_frame_equal` after a
+deterministic sort.
+
+| Operation | Result | Comparison | Java |
+| --- | --- | --- | --- |
+| `parse_batch_query` (query structure) | identical | exact title/region/query strings | not required |
+| `listScenariosInDB` | identical | `assert_frame_equal` | required |
+| `runQuery` (land-allocation query) | identical | `assert_frame_equal` (sorted) | required |
+| `importdata` (land-allocation query) | identical | `assert_frame_equal` (sorted) | required |
+| `gcamreader local` CLI CSV output | identical | SHA-256 (byte-for-byte) | required |
+
+Baseline captured with gcamreader 1.4.0 on Python 3.13.3, OpenJDK 23.0.2
+(Homebrew), macOS 26.5.1 (arm64). Reproduce locally with:
+
+```bash
+pytest benchmarks/test_regression.py
+```
+
+[Unreleased]: https://github.com/JGCRI/gcamreader/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/JGCRI/gcamreader/compare/v1.4.0...v1.5.0