Merge branch 'master' into fix#919

Author: jonbrenas

.codecov.yml

@@ -0,0 +1,9 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+    patch:
+      default:
+        target: 80%
+        threshold: 0%

.github/actions/setup-python/action.yaml

@@ -19,4 +19,4 @@ runs:
       shell: bash
       run: |
         poetry env use ${{ inputs.python-version }}
-        poetry install --extras dev
+        poetry install --with dev,test,docs

.github/workflows/tests.yml

@@ -12,6 +12,10 @@ jobs:
       fail-fast: true
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
+        numpy-spec:
+          # Keep this aligned with pyproject.toml: numpy = ">=2.0.2,<2.1"
+          - "==2.0.2"       # locked baseline
+          - ">=2.0.2,<2.1"  # latest allowed in declared range
     runs-on: ubuntu-latest
 
     steps:
@@ -23,8 +27,26 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Verify NumPy version
-        run: poetry run python -c "import numpy; print('NumPy version:', numpy.__version__)"
+      - name: Install matrix NumPy version
+        run: poetry run pip install --upgrade --no-deps "numpy${{ matrix.numpy-spec }}"
+
+      - name: Verify NumPy version and spec
+        env:
+          NUMPY_SPEC: ${{ matrix.numpy-spec }}
+        run: |
+          poetry run python - <<'PY'
+          import os
+          import numpy
+          from packaging.specifiers import SpecifierSet
+
+          spec = SpecifierSet(os.environ["NUMPY_SPEC"])
+          version = numpy.__version__
+          if version not in spec:
+              raise RuntimeError(
+                  f"NumPy version {version} does not satisfy matrix spec {spec}"
+              )
+          print("NumPy version:", version, "| spec:", spec)
+          PY
 
       - name: Run unit tests
         run: poetry run pytest -v tests --ignore tests/integration --typeguard-packages=malariagen_data,malariagen_data.anoph

.gitignore

@@ -1,8 +1,10 @@
 .idea
 .vscode
 __pycache__
+.mypy_cache
 *.pyc
 dist
+.venv/
 .coverage
 coverage.xml
 .ipynb_checkpoints/

CONTRIBUTING.md

@@ -12,9 +12,10 @@ This package provides Python tools for accessing and analyzing genomic data from
 
 You'll need:
 
