numchuck 0.2.0__tar.gz → 0.4.0__tar.gz

numchuck-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,302 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+        exclude:
+          # Windows Python 3.13 might have compatibility issues
+          - os: windows-latest
+            python-version: '3.13'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+        with:
+          enable-cache: true
+
+      - name: Install system dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            libjack-dev \
+            bison \
+            flex
+
+      - name: Install system dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew install cmake bison flex
+
+      - name: Install system dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
+
+      - name: Build and install package
+        run: |
+          uv sync --reinstall-package numchuck
+
+      - name: Run tests
+        run: |
+          # Skip: realtime (no audio device), wavfile (WvOut timing), chugin (not bundled), tui (requires console)
+          uv run pytest -v --tb=short -k "not realtime and not wavfile and not chugin and not tui"
+
+  lint:
+    name: Lint and Format Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+
+      # From the lockfile, not `uv pip install ruff`: an unpinned install
+      # picked up whatever ruff had released that day, and the formatter is not
+      # stable across minor versions -- 0.16 rewrapped a lambda that 0.14.10,
+      # the locked version, leaves alone. That is a failure no contributor can
+      # reproduce. --no-install-project skips building the extension, which
+      # this job does not need.
+      - name: Install linting tools
+        run: |
+          uv sync --only-group dev --no-install-project
+
+      # No --select here on purpose: the rules live in pyproject.toml so this
+      # job and `make lint` check the same thing. They did not, and import
+      # sorting was enforced only on the runner.
+      - name: Run ruff check
+        run: |
+          uv run --no-sync ruff check src/
+
+      - name: Run ruff format check
+        run: |
+          uv run --no-sync ruff format --check src/
+
+  realtime:
+    name: Real-time Audio Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+        with:
+          enable-cache: true
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            libasound2-plugins \
+            alsa-utils \
+            bison \
+            flex
+
+      # The tap seqlock is the most intricate code in the project and its only
+      # regression test needs an audio device, so it otherwise runs nowhere but
+      # a developer laptop. snd-dummy was the first attempt and is not an
+      # option: the Azure runner images carry no ALSA kernel modules
+      # ("modprobe: Module snd-dummy not found"). A PulseAudio null sink needs
+      # no kernel support, so try that, and record which route worked.
+      - name: Set up an audio device
+        id: audio
+        run: |
+          if sudo modprobe snd-dummy 2>/dev/null && test -e /dev/snd/pcmC0D0p; then
+            echo "method=snd-dummy" >> "$GITHUB_OUTPUT"
+          elif sudo apt-get install -y pulseaudio libasound2-plugins \
+               && pulseaudio --start --exit-idle-time=-1 \
+               && pactl load-module module-null-sink sink_name=numchuck; then
+            # Make it the default so the ALSA-to-PulseAudio bridge routes to it
+            # rather than to a card that does not exist.
+            pactl set-default-sink numchuck || true
+            echo "method=pulseaudio-null-sink" >> "$GITHUB_OUTPUT"
+          else
+            echo "method=none" >> "$GITHUB_OUTPUT"
+          fi
+          aplay -l || true
+          pactl list short sinks || true
+
+      - name: Build and install package
+        run: |
+          uv sync --reinstall-package numchuck
+
+      # -rs prints the reason for every skip, so a run that tested nothing says
+      # so in the log rather than passing quietly. Note that a device opening
+      # is not the same as a device producing audio: the null sink does the
+      # former and, so far, not the latter, so the tap tests skip themselves
+      # here with an explicit reason rather than passing on silence.
+      - name: Run real-time tests
+        if: steps.audio.outputs.method != 'none'
+        run: |
+          echo "audio device via ${{ steps.audio.outputs.method }}"
+          uv run pytest -v --tb=short -rs -m realtime
+
+      # A runner that cannot provide any audio device is a limitation of the
+      # environment, not a defect in the code, so it warns rather than failing
+      # the build -- but it must not be silent, or the workflow would look like
+      # it had covered the tap tests when it had not.
+      - name: Report a missing audio device
+        if: steps.audio.outputs.method == 'none'
+        run: |
+          echo "::warning title=Real-time tests skipped::No audio device could be created on this runner; the tap regression tests did not run."
+
+  docs:
+    name: Docs Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+        with:
+          enable-cache: true
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            bison \
+            flex
+
+      # mkdocstrings introspects the compiled extension to pull its docstrings,
+      # so the package has to be built before the docs can be.
+      - name: Build and install package
+        run: |
+          uv sync --group docs --reinstall-package numchuck
+
+      # --strict: a broken cross-reference or a page missing from the nav fails
+      # the build rather than shipping a dead link.
+      - name: Build documentation
+        run: |
+          uv run --group docs mkdocs build --strict
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+        with:
+          enable-cache: true
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            bison \
+            flex
+
+      - name: Build and install package
+        run: |
+          uv sync --reinstall-package numchuck
+
+      - name: Run mypy
+        run: |
+          uv run mypy --strict src/
+
+  coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            bison \
+            flex
+
+      - name: Install package with coverage
+        run: |
+          uv sync --reinstall-package numchuck
+          uv pip install --system pytest-cov
+
+      - name: Run tests with coverage
+        run: |
+          # Skip: realtime (no audio device), wavfile (WvOut timing), chugin (not bundled), tui (requires console)
+          uv run pytest --cov=numchuck --cov-report=xml --cov-report=term -k "not realtime and not wavfile and not chugin and not tui"

