v0.3.1: migrate to uv, refactor dependencies, and modernize CI/CD with multi-platform Docker

.github/workflows/ci.yml

@@ -2,10 +2,12 @@ name: CI
 
 on:
   push:
-    branches: [main, dev]
+    branches:
+      - main
+      - dev
   pull_request:
-    branches: [main, dev]
-    types: [opened, synchronize, reopened]
+    branches:
+      - dev
   workflow_dispatch:
 
 permissions:
@@ -27,47 +29,42 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.11"
-          cache: "pip"
-      - name: Install dependencies
-        run: pip install ruff
+          enable-cache: true
       - name: Lint with Ruff
-        run: ruff check .
+        run: uv run ruff check .
 
   ruff-format:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.11"
-          cache: "pip"
-      - name: Install dependencies
-        run: pip install ruff
+          enable-cache: true
       - name: Check formatting with Ruff
-        run: ruff format --check .
+        run: uv run ruff format --check .
 
   mypy-typecheck:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || github.event.pull_request.head.ref != 'dev'
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.11"
-          cache: "pip"
-      - name: Install dependencies
+          enable-cache: true
+      - name: Install system dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install .[dev]
+          sudo apt-get update
+          sudo apt-get install -y libeccodes-dev
+      - name: Install dependencies
+        run: uv sync --group dev
       - name: Type check with Mypy
-        run: mypy src/ tests/
+        run: uv run mypy src/ tests/
 
   unit-tests:
     name: unit-tests (Python ${{ matrix.python-version }})
@@ -78,22 +75,20 @@ jobs:
         python-version: ${{ fromJSON(needs.prepare.outputs.python-versions) }}
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
+          enable-cache: true
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
-      - name: Install dependencies
+      - name: Install system dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install .[dev]
+          sudo apt-get update
+          sudo apt-get install -y libeccodes-dev
+      - name: Install dependencies
+        run: uv sync --group dev
       - name: Run Unit Tests
         run: |
-          pytest -vv
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          uv run pytest -vv
 
   integration-tests:
     name: integration-tests (Python ${{ matrix.python-version }})
@@ -104,22 +99,20 @@ jobs:
         python-version: ${{ fromJSON(needs.prepare.outputs.python-versions) }}
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
+          enable-cache: true
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
-      - name: Install MPI
+      - name: Install system dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y openmpi-bin libopenmpi-dev
+          sudo apt-get install -y openmpi-bin libopenmpi-dev libeccodes-dev
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install .[dev]
+        run: uv sync --group dev
       - name: Run Integration Tests
         run: |
-          pytest -vv tests/test_integration.py --run-all
+          uv run pytest -vv tests/test_integration.py --run-integration
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:

.github/workflows/docker-publish.yml

@@ -3,7 +3,20 @@ name: Docker Publish
 on:
   workflow_run:
     workflows: ["CI"]
+    branches: [dev]
     types: [completed]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'The branch to build from'
+        required: true
+        type: choice
+        options:
+        - main
+        - dev
+        default: 'main'
 
 env:
   DOCKER_HUB_REPO: xddd/pystormtracker
@@ -12,23 +25,23 @@ env:
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') ||
+      github.event_name == 'release' ||
+      github.event_name == 'workflow_dispatch'
     permissions:
       contents: read
       packages: write
-    # Only run if CI was successful AND it was a push event to main or dev
-    # Added head_repository check to prevent checkout of untrusted code in trusted context
-    if: >
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.head_repository.full_name == github.repository &&
-      (github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'workflow_dispatch') &&
-      (github.event.workflow_run.head_branch == 'main' || github.event.workflow_run.head_branch == 'dev')
-
     steps:
       - name: Checkout repository
-        # Use the commit from the completed workflow run
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.workflow_run.head_sha }}
+          # Checkout the branch on manual trigger, the commit on workflow_run, or the tag on release
+          ref: ${{ github.event.inputs.branch || github.event.workflow_run.head_sha }}
+          fetch-depth: 0 # Fetches all history for all tags. Needed for semver.
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -43,27 +56,32 @@ jobs:
         uses: docker/login-action@v4
         with:
           registry: ghcr.io
