Add poethepoet config

.github/alpine-vm/start-alpine-vm.sh

@@ -21,7 +21,7 @@ VM_BUILD_DIR="$REPO_ROOT/.alpine-vm-build"
 VM_IMAGE="$VM_BUILD_DIR/alpine.qcow2"
 VM_SSH_PORT="2222"
 VM_CONSOLE_LOG="vm-console.log"
-VM_PACKAGES="bluez openssh uv"
+VM_PACKAGES="bluez openssh uv git"
 
 # Colors for output
 GREEN='\033[0;32m'

.github/workflows/build_and_test.yml

@@ -17,7 +17,9 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["310", "311", "312", "313", "314"]
+    env:
+      FORCE_COLOR: "1"
     steps:
       - uses: actions/checkout@v4
 
@@ -28,7 +30,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Test with pytest
-        run: uv run pytest -v --cov-report=xml --junitxml=junit.xml -o junit_family=legacy
+        run: uv run poe test-py${{ matrix.python-version }} --cov-report=xml --junitxml=junit.xml -o junit_family=legacy
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
@@ -45,31 +47,21 @@ jobs:
           flags: ${{ matrix.os }}-py${{ matrix.python-version }}
           token: ${{ secrets.CODECOV_TOKEN }}
 
-      # We don't do type checking in the lint job because we have conditionals
-      # on both the platform and the Python version in the code, so we
-      # need to check each matrix combination.
-      #
-      # We want always the latest version of pyright and mypy, to catch
-      # any breakage as soon as we can. That is why they are not dev
-      # dependencies in the pyproject.toml, because that would lock them to
-      # a specific version. Instead we install the latest version as tool.
-      - name: Type checking (pyright)
-        run: |
-          uv tool install pyright
-          uv run pyright
+      - name: Type checking
+        # We don't do this in the lint job because we have conditionals
+        # on both the platform and the Python version in the code, so we
+        # need to check each matrix combination.
 
-      - name: Type checking (mypy)
         run: |
-          uv tool install mypy
-          uv run mypy -p bleak -p tests -p examples
+          uv run poe typecheck
 
   integration_tests_bluez:
     name: "BlueZ integration tests"
     runs-on: "ubuntu-latest"
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["310", "311", "312", "313", "314"]
     steps:
       - uses: actions/checkout@v4
 
@@ -91,7 +83,7 @@ jobs:
             export FORCE_COLOR=1
             export CI=true
             export GITHUB_ACTIONS=true
-            uv run --python ${{ matrix.python-version }} pytest -v tests --bleak-bluez-vhci -v --cov-report=xml --cov-report=html:../.htmlcov --junitxml=junit.xml -o junit_family=legacy -o cache_dir=../.pytest_cache
+            uv run poe test-py${{ matrix.python-version }} --bleak-bluez-vhci --cov-report=xml --cov-report=html:../.htmlcov --junitxml=junit.xml -o junit_family=legacy -o cache_dir=../.pytest_cache
           '
 
       - name: Upload coverage reports to Codecov

.github/workflows/format_and_lint.yml

@@ -18,14 +18,8 @@ jobs:
         with:
           version: "latest"
 
-      - name: Check import sort with isort
-        run: uv run isort {.,docs} --check --diff
-
-      - name: Check code formatting with black
-        run: uv run black . --check --diff
-
-      - name: Lint with flake8
-        run: uv run flake8 . --count --show-source --statistics
+      - name: Check import sort with isort, code formatting with black, and lint with flake8
+        run: uv run poe lint --checkonly
 
       - name: Build docs
-        run: uv run make -C docs html
+        run: uv run poe docs

CONTRIBUTING.rst

@@ -79,17 +79,16 @@ and your favorite text editor. And Python of course.
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass linting and the tests::
+5. When you're done making changes, check that your changes pass linting, type checking and the tests::
 