numchuck-0.4.0/.github/workflows/pip-test.yml

@@ -0,0 +1,47 @@
+name: Pip Install Test Suite
+
+on:
+  workflow_dispatch:
+
+jobs:
+  pip-test:
+    name: Test on ${{ matrix.os }} (Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - name: Checkout code (for tests only)
+        uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install numchuck from PyPI and test dependencies
+        run: |
+          pip install numchuck pytest numpy pytest-asyncio
+
+      - name: Verify using installed package (not local src)
+        run: |
+          python -c "
+          import numchuck
+          import os
+          # Verify the package is installed from site-packages, not local src/
+          pkg_path = numchuck.__file__
+          assert 'site-packages' in pkg_path, f'Expected site-packages in path, got: {pkg_path}'
+          print(f'numchuck installed at: {pkg_path}')
+          print(f'numchuck version: {numchuck.__version__}')
+          "
+
+      - name: Run tests
+        run: |
+          # Run from tests/ dir to avoid importing local src/
+          # Skip: realtime (no audio device), wavfile (WvOut timing), chugin (not bundled), tui (requires console)
+          cd tests
+          pytest . -v --tb=short -k "not realtime and not wavfile and not chugin and not tui"

numchuck-0.4.0/.github/workflows/wheels.yml

@@ -0,0 +1,169 @@
+name: Build Wheels
+
+on:
+  push:
+    tags:
+      - 'v*'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install system dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            cmake \
+            libasound2-dev \
+            libsndfile1-dev \
+            bison \
+            flex
+
+      - name: Install system dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew install bison flex
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.3.1
+        env:
+          # Build for Python 3.10-3.14
+          CIBW_BUILD: cp310-* cp311-* cp312-* cp313-* cp314-*
+          # Skip 32-bit builds and musllinux
+          CIBW_SKIP: "*-win32 *-manylinux_i686 *-musllinux_*"
+          # Linux: Install build dependencies (manylinux uses yum/dnf)
+          CIBW_BEFORE_BUILD_LINUX: >
+            yum install -y alsa-lib-devel libsndfile-devel bison flex ||
+            (apt-get update && apt-get install -y libasound2-dev libsndfile1-dev bison flex)
+          # macOS: Build universal wheels (x86_64 + arm64) via cross-compilation
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+          # macOS: Set deployment target (11.0 required for ARM64)
+          CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=11.0
+          CIBW_BEFORE_BUILD_WINDOWS: pip install delvewheel
+          # Repair wheels with .chug support (repair tools skip non-standard extensions)
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: python {project}/scripts/repair_wheel.py {wheel} {dest_dir}
+          CIBW_REPAIR_WHEEL_COMMAND_MACOS: python {project}/scripts/repair_wheel.py {wheel} {dest_dir} --delocate-archs {delocate_archs}
+          CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: python {project}/scripts/repair_wheel.py {wheel} {dest_dir}
+          # Test the built wheels
+          CIBW_TEST_REQUIRES: pytest numpy pytest-asyncio
+          # Skip: realtime (no audio device), wavfile (WvOut timing), tui (requires console)
+          CIBW_TEST_COMMAND: pytest {project}/tests -v --tb=short -k "not realtime and not wavfile and not tui"
+          # Skip: aarch64 Linux (cross-compiled, no native runner)
+          CIBW_TEST_SKIP: "*-manylinux_aarch64"
+
+      - name: Validate wheel RECORD
+        run: python scripts/check_wheel_record.py wheelhouse/*.whl
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+          retention-days: 30
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build sdist
+        run: python -m build --sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          retention-days: 30
+
+  collect:
+    name: Collect all wheels
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Download all wheel artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Download sdist
+        uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist
+
+      - name: List collected files
+        run: ls -la dist/
+
+      - name: Validate all wheel RECORDs
+        run: python scripts/check_wheel_record.py dist/*.whl
+
+      - name: Upload combined artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: all-wheels
+          path: dist/*
+          retention-days: 30
+
+  publish:
+    name: Publish to PyPI
+    needs: [collect]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/numchuck
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: all-wheels
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1