Initial project setup for unified WebGPU API for Python

.actrc

@@ -0,0 +1,5 @@
+--container-architecture linux/amd64
+--artifact-server-path .artifacts
+-P ubuntu-latest=catthehacker/ubuntu:act-latest
+-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
+-P ubuntu-20.04=catthehacker/ubuntu:act-20.04

.env.local.example

@@ -0,0 +1,9 @@
+# Example .env.local file - copy to .env.local and customize
+# Values here override .env.repo
+
+# Use a shared tools folder across multiple checkouts
+# TOOLS_FOLDER=~/.gpu-tools
+
+# API tokens (never commit these!)
+GITHUB_PAT=your_github_personal_access_token
+PYPI_TOKEN=your_pypi_token

.env.repo

@@ -0,0 +1,16 @@
+TOOLS_FOLDER=.tools
+TOOLS_VERSION_UV=0.9.18
+TOOLS_VERSION_CMAKE=4.2.1
+TOOLS_VERSION_NINJA=1.13.2
+TOOLS_VERSION_EMSDK=4.0.9 # pyodide_2025_0 ABI
+TOOLS_VERSION_ACT=0.2.83
+TOOLS_VERSION_GH=2.83.1
+TOOLS_PYTHON313=3.13.11
+
+# UV configuration
+UV_PYTHON_PREFERENCE=only-managed
+UV_CACHE_DIR=${TOOLS_FOLDER}/uv/cache
+UV_TOOL_DIR=${TOOLS_FOLDER}/uv/tools
+UV_TOOL_BIN_DIR=${TOOLS_FOLDER}/uv/tools/bin
+UV_PYTHON_INSTALL_DIR=${TOOLS_FOLDER}/uv/python
+UV_PYTHON_BIN_DIR=${TOOLS_FOLDER}/uv/python/bin

.github/workflows/test.yml

@@ -0,0 +1,97 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  # Test pure Python packages (gpu-api, gpu-wesl, gpu-canvas)
+  # Pure Python wheels are version-agnostic (py3-none-any)
+  test-pure:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore tools cache
+        id: cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.tools
+          key: tools-${{ runner.os }}-${{ hashFiles('.env.repo', 'activate.sh', 'scripts/**/*.sh') }}
+          restore-keys: |
+            tools-${{ runner.os }}-
+
+      - name: Activate environment
+        env:
+          TOOLS_FOLDER: ~/.tools
+        run: source activate.sh
+
+      - name: Save tools cache
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.tools
+          key: tools-${{ runner.os }}-${{ hashFiles('.env.repo', 'activate.sh', 'scripts/**/*.sh') }}
+
+      - name: Build pure Python packages
+        run: |
+          uv build packages/gpu-api -o dist
+          uv build packages/gpu-wesl -o dist
+          uv build packages/gpu-canvas -o dist
+
+      - name: Test gpu-api
+        run: uv run --python ${{ matrix.python-version }} --with dist/gpu_api*.whl --with pytest pytest packages/gpu-api/tests -v
+
+      - name: Test gpu-wesl
+        run: uv run --python ${{ matrix.python-version }} --with dist/gpu_wesl*.whl --with pytest pytest packages/gpu-wesl/tests -v
+
+      - name: Test gpu-canvas
+        run: uv run --python ${{ matrix.python-version }} --with dist/gpu_canvas*.whl --with pytest pytest packages/gpu-canvas/tests -v
+
+  # Test native extension packages (gpu-dawn, gpu-wgpu)
+  # Native wheels are ABI-specific, so we build for each Python version
+  test-native:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore tools cache
+        id: cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.tools
+          key: tools-${{ runner.os }}-${{ hashFiles('.env.repo', 'activate.sh', 'scripts/**/*.sh') }}
+          restore-keys: |
+            tools-${{ runner.os }}-
+
+      - name: Activate environment
+        env:
+          TOOLS_FOLDER: ~/.tools
+        run: source activate.sh
+
+      - name: Save tools cache
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.tools
+          key: tools-${{ runner.os }}-${{ hashFiles('.env.repo', 'activate.sh', 'scripts/**/*.sh') }}
+
+      - name: Build and test gpu-dawn
+        run: |
+          uv build --python ${{ matrix.python-version }} packages/gpu-dawn -o dist
+          uv run --python ${{ matrix.python-version }} --with dist/gpu_dawn*.whl --with pytest pytest packages/gpu-dawn/tests -v
+
+      - name: Build and test gpu-wgpu
+        run: |
+          rm -rf dist
+          uv build --python ${{ matrix.python-version }} packages/gpu-wgpu -o dist
+          uv run --python ${{ matrix.python-version }} --with dist/gpu_wgpu*.whl --with pytest pytest packages/gpu-wgpu/tests -v

.github/workflows/wheels.yml

