refactor: apply codebase review fixes, add type stubs, and offline unit tests

.github/workflows/nightly.yaml

@@ -0,0 +1,58 @@
+name: nightly
+
+on:
+  schedule:
+    - cron: '0 3 * * *' # Every night at 03:00 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  api-drift-check:
+    name: Ensembl Live API Drift Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.14'
+
+      - name: Set Poetry Version
+        id: set-poetry-version
+        run: echo "POETRY_VERSION=$(cat .poetry-version)" >> $GITHUB_OUTPUT
+
+      - name: Install Poetry
+        id: install-poetry-version
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
+        with:
+          version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          virtualenvs-path: .venv
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-3.14-nightly-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Install project
+        run: poetry install --no-interaction
+
+      - name: Run all tests against live Ensembl API
+        run: poetry run pytest -v tests/

.github/workflows/pull_request.yaml

@@ -3,27 +3,87 @@ name: pull_request
 on:
   pull_request:
     paths:
-      - 'pyensemblrest/**.py'
-      - 'tests/**.py'
+      - 'pyensemblrest/**'
+      - 'tests/**'
       - 'pyproject.toml'
       - 'poetry.lock'
       - '.github/workflows/pull_request.yaml'
 
+# Automatically cancel redundant in-progress workflow runs for new commits on the same PR branch
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
 jobs:
-  test:
-    name: Run Tests
+  lint:
+    name: Code Quality & Type Check
     runs-on: ubuntu-latest
-    environment: dev
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.14'
+
+      - name: Set Poetry Version
+        id: set-poetry-version
+        run: echo "POETRY_VERSION=$(cat .poetry-version)" >> $GITHUB_OUTPUT
+
+      - name: Install Poetry
+        id: install-poetry-version
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
+        with:
+          version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          virtualenvs-path: .venv
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-3.14-lint-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Install project
+        run: poetry install --no-interaction
+
+      - name: Run Ruff Linter and Formatter Check
+        run: |
+          poetry run ruff check .
+          poetry run ruff format --check .
+
+      - name: Run Mypy Type Check
+        run: poetry run mypy . --no-incremental
+
+      - name: Run Poetry Config Check
+        run: poetry check
+
+  unit-test:
+    name: Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
+      fail-fast: false
       matrix:
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
-    timeout-minutes: 60
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -33,7 +93,7 @@ jobs:
 
       - name: Install Poetry
         id: install-poetry-version
-        uses: snok/install-poetry@v1
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
         with:
           version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
           virtualenvs-create: true
@@ -43,7 +103,7 @@ jobs:
 
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: .venv
           key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
@@ -55,14 +115,57 @@ jobs:
       - name: Install project
         run: poetry install --no-interaction
 
-      - name: Run pre-commit hooks, excluding unit tests
-        run: SKIP=unit-test poetry run pre-commit run --all-files
-
-      - name: Run unit tests with pytest and code coverage with pytest-cov
-        run: poetry run pytest -v --cov=pyensemblrest --cov-report lcov:./tests/lcov.info
+      - name: Run offline unit tests with coverage
+        run: poetry run pytest -v -m "not live" --cov=pyensemblrest --cov-report lcov:./tests/lcov.info tests/
 
       - name: Upload Coverage Results
-        uses: coverallsapp/github-action@master
+        if: matrix.python-version == '3.14'
+        uses: coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           path-to-lcov: ./tests/lcov.info
+
+  live-test:
+    name: Live Ensembl API Smoke Test
+    needs: [unit-test]
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.14'
+
+      - name: Set Poetry Version
+        id: set-poetry-version
+        run: echo "POETRY_VERSION=$(cat .poetry-version)" >> $GITHUB_OUTPUT
+
+      - name: Install Poetry
+        id: install-poetry-version
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
+        with:
+          version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          virtualenvs-path: .venv
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-3.14-live-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Install project
+        run: poetry install --no-interaction
+
+      - name: Run Live Ensembl REST API tests (single runner to respect rate limits)
+        run: poetry run pytest -v -m "live" tests/

.github/workflows/push_tag.yaml

@@ -5,27 +5,32 @@ on:
     tags:
       - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: read
 
 jobs:
   release:
     name: Release to GitHub
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     environment: dev
     permissions:
       contents: write
       discussions: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-tags: true
-          ref: ${{ github.ref_name}}
+          ref: ${{ github.ref_name }}
 
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ">=3.10 <3.15"
 
@@ -35,7 +40,7 @@ jobs:
 
       - name: Install Poetry
         id: install-poetry-version
-        uses: snok/install-poetry@v1
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
         with:
           version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
           virtualenvs-create: true
@@ -49,7 +54,7 @@ jobs:
 
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: .venv
           key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
@@ -65,46 +70,48 @@ jobs:
         run: poetry build
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: release-dists
           path: dist/
 
       - name: Create release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         if: startsWith(github.ref, 'refs/tags/')
         with:
           files: dist/*
           generate_release_notes: true
           draft: false
           prerelease: false
+
   publish:
     needs:
       - release
-    permissions:
-      id-token: write
-    name: Publish to PyPI
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     environment:
       name: dev
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set Poetry Version
         id: set-poetry-version
         run: echo "POETRY_VERSION=$(cat .poetry-version)" >> $GITHUB_OUTPUT
 
       - name: Install Poetry
-        uses: snok/install-poetry@v1
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1.4.2
         with:
           version: ${{ steps.set-poetry-version.outputs.POETRY_VERSION }}
 
       - name: Add Poetry Dynamic Versioning Plugin
         run: poetry self add poetry-dynamic-versioning[plugin]
 
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: release-dists
           path: dist