-          username: ${{ github.actor }}
+          username: ${{ github.repository_owner }}
           password: ${{ secrets.GHCR_PAT }}
 
       - name: Extract Docker metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: |
             ${{ env.DOCKER_HUB_REPO }}
             ${{ env.GHCR_REPO }}
           tags: |
-            type=raw,value=dev,pattern=dev
-            type=raw,value=latest,pattern=main
-            type=semver,pattern={{version}},pattern=main
-            type=semver,pattern={{major}}.{{minor}},pattern=main
+            # Tag all builds with the short commit hash
+            type=sha,format=short
+            # 'dev' tag for CI runs on dev branch or manual builds of dev
+            type=raw,value=dev,enable=${{ (github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'dev') || (github.event_name == 'workflow_dispatch' && github.event.inputs.branch == 'dev') }}
+            # 'latest' and semantic version tags for releases
+            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            type=match,pattern=v(.*),group=1,enable=${{ github.event_name == 'release' }}
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v7
         with:
           context: .
           push: true
+          provenance: false
+          platforms: linux/amd64,linux/arm64
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha

.github/workflows/python-publish.yml

@@ -17,14 +17,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v6
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.x"
+          enable-cache: true
 
       - name: Build release distributions
-        run: |
-          python -m pip install build
-          python -m build
+        run: uv build
 
       - name: Upload distributions
         uses: actions/upload-artifact@v7

.pre-commit-config.yaml

@@ -1,3 +1,4 @@
+default_stages: [pre-commit, pre-push]
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -19,4 +20,4 @@ repos:
     rev: v1.15.0
     hooks:
       - id: mypy
-        additional_dependencies: [numpy, pooch, scipy, pytest, pandas, xarray, dask, distributed, h5netcdf]
+        additional_dependencies: [numpy, pooch, scipy, pytest, xarray, dask, distributed, h5netcdf]

.readthedocs.yaml

@@ -1,19 +1,22 @@
-# Read the Docs configuration file
+# Read the Docs configuration file for Sphinx projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 version: 2
 
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.14"
+    python: "3.11"
 
 python:
   install:
     - method: pip
       path: .
       extra_requirements:
-        - dev
+        - docs
 
 sphinx:
   configuration: docs/conf.py
+
+formats:
+  - pdf

CITATION.cff

@@ -11,15 +11,15 @@ identifiers:
   - type: doi
     value: 10.5281/zenodo.18764813
 repository-code: 'https://github.com/mwyau/PyStormTracker'
-url: 'https://github.com/mwyau/PyStormTracker'
+url: 'https://pystormtracker.readthedocs.io/'
 abstract: A Parallel Object-Oriented Cyclone Tracker in Python
 keywords:
   - cyclone tracking
   - climate variability
   - dask
   - mpi
 license: BSD-3-Clause
-version: 0.3.0
+version: 0.3.1
 date-released: '2026-03-08'
 preferred-citation:
   type: article

Dockerfile

@@ -14,11 +14,14 @@ WORKDIR /app
 # Create data directory for mounting
 RUN mkdir /data && chmod 777 /data
 
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
 # Copy the project files
 COPY . .
 
-# Install the package and its dependencies
-RUN pip install --no-cache-dir .
+# Install the package and its dependencies using uv
+RUN uv pip install --system --no-cache .
 
 # Add a non-root user for security
 RUN useradd -m pst

LICENSE

@@ -1,40 +1,29 @@
+BSD 3-Clause License
+
 Copyright (c) 2015, University Corporation for Atmospheric Research (UCAR)
 Copyright (c) 2026, Albert M. W. Yau
-All rights reserved.
 
-Developed by: Application Scalability and Performance Group
-              University Corporation for Atmospheric Research -
-              National Center for Atmospheric Research
-              https://www.cisl.ucar.edu/
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-Developed by: Albert M. W. Yau
-              https://github.com/mwyau/PyStormTracker
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the "Software"),
-to deal with the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom
-the Software is furnished to do so, subject to the following conditions:
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-- Redistributions of source code must retain the above copyright notice,
-  this list of conditions and the following disclaimers.
-- Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimers in the documentation
-  and/or other materials provided with the distribution.
-- Neither the names of the Application Scalability and Performance (ASAP)
-  Group, UCAR, nor the names of its contributors may be used to endorse or
-  promote products derived from this Software without specific prior written
-  permission.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.