@@ -0,0 +1,223 @@
+name: Build wheels
+
+on:
+  push:
+    tags:
+      - "v*"
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  # Build pure Python packages (gpu-api, gpu-wesl, gpu-canvas)
+  build_pure:
+    name: Build pure Python packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build gpu-api
+        run: pipx run build packages/gpu-api
+
+      - name: Build gpu-wesl
+        run: pipx run build packages/gpu-wesl
+
+      - name: Build gpu-canvas
+        run: pipx run build packages/gpu-canvas
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-pure
+          path: packages/*/dist/*.whl
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist-pure
+          path: packages/*/dist/*.tar.gz
+
+  # Build all native source distributions
+  build_sdists:
+    name: Build source distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdists
+        run: |
+          pipx run build --sdist packages/gpu-dawn -o dist/
+          pipx run build --sdist packages/gpu-wgpu -o dist/
+          pipx run build --sdist packages/gpu-pyodide -o dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdists
+          path: dist/*.tar.gz
+
+  # Build gpu-dawn native wheels from sdist
+  build_dawn:
+    name: Build gpu-dawn on ${{ matrix.os }} (${{ matrix.arch }})
+    needs: [build_sdists]
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - { os: linux, arch: x64, runner: ubuntu-latest, cibw_archs: x86_64 }
+          - { os: linux, arch: arm64, runner: ubuntu-24.04-arm, cibw_archs: aarch64 }
+          - { os: macos, arch: x64, runner: macos-15-intel, cibw_archs: x86_64 }
+          - { os: macos, arch: arm64, runner: macos-latest, cibw_archs: arm64 }
+          - { os: windows, arch: x64, runner: windows-latest, cibw_archs: AMD64 }
+          - { os: windows, arch: arm64, runner: windows-11-arm, cibw_archs: ARM64 }
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdists
+          path: sdists/
+
+      - name: Extract sdist
+        run: |
+          mkdir -p package
+          tar -xzf sdists/gpu_dawn-*.tar.gz -C package --strip-components=1
+        shell: bash
+
+      - name: Build wheels
+        uses: pypa/[email protected]
+        with:
+          package-dir: package
+          output-dir: wheelhouse
+        env:
+          CIBW_ARCHS: ${{ matrix.cibw_archs }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-dawn-${{ matrix.os }}-${{ matrix.arch }}
+          path: ./wheelhouse/*.whl
+
+  # Build gpu-wgpu native wheels from sdist
+  build_wgpu:
+    name: Build gpu-wgpu on ${{ matrix.os }} (${{ matrix.arch }})
+    needs: [build_sdists]
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - { os: linux, arch: x64, runner: ubuntu-latest, cibw_archs: x86_64 }
+          - { os: linux, arch: arm64, runner: ubuntu-24.04-arm, cibw_archs: aarch64 }
+          - { os: macos, arch: x64, runner: macos-15-intel, cibw_archs: x86_64 }
+          - { os: macos, arch: arm64, runner: macos-latest, cibw_archs: arm64 }
+          - { os: windows, arch: x64, runner: windows-latest, cibw_archs: AMD64 }
+          - { os: windows, arch: arm64, runner: windows-11-arm, cibw_archs: ARM64 }
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdists
+          path: sdists/
+
+      - name: Extract sdist
+        run: |
+          mkdir -p package
+          tar -xzf sdists/gpu_wgpu-*.tar.gz -C package --strip-components=1
+        shell: bash
+
+      - name: Build wheels
+        uses: pypa/[email protected]
+        with:
+          package-dir: package
+          output-dir: wheelhouse
+        env:
+          CIBW_ARCHS: ${{ matrix.cibw_archs }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-wgpu-${{ matrix.os }}-${{ matrix.arch }}
+          path: ./wheelhouse/*.whl
+
+  # Build gpu-pyodide wheel from sdist (Pyodide only)
+  build_pyodide:
+    name: Build gpu-pyodide wheel
+    needs: [build_sdists]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdists
+          path: sdists/
+
+      - name: Extract sdist
+        run: |
+          mkdir -p package
+          tar -xzf sdists/gpu_pyodide-*.tar.gz -C package --strip-components=1
+
+      - name: Build Pyodide wheel
+        uses: pypa/[email protected]
+        with:
+          package-dir: package
+          output-dir: wheelhouse
+        env:
+          CIBW_PLATFORM: pyodide
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-pyodide
+          path: ./wheelhouse/*.whl
+
+  # Publish to PyPI
+  publish:
+    name: Publish to PyPI
+    needs: [build_pure, build_sdists, build_dawn, build_wgpu, build_pyodide]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdists
+          path: dist
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: sdist-*
+          path: dist
+          merge-multiple: true
+
+      # Exclude Pyodide wheels - PyPI doesn't support wasm32 yet (see PEP 783)
+      - name: Remove Pyodide wheels
+        run: rm -f dist/*pyodide*.whl dist/*wasm32*.whl dist/*emscripten*.whl
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+  # Create GitHub Release with all artifacts
+  release:
+    name: Create GitHub Release
+    needs: [build_pure, build_sdists, build_dawn, build_wgpu, build_pyodide]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

.gitignore

@@ -1,3 +1,15 @@
+# macOS
+.DS_Store
+
+# Local tools (managed by activate scripts)
+.tools/
+
+# Act artifacts (local CI testing)
+.artifacts/
+
+# cibuildwheel output
+wheelhouse/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -136,14 +148,19 @@ celerybeat.pid
 
 # Environments
 .env
+.env.local
 .envrc
 .venv
+.venv-pyodide/
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/
 
+# Pyodide build artifacts
+**/.pyodide_build/
+
 # Spyder project settings
 .spyderproject
 .spyproject

.python-version

@@ -0,0 +1 @@
+3.13