-    $ uv run isort .
-    $ uv run black .
-    $ uv run flake8
-    $ uv run pytest
+    $ uv run poe lint
+    $ uv run poe typecheck
+    $ uv run poe test-all
 
 6. Additionally, you can run integration tests by adding the ``--bleak-hci-transport`` argument to ``pytest``.
 For more information, see `tests/integration/README.rst <tests/integration/README.rst>`_.
 
-  $ uv run pytest --bleak-hci-transport=serial:/dev/tty.usbmodem1101
+  $ uv run poe test-all --bleak-hci-transport=serial:/dev/tty.usbmodem1101
 
 7. Commit your changes and push your branch to GitHub::
 

pyproject.toml

@@ -59,6 +59,7 @@ test = [
     "bumble==0.0.226",
 ]
 dev = [
+    "poethepoet>=0.45.0",
     { include-group = "docs" },
     { include-group = "lint" },
     { include-group = "test" },
@@ -83,6 +84,7 @@ python_version = "3.10"
 disable_error_code = ["import-not-found"]
 exclude = "(.venv|kivy|recipes)/"
 mypy_path = "typings"
+packages = ["bleak", "tests", "examples"]
 
 [tool.pyright]
 typeCheckingMode = "strict"
@@ -100,7 +102,77 @@ filterwarnings = [
 ]
 
 addopts = """
+--import-mode=importlib
 --cov=bleak
 --cov-branch
 --cov-report html
 """
+
+
+
+[tool.poe.executor]
+type = "uv"
+isolated = true
+
+[tool.poe.tasks.test-py310]
+help = "Run tests using Python 3.10"
+cmd = "pytest tests -v $POE_EXTRA_ARGS"
+executor = { python = "3.10", group = "test" }
+
+[tool.poe.tasks.test-py311]
+help = "Run tests using Python 3.11"
+cmd = "pytest tests -v $POE_EXTRA_ARGS"
+executor = { python = "3.11", group = "test" }
+
+[tool.poe.tasks.test-py312]
+help = "Run tests using Python 3.12"
+cmd = "pytest tests -v $POE_EXTRA_ARGS"
+executor = { python = "3.12", group = "test" }
+
+[tool.poe.tasks.test-py313]
+help = "Run tests using Python 3.13"
+cmd = "pytest tests -v $POE_EXTRA_ARGS"
+executor = { python = "3.13", group = "test" }
+
+[tool.poe.tasks.test-py314]
+help = "Run tests using Python 3.14"
+cmd = "pytest tests -v $POE_EXTRA_ARGS"
+executor = { python = "3.14", group = "test" }
+
+[tool.poe.tasks.test-all]
+help = "Run tests using all supported Python versions"
+sequence = [
+    "test-py310",
+    "test-py311",
+    "test-py312",
+    "test-py313",
+    "test-py314",
+]
+
+[tool.poe.tasks.typecheck]
+help = "Run type checkers (mypy, pyright)"
+
+# We want always the latest version of pyright and mypy, to catch
+# any breakage as soon as we can. That is why they are not dev
+# dependencies in the pyproject.toml, because that would lock them to
+# a specific version. Instead we install the latest version as tool.
+sequence = [
+    { cmd = "mypy", executor = { with = "mypy" } },
+    { cmd = "pyright", executor = { with = "pyright" } },
+]
+
+[tool.poe.tasks.lint]
+help = "Run code linters (isort, black, flake8)"
+sequence = [
+    { cmd = "isort . ${checkonly:+--check --diff}", executor = { group = "lint" } },
+    { cmd = "isort docs ${checkonly:+--check --diff}", executor = { group = "lint" } },
+    { cmd = "black . ${checkonly:+--check --diff}", executor = { group = "lint" } },
+    { cmd = "flake8 . --count --show-source --statistics", executor = { group = "lint" } },
+]
+args = [{ name = "checkonly", type = "boolean" }]
+executor = { group = "lint" }
+
+[tool.poe.tasks.docs]
+help = "Build the documentation"
+cmd = "sphinx-build -b html -W -d docs/_build/doctrees docs docs/_build/html"
+executor = { python = "3.11", group = "docs" }