Documentation and Testing Rework

.github/workflows/python-publish.yml

@@ -6,15 +6,14 @@ on:
 
 jobs:
   deploy:
-
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
-        python-version: '3.x'
+        python-version: '3.11.x'
         cache: 'pip'
     - name: Install dependencies
       run: |

.github/workflows/python-test.yml

@@ -4,42 +4,153 @@ on: [ pull_request, workflow_dispatch ]
 
 jobs:
   test-docs:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.9.x'
+          python-version: '3.11.x'
           cache: 'pip'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r docs/requirements.txt
-          sudo apt-get update && sudo apt-get install -y enchant-2 aspell-en
+          sudo apt-get update && sudo apt-get install -y enchant-2
       - name: Build Docs
         run: |
           cd docs
           make clean
           make html
+      - name: Spelling Check
+        run: |
+          cd docs
+          make spelling
+      - name: Test Code Snippets
+        run: |
+          cd docs
+          make doctest
+      - name: Link Check
+        run: |
+          cd docs
           make linkcheck
-  test:
-    runs-on: ubuntu-22.04
+
+  test-container:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+      fail-fast: false
+    permissions:
+      pages: write
+      id-token: write
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.9.x'
+          python-version: ${{ matrix.python-version }}
           cache: 'pip'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r tests/requirements.txt
+          pip install "coverage[toml]"
       - name: Add DBus Config
         run: |
-          sudo cp tests/com.spacecheese.test.conf /etc/dbus-1/system.d
+          sudo cp tests/unit/com.spacecheese.test.conf /etc/dbus-1/system.d
       - name: Run Tests
         run: |