-- Python 3.10.x (CI-tested version)
-- [Poetry](https://python-poetry.org/) for dependency management
-- [Git](https://git-scm.com/) for version control
+- [pipx](https://pipx.pypa.io/) for installing Python tools
+- [git](https://git-scm.com/) for version control
+
+Both of these can be installed using your distribution's package manager or [Homebrew](https://brew.sh/) on Mac.
 
 ### Initial setup
 
@@ -33,18 +34,31 @@ You'll need:
    git remote add upstream https://github.com/malariagen/malariagen-data-python.git
    ```
 
-3. **Install Poetry** (if not already installed)
+3. **Install Poetry**
 
    ```bash
    pipx install poetry
    ```
 
-4. **Install the project and its dependencies**
+4. **Install Python 3.12**
+
+   Python 3.12 is tested in the CI-system and is the recommended version to use.
+
+   ```bash
+   poetry python install 3.12
+   ```
+
+5. **Install the project and its dependencies**
 
    ```bash
-   poetry install
+   poetry env use 3.12
+   poetry install --with dev,test,docs
    ```
 
+   This installs the runtime dependencies along with the `dev`, `test`, and `docs`
+   [dependency groups](https://python-poetry.org/docs/managing-dependencies/#dependency-groups).
+   If you only need to run tests, `poetry install --with test` is sufficient.
+
    **Recommended**: Use `poetry run` to run commands inside the virtual environment:
 
    ```bash
@@ -71,7 +85,7 @@ You'll need:
    python script.py
    ```
 
-5. **Install pre-commit hooks**
+6. **Install pre-commit hooks**
 
    ```bash
    pipx install pre-commit
@@ -107,16 +121,40 @@ You'll need:
 
 4. **Run tests locally**
 
-   Fast unit tests (no external data access):
+   Fast unit tests using simulated data (no external data access):
 
    ```bash
-   poetry run pytest -v tests/anoph
+   poetry run pytest -v tests --ignore tests/integration
    ```
 
-   All unit tests (requires setting up credentials for legacy tests):
+   To run integration tests which read data from GCS, you'll need to [request access to MalariaGEN data on GCS](https://malariagen.github.io/vector-data/vobs/vobs-data-access.html).
+
+   Once access has been granted, [install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install). E.g., if on Linux:
 
    ```bash
-   poetry run pytest -v tests --ignore tests/integration
+   ./install_gcloud.sh
+   ```
+
+   You'll then need to obtain application-default credentials, e.g.:
+
+   ```bash
+   ./google-cloud-sdk/bin/gcloud auth application-default login
+   ```
+
+   Once this is done, you can run integration tests:
+
+   ```bash
+   poetry run pytest -v tests/integration
+   ```
+
+   Tests will run slowly the first time, as data required for testing will be read from GCS. Subsequent runs will be faster as data will be cached locally in the "gcs_cache" folder.
+
+6. **Run typechecking**
+
+   Run static typechecking with mypy:
+
+   ```bash
+   poetry run mypy malariagen_data tests --ignore-missing-imports
    ```
 
 5. **Check code quality**
@@ -150,7 +188,7 @@ ruff format .
 - **Fast tests**: Unit tests should use simulated data when possible (see `tests/anoph/`)
 - **Integration tests**: Tests requiring GCS data access are slower and run separately
 
-Run type checking with:
+Run dynamic type checking with:
 
 ```bash
 poetry run pytest -v tests --typeguard-packages=malariagen_data,malariagen_data.anoph

LINUX_SETUP.md

@@ -0,0 +1,140 @@
+# Developer setup (Linux)
+
+## 1. Install Git
+
+Choose the command for your Linux distribution:
+
+**Ubuntu, Debian, and Mint:**
+
+```bash
+sudo apt update
+sudo apt install -y git
+```
+
+**Fedora:**
+
+```bash
+sudo dnf install -y git
+```
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S sudo
+sudo pacman -S git
+sudo pacman -S openssh
+```
+
+If your Arch install does not have `sudo` configured yet, run the commands above as `root`, then configure `sudo` for your user.
+
+## 2. Fork and clone this repo
+
+After forking the repository on GitHub, clone your fork.
+
+Use SSH if your SSH keys are set up:
+
+```bash
+git clone git@github.com:[YOUR_GITHUB_USERNAME]/malariagen-data-python.git
+cd malariagen-data-python
+```
+
+Use HTTPS if you prefer, or if you do not have SSH keys configured (common on WSL):
+
+```bash
+git clone https://github.com/[YOUR_GITHUB_USERNAME]/malariagen-data-python.git
+cd malariagen-data-python
+```
+
+## 3. Install pipx
+
+Choose the command for your Linux distribution:
+
+**Ubuntu, Debian, and Mint:**
+
+```bash
+sudo apt update
+sudo apt install -y pipx
+pipx ensurepath
+```
+
+**Fedora:**
+
+```bash
+sudo dnf install -y pipx
+pipx ensurepath
+```
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S python-pipx
+pipx ensurepath
+```
+
+Close and reopen your terminal to apply PATH changes.
+If you prefer to reload the shell in-place, run:
+
+```bash
+exec bash
+```
+
+## 4. Install Poetry and Python 3.12
+
+The package requires `>=3.10,<3.13`. We use Poetry's built-in installer to handle the Python version universally across all distributions.
+
+```bash
+pipx install poetry
+poetry python install 3.12
+```
+
+## 5. Create development environment
+
+```bash
+poetry env use 3.12
+poetry install --extras dev
+```
+
+## 6. Install pre-commit hooks
+
+```bash
+pipx install pre-commit
+pre-commit install
+```
+
+Run pre-commit checks manually:
+
+```bash
+pre-commit run --all-files
+```
+
+## 7. Run tests
+
+Run fast unit tests using simulated data:
+
+```bash
+poetry run pytest -v tests/anoph
+```
+
+## 8. Google Cloud authentication (for legacy tests)
+
+To run legacy tests which read data from GCS, you'll need to [request access to MalariaGEN data on GCS](https://malariagen.github.io/vector-data/vobs/vobs-data-access.html).
+
+Once access has been granted, [install the Google Cloud CLI](https://cloud.google.com/sdk/docs/install):
+
+```bash
+./install_gcloud.sh
+```
+
+Then obtain application-default credentials:
+
+```bash
+./google-cloud-sdk/bin/gcloud auth application-default login
+```
+
+Once authenticated, run legacy tests:
+
+```bash
+poetry run pytest --ignore=tests/anoph -v tests
+```
+
+Tests will run slowly the first time, as data will be read from GCS and cached locally in the `gcs_cache` folder.

MACOS_SETUP.md

@@ -0,0 +1,77 @@
+# Developer setup (macOS)
+
+The Linux setup guide is available in [LINUX_SETUP.md](LINUX_SETUP.md). If you are on macOS, follow these steps instead.
+
+## 1. Install Miniconda
+
+Download and install Miniconda for macOS from https://docs.conda.io/en/latest/miniconda.html.
+Choose the Apple Silicon installer if you have an Apple Silicon Mac, or the Intel installer otherwise. You can check with:
+```bash
+uname -m
+# arm64 = Apple Silicon, x86_64 = Intel
+```
+
+After installation, close and reopen your terminal for conda to be available.
+
+## 2. Create a conda environment
+
+The package requires Python `>=3.10, <3.13`. Python 3.13+ is not currently supported.
+```bash
+conda create -n malariagen python=3.11
+conda activate malariagen
+```
+
+## 3. Fork and clone this repo
+
+Fork the repository on GitHub, then clone your fork:
+```bash
+git clone git@github.com:[username]/malariagen-data-python.git
+cd malariagen-data-python
+pip install -e ".[dev]"
+```
+
+## 4. Install pre-commit hooks
+```bash
+pre-commit install
+```
+
+Run pre-commit checks manually:
+```bash
+pre-commit run --all-files
+```
+
+## 5. Run tests
+
+Run fast unit tests using simulated data:
+```bash
+pytest -v tests/anoph
+```
+
+## 6. Google Cloud authentication (for legacy tests)
+
+To run legacy tests which read data from GCS, you'll need to [request access to MalariaGEN data on GCS](https://malariagen.github.io/vector-data/vobs/vobs-data-access.html).
+
+Once access has been granted, install the Google Cloud CLI:
+```bash
+brew install google-cloud-sdk
+```
+
+Then authenticate:
+```bash
+gcloud auth application-default login
+```
+
+This opens a browser — log in with any Google account.
+
+Once authenticated, run legacy tests:
+```bash
+pytest --ignore=tests/anoph -v tests
+```
+
+Tests will run slowly the first time, as data will be read from GCS and cached locally in the `gcs_cache` folder.
+
+## 7. VS Code terminal integration
+
+To use the `code` command from the terminal:
+
+Open VS Code → `Cmd + Shift + P` → type `Shell Command: Install 'code' command in PATH` → press Enter.