Migrate to uv & ruff, remove black and isort (#290)

## Summary

This PR migrates the project's tooling from pip/black/isort/flake8 to
uv/ruff, and renames `master` → `main` in CI.

### CI changes
- **uv**: replaced pip with uv for all package management in CI; `uv
venv` + `uv pip install` for virtual environment setup and dependency
installation
- **ruff**: replaced black (formatter) + isort (import sorter) + flake8
(linter) with a single `ruff` invocation; added a new `check` job that
runs `ruff format --diff`, `ruff check --select I,RUF022 --diff`
(isort), and `ruff check`
- **Branch rename**: updated CI trigger and publish step to target
`main` instead of `master`

### Script changes (`tests/`)
- `install-demo-module.sh`: replaced `pip install` with `uv pip install
--python <exe>` to install into the active venv without requiring pip to
be present (uv venv doesn't include pip by default)
- `check-demo-stubs-generation.sh`: replaced `black` + `isort` with
`ruff format` + `ruff check --select I,RUF022 --fix`; added dynamic
`--target-version` to handle PEP 695 syntax in Python 3.12+ stubs;
removed `--diff` flag from the fix step (diffs are shown later by `git
diff --exit-code`)
- `check-demo-errors-generation.sh`: removed `uv run` wrapper (not
compatible with tox's virtual env activation)

### tox changes
- Removed `requirements-dev.txt` dependency (replaced with inline `deps`
in tox.ini)
- Fixed parallel run: `PYTHON_TAG_FILE` now uses `{envtmpdir}` (per-env)
instead of a shared path under `{toxinidir}/tmp/`
- Added `cmeel-eigen` to `deps` so it's available during `commands_pre`
(cmake build)

### Reference stubs
- Reformatted all reference stubs under `tests/stubs/` with ruff (import
ordering and style differ slightly from isort+black)
- Updated `requirements.txt` files: removed `black` and `isort`, added
`ruff>=0.14.14`

### pyproject.toml
- Added `exclude = ["tests/stubs"]` to `[tool.ruff]` to prevent ruff
from parsing PEP 695 stub syntax (e.g. `def f[T](...)`) with a `py310`
target version

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Sergey Shumakov <skarn@Sergeys-MacBook-Pro.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/ci.yml

@@ -5,58 +5,60 @@ on:
   pull_request:
   push:
     branches:
-      - master
+      - main
     tags:
       - "v*"
 
 jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: astral-sh/setup-uv@v7
+      - name: Checkout
+        uses: actions/checkout@v5
+      - name: Install requirements
+        run: |
+          uv lock --check
+          uv sync
+      - name: Run Ruff as isort
+        run: uv run ruff check --select I,RUF022 --fix --diff ./pybind11_stubgen
+        if: ${{ failure() ||  success() }}
+      - name: Run Ruff format
+        run: uv run ruff format --diff ./pybind11_stubgen
+        if: ${{ failure() ||  success() }}
+      - name: Run Ruff
+        run: |
+          uv run ruff check --ignore F401,F821 .
+        if: ${{ failure() ||  success() }}
+
   build:
     name: Build wheel
     runs-on: ubuntu-latest
+    needs: [check]
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: "3.13"
 
-      - name: Install build
-        run: python -m pip --disable-pip-version-check install build
+      - uses: astral-sh/setup-uv@v7
 
       - name: Build sdist + wheel
-        run: python -m build
+        run: |
+          uv lock --check
+          uv build
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v6
         with:
           name: dist
           path: dist
 
-  format:
-    name: Format code
-    runs-on: ubuntu-latest
-    steps:
-      - name: Setup Python 3.13
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.13"
-      - name: Checkout
-        uses: actions/checkout@v5
-      - name: Install requirements
-        run: pip install -r requirements-dev.txt
-      - name: Run isort
-        run: isort --check --profile=black --diff ./pybind11_stubgen
-        if: ${{ failure() ||  success() }}
-      - name: Run black
-        run: black --diff ./pybind11_stubgen
-        if: ${{ failure() ||  success() }}
-      - name: Run flake8
-        run: |
-          flake8 \
-            --max-line-length=88 \
-            --extend-ignore=E203 \
-            --extend-exclude=venv/,.pytest_cache/,.ipynb_checkpoints/,tests/,tmp/,build/
-        if: ${{ failure() ||  success() }}
-
   tests:
     name: "Test 🐍 ${{ matrix.config.python }} • pybind-${{ matrix.config.pybind11-branch }} • ${{ matrix.config.numpy-format }}"
     runs-on: ubuntu-latest
@@ -159,31 +161,40 @@ jobs:
         with:
           python-version: ${{ matrix.config.python }}
 
+      - uses: astral-sh/setup-uv@v7
+
       - name: Update CMake
         uses: jwlawson/actions-setup-cmake@v2
         with:
-          # https://github.com/pybind/pybind11/blob/914c06fb252b6cc3727d0eedab6736e88a3fcb01/CMakeLists.txt#L13C34-L13C38
           cmake-version: ${{ matrix.config.cmake-version }}
 
+      - name: Create UV venv
+        run: |
+          uv venv .venv
+
       - name: Setup annotations on Linux
         if: runner.os == 'Linux'
-        run: python -m pip install pytest-github-actions-annotate-failures
+        run: uv pip install pytest-github-actions-annotate-failures
 
       - name: Install requirements
-        run: pip install -r "./tests/stubs/python-${{ matrix.config.python }}/requirements.txt"
+        run: uv sync --group dev --no-install-project
 
       - name: Install
         shell: bash
         working-directory: dist
-        run: python -m pip --disable-pip-version-check install *.whl
+        run: uv pip install --disable-pip-version-check *.whl
 
       - name: Install demo module
         shell: bash
-        run: ./tests/install-demo-module.sh --pybind11-branch "${{ matrix.config.pybind11-branch }}"
+        run: |
+          source .venv/bin/activate
+          ./tests/install-demo-module.sh --pybind11-branch "${{ matrix.config.pybind11-branch }}"
 
       - name: Check stubs generation
         shell: bash
-        run: ./tests/check-demo-stubs-generation.sh --stubs-sub-dir "stubs/python-${{ matrix.config.python }}/pybind11-${{ matrix.config.pybind11-branch }}/${{ matrix.config.numpy-format }}" --${{ matrix.config.numpy-format }}
+        run: |
+          source .venv/bin/activate
+          ./tests/check-demo-stubs-generation.sh --stubs-sub-dir "stubs/python-${{ matrix.config.python }}/pybind11-${{ matrix.config.pybind11-branch }}/${{ matrix.config.numpy-format }}" --${{ matrix.config.numpy-format }}
 
       - name: Archive patch
         uses: actions/upload-artifact@v6
@@ -196,7 +207,9 @@ jobs:
 
       - name: Check error generation
         shell: bash
-        run: ./tests/check-demo-errors-generation.sh "pybind11-${{ matrix.config.pybind11-branch }}"
+        run: |
+          source .venv/bin/activate
+          ./tests/check-demo-errors-generation.sh "pybind11-${{ matrix.config.pybind11-branch }}"
 
   test-cli-options:
     name: "Runs on 🐍 ${{ matrix.python }} • ${{ matrix.test-package }}"
@@ -219,28 +232,35 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
 
+      - uses: astral-sh/setup-uv@v7
+
       - name: Download build artifacts
         uses: actions/download-artifact@v6
         with:
           name: dist
           path: dist
 
+      - name: Create UV venv
+        run: |
+          uv venv .venv
+
       - name: Setup annotations on Linux
         if: runner.os == 'Linux'
-        run: python -m pip install pytest-github-actions-annotate-failures
+        run: uv pip install pytest-github-actions-annotate-failures
 
       - name: Install
         shell: bash
         working-directory: dist
-        run: python -m pip --disable-pip-version-check install *.whl
+        run: uv pip install --disable-pip-version-check *.whl
 
       - name: "Install ${{ matrix.test-package }}"
         shell: bash
-        run: pip install "${{ matrix.test-package }}"
+        run: uv pip install "${{ matrix.test-package }}"
 
       - name: Generate stubs
         shell: bash
         run: |
+          source .venv/bin/activate
           pybind11-stubgen "${{ matrix.test-package }}" -o flavour-1 --numpy-array-wrap-with-annotated
           pybind11-stubgen "${{ matrix.test-package }}" -o flavour-2 --numpy-array-remove-parameters
           pybind11-stubgen "${{ matrix.test-package }}" -o flavour-3 --print-invalid-expressions-as-is
@@ -249,7 +269,7 @@ jobs:
 
   publish:
     name: Publish distribution
-    needs: [build, format, tests, test-cli-options]
+    needs: [check, build, tests, test-cli-options]
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
     runs-on: ubuntu-latest
     permissions:

.gitignore

@@ -210,6 +210,9 @@ cython_debug/
 # VS Code
 .vscode/
 
+# Zed
+.zed/
+
 tmp
 *.patch
 *.zip

pyproject.toml

@@ -18,6 +18,18 @@ dynamic = ["readme"]
 Repository = "https://github.com/pybind/pybind11-stubgen"
 Issues = "https://github.com/pybind/pybind11-stubgen/issues"
 
+[dependency-groups]
+dev = [
+    "cmeel==0.59.0",
+    "cmeel-eigen==3.4.0.2",
+    "numpy~=1.20",
+    "pip",
+    "scipy~=1.0",
+    "typing_extensions>=4,<5",
+    "mypy>=1.19.1",
+    "ruff>=0.14.14",
+]
+
 [tool.setuptools.packages]
 find = {}
 
@@ -26,3 +38,18 @@ readme = {file = ["README.md"], content-type = "text/markdown"}
 
 [project.entry-points.console_scripts]
 pybind11-stubgen = "pybind11_stubgen.__init__:main"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+exclude = ["tests/stubs"]
+
+[tool.ruff.lint]
+ignore = ["F403"]  # undefined names imported (triggered by native extensions)
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 88

requirements-dev.txt

@@ -2,8 +2,6 @@
 
 set -e
 
-PYTHON_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')
-
 resolve_path() {
   local path="$1"
 
@@ -55,7 +53,7 @@ remove_stubs() {
 }
 
 run_stubgen() {
-  ${PYTHON_EXECUTABLE} -m pybind11_stubgen \
+  pybind11-stubgen \
       demo \
       --output-dir=${STUBS_DIR} \
       ${NUMPY_FORMAT} \
@@ -69,8 +67,9 @@ run_stubgen() {
 format_stubs() {
   (
     cd "${STUBS_DIR}" ;
-    black . ;
-    isort --profile=black . ;
+    PYTHON_TARGET=$(python -c "import sys; print(f'py{sys.version_info.major}{sys.version_info.minor}')")
+    ruff format --target-version "${PYTHON_TARGET}" .
+    ruff check --select I,RUF022 --fix --target-version "${PYTHON_TARGET}" .
   )
 }
 

tests/check-demo-stubs-generation.sh

@@ -18,6 +18,7 @@ resolve_path() {
   fi
 }
 
+
 function parse_args() {
 
   CLEAR='\033[0m'
@@ -84,7 +85,7 @@ install_pydemo() {
   (
     export CMAKE_PREFIX_PATH="$(resolve_path "${INSTALL_PREFIX}"):$(cmeel cmake)";
     rm -rf ${TESTS_ROOT}/py-demo/build
-    ${PYTHON_EXECUTABLE} -m pip install --force-reinstall "${TESTS_ROOT}/py-demo"
+    uv pip install --python "${PYTHON_EXECUTABLE}" --force-reinstall "${TESTS_ROOT}/py-demo"
   )
 }
 

tests/install-demo-module.sh

@@ -2,12 +2,11 @@ from __future__ import annotations
 
 import typing
 
-import numpy
-from numpy import random
-
 import demo._bindings.enum
+import numpy
 from demo._bindings.aliases.foreign_method_arg import Bar2 as foreign_type_alias
 from demo._bindings.aliases.foreign_return import get_foo as foreign_class_alias
+from numpy import random
 
 from . import (
     foreign_arg,

tests/stubs/python-3.10/pybind11-v3.0/numpy-array-wrap-with-annotated/demo/_bindings/aliases/__init__.pyi

@@ -61,12 +61,12 @@ def four_col_matrix_r(
 def four_row_matrix_r(
     arg0: typing.Annotated[numpy.typing.ArrayLike, numpy.float32, "[4, n]"],
 ) -> typing.Annotated[numpy.typing.NDArray[numpy.float32], "[4, n]"]: ...
-def get_matrix_int() -> (
-    typing.Annotated[numpy.typing.NDArray[numpy.int32], "[3, 3]"]
-): ...
-def get_vector_float64() -> (
-    typing.Annotated[numpy.typing.NDArray[numpy.float64], "[3, 1]"]
-): ...
+def get_matrix_int() -> typing.Annotated[
+    numpy.typing.NDArray[numpy.int32], "[3, 3]"
+]: ...
+def get_vector_float64() -> typing.Annotated[
+    numpy.typing.NDArray[numpy.float64], "[3, 1]"
+]: ...
 def sparse_matrix_c(
     arg0: typing.Annotated[scipy.sparse.csc_matrix, numpy.float32],
 ) -> typing.Annotated[scipy.sparse.csc_matrix, numpy.float32]: ...

tests/stubs/python-3.10/pybind11-v3.0/numpy-array-wrap-with-annotated/demo/_bindings/eigen.pyi

@@ -4,9 +4,9 @@ import typing
 
 __all__: list[str] = [
     "backslashes_should_be_escaped",
-    "issue_274_docstring_leading_newline",
     "issue_51_catastrophic_regex",
     "issue_73_utf8_doc_chars",
+    "issue_274_docstring_leading_newline",
 ]
 
 def backslashes_should_be_escaped() -> None:

tests/stubs/python-3.10/pybind11-v3.0/numpy-array-wrap-with-annotated/demo/_bindings/issues.pyi

@@ -43,27 +43,23 @@ class WithPropDoc:
         """
         prop doc token
         """
-
     @def_property.setter
     def def_property(self, arg1: typing.SupportsInt | typing.SupportsIndex) -> None: ...
     @property
     def def_property_readonly(self) -> int:
         """
         prop doc token
         """
-
     @property
     def def_readonly(self) -> int:
         """
         prop doc token
         """
-
     @property
     def def_readwrite(self) -> int:
         """
         prop doc token
         """
-
     @def_readwrite.setter
     def def_readwrite(
         self, arg0: typing.SupportsInt | typing.SupportsIndex
@@ -81,13 +77,11 @@ class WithGetterSetterDoc:
         """
         getter doc token
         """
-
     @def_property.setter
     def def_property(self, arg1: typing.SupportsInt | typing.SupportsIndex) -> None:
         """
         setter doc token
         """
-
     @property
     def def_property_readonly(self) -> int:
         """
@@ -106,7 +100,6 @@ class WithPropAndGetterSetterDoc:
         """
         prop doc token
         """
-
     @def_property.setter
     def def_property(self, arg1: typing.SupportsInt | typing.SupportsIndex) -> None: ...
     @property