-          python -m unittest discover -s tests -p "test_*.py" -v
+          coverage run --source=. --branch -m pytest tests/unit -v
+      - name: Report Coverage
+        run: |
+          coverage html
+          coverage report -m
+      - name: Upload Coverage Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: htmlcov/
+
+  test-qemu:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        image_id: ["ubuntu-24.04-bluez-5.64", "ubuntu-24.04-bluez-5.66", "ubuntu-24.04-bluez-5.70"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y qemu-system-x86 qemu-utils
+      - name: Download qemu images
+        env:
+          image_repo: "spacecheese/bluez_images"
+        run: |
+          image_id=${{ matrix.image_id }}
+          mkdir -p tests/loopback/assets
+          curl -L -o tests/loopback/assets/id_ed25519 \
+            https://github.com/$image_repo/releases/latest/download/id_ed25519
+          chmod 600 tests/loopback/assets/id_ed25519
+          curl -L -o tests/loopback/assets/image.qcow2 \
+            https://github.com/$image_repo/releases/latest/download/${image_id}.qcow2
+      - name: Run loopback Tests
+        run: |
+          tests/loopback/test.sh tests/loopback/assets/image.qcow2 tests/loopback/assets/id_ed25519 .
+
+  format-check:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11.x'
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install black
+      - name: Check Formatting
+        run: |
+          python -m black --check bluez_peripheral
+          python -m black --check tests
+
+  type-hint-check:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11.x'
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install mypy
+      - name: Check type hints
+        run: |
+          python -m mypy bluez_peripheral
+
+  lint-check:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11.x'
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pylint
+      - name: Run lint checks
+        run: |
+          python -m pylint bluez_peripheral
 

.gitignore

@@ -138,4 +138,7 @@ dmypy.json
 cython_debug/
 
 # VSCode Config Files
-.vscode/
+.vscode/
+
+# Testing images
+tests/loopback/assets

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 25.12.0
+    hooks:
+      - id: black
+        name: black (code formatting)
+        files: ^(bluez_peripheral/|tests/)
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        name: mypy (type hints)
+        additional_dependencies:
+          - dbus_fast
+        files: ^bluez_peripheral/
+
+  - repo: https://github.com/pylint-dev/pylint
+    rev: v4.0.4
+    hooks:
+      - id: pylint
+        additional_dependencies:
+          - dbus_fast
+        files: ^bluez_peripheral/
+
+  - repo: local
+    hooks:
+      - id: docs-build
+        name: docs (build)
+        entry: bash -c "cd docs && make clean && make html"
+        language: system
+        pass_filenames: false
+        stages: [manual]
+
+      - id: docs-spelling
+        name: docs (spell check)
+        entry: bash -c "cd docs && make spelling"
+        language: system
+        pass_filenames: false
+        stages: [manual]
+
+      - id: docs-doctest
+        name: docs (test code snippets)
+        entry: bash -c "cd docs && make doctest"
+        language: system
+        pass_filenames: false
+        stages: [manual]
+
+      - id: docs-linkcheck
+        name: docs (linkcheck)
+        entry: bash -c "cd docs && make linkcheck"
+        language: system
+        pass_filenames: false
+        stages: [manual]

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+Contributions of are encouraged and greatly appreciated.
+
+## Getting Started
+Code must pass the following CI checks before it will be accepted:
+- Be preformatted with [black](https://github.com/psf/black)
+- A mypy type hinting check
+- A pylint check (including full docstring coverage)
+- shphinx linkcheck, spelling and doctest (code snippet tests)
+- Unit and end-to-end tests
+
+Most of these checks can be run locally using [pre-commit](https://pre-commit.com/). To configure this run:
+```bash
+pip install pre-commit
+pre-commit install
+```
+pylint, mypy and formatting checks will then be automatically run as part of your git hooks. sphinx tests can also be run by pre-commit, though you must first install some additional dependencies to build the documentation:
+```bash
+pip install -r docs/requirements.txt
+sudo apt-get install enchant-2 # This depends on your distribution- for more see the pyenchant documentation
+```
+You can then run all pre-commit checks manually:
+```bash
+pre-commit run --hook-stage manual --all-files
+```
+
+For instructions on running tests locally please consult the respective markdown files- this process more more complex since bluez, dbus and the hci_vhci kernel module are required.

README.md

@@ -22,29 +22,25 @@ Install bluez (eg. `sudo apt-get install bluez`)
 
 ## GATT Overview
 
-GATT is a BLE protocol that allows you to offer services to other devices.
-You can find a list of standardised services on the [Bluetooth SIG website](https://www.bluetooth.com/specifications/specs/) (you can largely ignore profiles when working with BLE). You should refer to the "Service Characteristics" in these specifications for the purposes of this library.
+GATT is a protocol that allows you to offer services to other devices. 
+You can find a list of standardized services on the [Bluetooth SIG website](https://www.bluetooth.com/specifications/specs/).
 
-![Peripheral Hierarchy Diagram](https://doc.qt.io/qt-5/images/peripheral-structure.png)
+![Peripheral Hierarchy Diagram](https://doc.qt.io/qt-6/images/peripheral-structure.png)
 
 _Courtesey of Qt documentation (GNU Free Documentation License)_
 
-A peripheral defines a list of services that it provides. Services are a collection of characteristics which expose particular data (eg. a heart rate or mouse position). Characteristics may also have descriptors that contain metadata (eg. the units of a characteristic). Services can optionally include other services. All BLE attributes (Services, Characterisics and Descriptors) are identified by a 16-bit number [assigned by the Bluetooth SIG](https://www.bluetooth.com/specifications/assigned-numbers/).
+A peripheral defines a list of services that it provides. Services are a collection of characteristics which expose particular data (eg. a heart rate or mouse position). Characteristics may also have descriptors that contain metadata (eg. the units of a characteristic). Services can optionally include other services. All BLE attributes (Services, Characteristics and Descriptors) are identified by a 16-bit number [assigned by the Bluetooth SIG](https://www.bluetooth.com/specifications/assigned-numbers/).
 
-Characteristics may operate in a number of modes depending on their purpose. By default characteristics are read-only in this library however they may also be writable and provide notification (like an event system) when their value changes. Additionally some characteristics require security protection. You can read more about BLE on the [Bluetooth SIG blog](https://www.bluetooth.com/blog/a-developers-guide-to-bluetooth/).
+Characteristics may operate in a number of modes depending on their purpose. By default characteristics are read-only in this library however they may also be writable and provide notification (like an event system) when their value changes. Additionally some characteristics may require security protection. You can read more about BLE on the [Bluetooth SIG blog](https://www.bluetooth.com/blog/a-developers-guide-to-bluetooth/). [This video](https://www.youtube.com/watch?v=BZwOrQ6zkzE) gives a more in-depth overview of BLE.
 
 ## Usage
 
-There are a few important things you need to remember when using this library:
-
-- **Do not attempt to create the Generic Access Service or a Client Characteristic Configuration Descriptor** (if you don't know what this means don't worry). These are both handled automatically by Bluez and attempting to define them will result in errors.
-- Services are not implicitly threaded. **If you register a service in your main thread blocking that thread will stop your service (and particularly notifications) from working**. Therefore you must frequently yeild to the asyncio event loop (for example using asyncio.sleep) and ideally use multithreading.
+When using this library please remember that services are not implicitly threaded. **The thread used to register your service must regularly yeild otherwise your service will not work** (particularly notifications). Therefore you must frequently yield to the asyncio event loop (for example using asyncio.sleep) and ideally use multithreading.
 
 The easiest way to use the library is to create a class describing the service that you wish to provide.
 
 ```python
-from bluez_peripheral.gatt.service import Service
-from bluez_peripheral.gatt.characteristic import characteristic, CharacteristicFlags as CharFlags
+from bluez_peripheral.gatt import Service, characteristic, CharacteristicFlags as CharFlags
 
 import struct
 
@@ -89,15 +85,16 @@ async def main():
     service = HeartRateService()
     await service.register(bus)
 
-    # An agent is required to handle pairing
+    # An agent is required if you wish to handle pairing.
     agent = NoIoAgent()
-    # This script needs superuser for this to work.
+    # This line needs superuser for this to work.
     await agent.register(bus)
 
     adapter = await Adapter.get_first(bus)
 
     # Start an advert that will last for 60 seconds.
-    advert = Advertisement("Heart Monitor", ["180D"], 0x0340, 60)
+    advert = Advertisement("Heart Monitor", ["180D"], 
+        appearance=0x0340, timeout=60)
     await advert.register(bus, adapter)
 
     while True:

bluez_peripheral/__init__.py

@@ -0,0 +1,3 @@
+from .advert import Advertisement
+from .uuid16 import UUID16
+from .util import get_message_bus