Merge branch 'master' into GH1091-debian-setup-docs

Author: jonbrenas

.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

.gitignore

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

CONTRIBUTING.md

@@ -12,7 +12,7 @@ This package provides Python tools for accessing and analyzing genomic data from
 
 You'll need:
 
-- [pipx](https://python-poetry.org/) for installing Python tools
+- [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.
@@ -52,9 +52,13 @@ Both of these can be installed using your distribution's package manager or [Hom
 
    ```bash
    poetry env use 3.12
-   poetry install --extras dev
+   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

README.md

@@ -49,6 +49,8 @@ To get setup for development, see [this video if you prefer VS Code](https://you
 For detailed setup instructions, see:
 - [Linux setup guide](LINUX_SETUP.md)
 - [macOS setup guide](MACOS_SETUP.md)
+- [Windows setup guide](WINDOWS_SETUP.md)
+- [Google Colab (TPU) setup guide](docs/source/colab_tpu_runtime.rst)
 Detailed instructions can be found in the [Contributors guide](https://github.com/malariagen/malariagen-data-python/blob/master/CONTRIBUTING.md).
 
 ## AI use policy and guidelines

WINDOWS_SETUP.md

@@ -0,0 +1,90 @@
+# Windows Setup Guide
+
+To get setup for development on Windows, see
+[this video if you prefer VS Code](https://youtu.be/zddl3n1DCFM),
+or [this older video if you prefer PyCharm](https://youtu.be/QniQi-Hoo9A),
+and the instructions below.
+
+## 1. Fork and clone this repo
+```bash
+git clone https://github.com/[username]/malariagen-data-python.git
+cd malariagen-data-python
+```
+
+## 2. Install Python
+
+Download and install Python 3.10 from the official website:
+https://www.python.org/downloads/windows/
+
+During installation, check the box that says Add Python to PATH
+before clicking Install.
+
+Verify the installation worked:
+```bash
+python --version
+```
+
+## 3. Install pipx and poetry
+```bash
+python -m pip install --user pipx
+python -m pipx ensurepath
+pipx install poetry
+```
+
+After running ensurepath, close and reopen PowerShell before continuing.
+
+## 4. Create and activate development environment
+```bash
+poetry install
+poetry shell
+```
+
+## 5. Install pre-commit hooks
+```bash
+pipx install pre-commit
+pre-commit install
+```
+
+## 6. Add upstream remote and get latest code
+```bash
+git remote add upstream https://github.com/malariagen/malariagen-data-python
+git pull upstream master
+```
+
+Note: On Windows the default branch is called master, not main.
+
+## 7. Verify everything works
+```bash
+python -c "import malariagen_data; print('Setup successful!')"
+```
+
+## Common Issues on Windows
+
+**poetry not found after install**
+
+Close and reopen PowerShell, then try again.
+
+**git not recognized**
+
+Install Git from https://git-scm.com/download/win
+and restart PowerShell.
+
+**python not recognized**
+
+Reinstall Python and make sure to check
+Add Python to PATH during installation.
+
+**fatal: not a git repository**
+
+Make sure you are inside the malariagen-data-python
+folder before running any git commands.
+```bash
+cd malariagen-data-python
+```
+
+**error: pathspec main did not match**
+
+On Windows use master instead of main.
+```bash
+git checkout master
+```

docs/source/_static/images/anopheles_dirus.jpg

@@ -0,0 +1,111 @@
+Google Colab Installation Guide
+===============================
+Prerequisites
+-------------
+
+Before installing the package, configure the runtime environment
+correctly:
+
+1. Open a new notebook in Google Colab.
+2. Navigate to ``Runtime → Change runtime type``.
+3. Set the runtime configuration as follows:
+
+   - **Runtime type:** Python 3
+   - **Hardware accelerator:** TPU
+   - **TPU type:** v2-8
+
+4. Click **Save** to apply the configuration.
+
+Using the recommended TPU configuration ensures compatibility with
+workflows that may require TPU-based computation.
+
+
+Installation Procedure
+----------------------
+
+In a new notebook cell, install the package:
+
+.. code-block:: bash
+
+   !pip install malariagen_data
+
+After installation completes, verify that the package is available:
+
+.. code-block:: python
+
+   import malariagen_data
+
+If the import executes without errors, the installation was successful.
+
+If dependency-related warnings or conflicts occur, follow one of the
+resolution options described below.
+
+
+Resolution Options
+------------------
+
+Resolution Option 1: Uninstall Panel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your notebook does not require ``panel``, uninstall it before
+installing ``malariagen_data``.
+
+.. code-block:: bash
+
+   !pip uninstall -y panel
+   !pip install malariagen_data
+
+Verify installation:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Resolution Option 2: Install Compatible Panel Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your workflow depends on ``panel``, install a compatible version:
+
+.. code-block:: bash
+
+   !pip install panel==1.7.0
+   !pip install malariagen_data
+
+Restart the runtime:
+
+``Runtime → Restart runtime``
+
+Then verify:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Resolution Option 3: Install Required Blinker Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a ``blinker`` version conflict occurs:
+
+.. code-block:: bash
+
+   !pip install blinker==1.9.0 --ignore-installed
+   !pip install malariagen_data
+
+Restart the runtime and verify:
+
+.. code-block:: python
+
+   import malariagen_data
+
+
+Final Verification
+------------------
+
+After completing any of the procedures above:
+
+- Ensure that ``malariagen_data`` installs without dependency errors.
+- Confirm that ``import malariagen_data`` runs successfully.
+- Restart the runtime whenever core dependencies are modified.
+- Avoid mixing incompatible package versions within the same Colab session.