build(python): migrate to uv

.github/workflows/ci-tests.yml

@@ -2,6 +2,9 @@
 name: CI Tests
 permissions: {}
 
+env:
+  PYTHON_VERSION: '3.14'
+
 on:
   pull_request:
   push:
@@ -16,36 +19,37 @@ concurrency:
 jobs:
   tests:
     permissions:
-      contents: write  # write is required for release_setup
+      contents: read
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
-          python-version: '3.14'
+          python-version: ${{ env.PYTHON_VERSION }}
 
-      - name: Set up Node
+      - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: latest
 
-      - name: Install Python Dependencies
-        shell: bash
-        run: |
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -e .[dev]
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
 
-      - name: Install Node Dependencies
-        shell: bash
+      - name: Install Python dependencies
+        run: uv sync --locked --extra dev --python "${PYTHON_VERSION}" --no-python-downloads
+
+      - name: Install npm dependencies
         run: npm ci --ignore-scripts
 
       - name: Test with pytest
         id: pytest
         shell: bash
-        run: python -m pytest
+        run: uv run --no-sync python -m pytest tests
 
       - name: Test with Jest
         id: jest
@@ -70,7 +74,6 @@ jobs:
         with:
           fail_ci_if_error: true
           files: ./coverage/python-coverage.xml,./coverage/coverage-final.json
-          flags: ${{ runner.os }}
           report_type: coverage
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true
@@ -90,7 +93,6 @@ jobs:
         with:
           fail_ci_if_error: true
           files: ./junit-python.xml,./junit.xml
-          flags: ${{ runner.os }}
           report_type: test_results
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true

.github/workflows/update-db.yml

@@ -2,6 +2,9 @@
 name: Update
 permissions: {}
 
+env:
+  PYTHON_VERSION: '3.14'
+
 on:
   pull_request:
   push:
@@ -34,19 +37,22 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
-          python-version: '3.14'
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
 
       - name: Install Python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e .
+        run: uv sync --locked --python "${PYTHON_VERSION}" --no-python-downloads
 
       - name: Update
         env:
           TWITCH_CLIENT_ID: ${{ secrets.TWITCH_CLIENT_ID }}
           TWITCH_CLIENT_SECRET: ${{ secrets.TWITCH_CLIENT_SECRET }}
           YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }}
-        run: python -u ./src/update_db.py ${{ github.event_name == 'pull_request' && '-t' || '' }}
+        run: uv run --no-sync python -u ./src/update_db.py ${{ github.event_name == 'pull_request' && '-t' || '' }}
 
       - name: Prepare Artifacts  # uploading artifacts will fail if not zipped due to very large quantity of files
         shell: bash

README.md

@@ -54,3 +54,7 @@ alphanumeric characters of the game name (lowercased), e.g. `ha.json` for games
 *Halo*. Games whose names contain a space as the second character are put into a bucket named after the first
 character. Games whose names do not start with two alphanumeric characters are grouped into `@.json`. Each bucket
 contains a dictionary of `{ id: { name } }` entries, keeping individual files small for fast lookups.
+
+## Development
+
+Code contributors can use the [Developer Setup](docs/developerSetup.md) guide.

docs/developerSetup.md

@@ -0,0 +1,51 @@
+# Developer Setup
+
+This page is for code contributors working on GameDB development, tests, or workflow automation.
+
+Python dependencies are managed with [uv](https://docs.astral.sh/uv/). The dependency declarations live in
+`pyproject.toml`, and `uv.lock` is committed so local development and CI use the same resolved package set.
+
+Install uv outside this repository's `.venv` if it is not already available:
+
+```shell
+pipx install uv
+# or
+python -m pip install --user uv
+```
+
+If Python 3.14 is not already installed, install it with uv:
+
+```shell
+uv python install 3.14
+```
+
+Create or update the project `.venv` environment, including test dependencies:
+
+```shell
+uv sync --extra dev
+```
+
+Run Python commands through uv so they use the synced `.venv` environment:
+
+```shell
+uv run python -m pytest tests
+```
+
+Node dependencies still use npm:
+
+```shell
+npm ci --ignore-scripts
+npm test
+```
+
+When `pyproject.toml` dependencies change, update the lock file and include it in the same pull request:
+
+```shell
+uv lock
+```
+
+CI runs `uv sync --locked`, so dependency changes fail until `uv.lock` is current. To check that locally, run:
+
+```shell
+uv sync --locked --extra dev
+```

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gamedb"
-dynamic = ["version"]
+version = "0.0.0"
 description = "Game Database - Jekyll static site with IGDB data"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -49,6 +49,7 @@ addopts = [
     "--color=yes",
     "--cov=src",
     "--cov-report=term-missing",
+    "--cov-report=xml:coverage/python-coverage.xml",
     "--junitxml=junit-python.xml",
     "-o", "junit_family=legacy",
 ]