Skip to content

Commit 2cb5c06

Browse files
Merge pull request #10 from scottmckenzie/feature/migrate-to-uv
build: migrate to uv, pytest, ruff and pyrefly
2 parents 2b62c03 + 48b7795 commit 2cb5c06

15 files changed

Lines changed: 951 additions & 89 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [master]
6+
pull_request:
7+
8+
jobs:
9+
lint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v5
13+
- uses: astral-sh/setup-uv@v6
14+
- run: uv sync --locked
15+
- run: uv run ruff check .
16+
- run: uv run ruff format --check .
17+
- run: uv run pyrefly check
18+
19+
test:
20+
runs-on: ubuntu-latest
21+
strategy:
22+
fail-fast: false
23+
matrix:
24+
python-version: ["3.9", "3.14"]
25+
steps:
26+
- uses: actions/checkout@v5
27+
- uses: astral-sh/setup-uv@v6
28+
with:
29+
python-version: ${{ matrix.python-version }}
30+
- run: uv sync --locked
31+
- run: uv run pytest
32+
33+
build:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- uses: actions/checkout@v5
37+
- uses: astral-sh/setup-uv@v6
38+
- run: uv build

‎CLAUDE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# holman-linux-python
2+
3+
Python SDK and `holmanctl` CLI for controlling Holman Bluetooth tap timers (CO3015, BTX1/CO3011) on Linux via BlueZ.
4+
5+
## Tech Stack
6+
- Python 3, built on the `gatt` library (which wraps BlueZ's D-Bus API)
7+
- `python3-dbus` comes from apt, not PyPI, and is not in `dependencies`
8+
- Managed with uv; `pyproject.toml` (hatchling backend) is the only packaging config; published to PyPI as `holman`
9+
10+
## Layout
11+
- `holman/holman.py` — the whole SDK: `TapTimerManager` (discovery), `TapTimer` (connection + control), and the two listener base classes
12+
- `holman/__init__.py` — public API re-exports; update it when adding public classes
13+
- `holmanctl.py` — demo/test CLI, installed as the `holmanctl` console script
14+
- `tests/` — pytest suite; `conftest.py` swaps `gatt` for an in-memory fake (real `gatt` calls `sys.exit` on import without dbus)
15+
- `typings/gatt/` — pyrefly stub pinning `gatt` to its BlueZ backend (it picks a backend at runtime, which the checker can't narrow)
16+
17+
## Development
18+
- Before finishing a change, run `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .` and `uv run pyrefly check`
19+
- CI (`.github/workflows/ci.yml`) runs the same checks, with pytest on Python 3.9 and 3.14; keep `requires-python` and that matrix in sync
20+
- Ruff formats the Python snippets in `README.md` too
21+
- Tests run with `--import-mode=importlib`, so share test helpers as fixtures in `conftest.py`, not by importing modules from `tests/`
22+
- Tests cover logic only; when adding a `gatt` API call, add it to the fakes in `tests/conftest.py`
23+
- Real verification needs hardware: a tap timer in range, `bluetoothd` running, and root (`sudo holmanctl --discover`, `--connect <MAC>`)
24+
- Event-driven: nothing happens until `TapTimerManager.run()` starts the GLib loop; results arrive through listener callbacks, not return values
25+
26+
## Device Protocol
27+
- Supported models are identified by GATT service UUID — `holman/holman.py:90-95`. A new model means adding its UUID to `SERVICE_UUIDS`
28+
- Discovery also filters on the BLE alias `'Tap Timer'` — `holman/holman.py:41`
29+
- Start/stop write a 4-byte value to the manual characteristic (byte 0 = on/off, byte 3 = minutes, capped at 255) — `holman/holman.py:228-243`
30+
- On/off state is the last byte of the state characteristic — `holman/holman.py:217-221`
31+
- Battery level is not decoded yet (`battery_level()` always returns `None`)
32+
33+
## Releasing
34+
- Bump `version` in `pyproject.toml`, then `uv lock`, `uv build` and `uv publish`
35+
36+
## Python Version
37+
38+
Python 3.9 minimum (`requires-python` in pyproject.toml; ruff and pyrefly also target 3.9). Use the newest syntax 3.9 supports:
39+
- `list[str]` instead of `List[str]`
40+
- `dict[str, Any]` instead of `Dict[str, Any]`
41+
- `tuple[int, str]` instead of `Tuple[int, str]`
42+
- `X | None` instead of `Optional[X]` only in annotations, with `from __future__ import annotations` at the top of the module; `|` between types fails at runtime on 3.9 anywhere else (e.g. `isinstance`, aliases)
43+
- No `match` statements (3.10) or `type X = ...` aliases (3.12); use `if`/`elif` and plain `X = ...` alias assignments (`typing.TypeAlias` is 3.10+, and `typing_extensions` isn't a dependency)
44+
45+
## Manage packages
46+
47+
This project uses uv. Do not use pip, pip-tools, poetry, or conda.
48+
49+
- Add runtime dependency: `uv add <package>` (writes to `[project.dependencies]`)
50+
- Add dev dependency: `uv add --dev <package>` (writes to `[dependency-groups]` per PEP 735)
51+
- Remove dependency: `uv remove <package>`
52+
- Sync environment from lockfile: `uv sync`
53+
- Regenerate lockfile from constraints: `uv lock`
54+
- Upgrade locked versions: `uv lock --upgrade`
55+
- Commit `uv.lock` to version control (current uv guidance is to commit it for applications, CLIs, and libraries)
56+
57+
## Run code
58+
59+
Always use `uv run` to execute Python code and tools. Never call `python`, `pytest`, `ruff`, or other tools directly. They may not resolve to the project's virtual environment.
60+
61+
- Run a script: `uv run python script.py`
62+
- Run a module: `uv run python -m module_name`
63+
- Run a tool: `uv run pytest`, `uv run ruff check .`
64+
- One-off tool (not a project dependency): `uvx <tool>`
65+
66+
## Test code
67+
68+
- Framework: pytest
69+
- Run tests: `uv run pytest`
70+
- Test files go in `tests/` at the project root
71+
- Test file naming: `test_*.py`
72+
- Test function naming: `test_*`
73+
- No `__init__.py` needed in `tests/`
74+
- Coverage: `uv add --dev coverage`, then `uv run coverage run -m pytest` and `uv run coverage report`
75+
76+
## Lint and format code
77+
78+
- Tool: ruff (handles both linting and formatting)
79+
- Lint: `uv run ruff check .`
80+
- Lint and auto-fix: `uv run ruff check --fix .`
81+
- Format: `uv run ruff format .`
82+
- Check formatting: `uv run ruff format --check .`
83+
- Configuration lives in `pyproject.toml` under `[tool.ruff]`
84+
85+
## Check types
86+
87+
- Tool: pyrefly (preferred), ty, or mypy
88+
- Run: `uv run pyrefly check`, `uv run ty check`, or `uv run mypy .`
89+
- Configuration lives in `pyproject.toml` under `[tool.pyrefly]`, `[tool.ty]`, or `[tool.mypy]`
90+
91+
## Avoid these practices
92+
93+
- Do not create or activate virtual environments manually. uv manages `.venv/` automatically.
94+
- Do not install packages globally or with `pip install`.
95+
- Do not create `requirements.txt` for dependency management. Use `pyproject.toml` and `uv.lock`.
96+
- Do not run `python setup.py` commands.
97+
- Do not add dependencies to pyproject.toml by hand. Use `uv add`.
98+
- If you must edit pyproject.toml directly, write dev dependencies under `[dependency-groups]` (PEP 735), not the legacy `[tool.uv.dev-dependencies]` table.
99+
100+
## Development Standards
101+
102+
### Git Workflow
103+
- Branch names: `feature/description` or `fix/description`
104+
- Commit messages: Follow conventional commits
105+
- PR required before merge
106+
- All CI/CD checks must pass
107+
- Minimum 1 approval required
108+
109+
### Testing Requirements
110+
- Minimum 80% code coverage
111+
- All critical paths must have tests
112+

‎README.md‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ and [BTX1](https://www.holmanindustries.com.au/products/btx1-tap-mounted-smart-v
55
The Holman Python SDK for Linux allows you to integrate your Holman(s) into any type of Linux application or script that can execute Python code.
66

77
## Prerequisites
8-
The Holman SDK requires [Python 3.4+](https://www.python.org) and a recent installation of [BlueZ](http://www.bluez.org/). It is tested to work fine with BlueZ 5.44, slightly older versions should however work, too.
8+
The Holman SDK requires [Python 3.9+](https://www.python.org) and a recent installation of [BlueZ](http://www.bluez.org/). It is tested to work fine with BlueZ 5.44, slightly older versions should however work, too.
99

1010
## Installation
1111
These instructions assume a Debian-based Linux.
@@ -87,11 +87,13 @@ Please note that communication with your Bluetooth adapter happens over BlueZ's
8787
```python
8888
import holman
8989

90+
9091
class TapTimerManagerPrintListener(holman.TapTimerManagerListener):
9192
def tap_timer_discovered(self, tap_timer):
9293
print("Discovered Holman tap_timer", tap_timer.mac_address)
9394

94-
manager = holman.TapTimerManager(adapter_name='hci0')
95+
96+
manager = holman.TapTimerManager(adapter_name="hci0")
9597
manager.listener = TapTimerManagerPrintListener()
9698
manager.start_discovery()
9799
manager.run()
@@ -108,10 +110,11 @@ The following example connects to a Holman tap timer manually:
108110
```python
109111
import holman
110112

111-
manager = holman.TapTimerManager(adapter_name='hci0')
113+
manager = holman.TapTimerManager(adapter_name="hci0")
112114

113-
tap_timer = holman.TapTimer(mac_address='AA:BB:CC:DD:EE:FF', manager=manager)
114-
tap_timer.listener = holman.TapTimerListener() # Use an instance of your own holman.TapTimerListener subclass
115+
tap_timer = holman.TapTimer(mac_address="AA:BB:CC:DD:EE:FF", manager=manager)
116+
# Use an instance of your own holman.TapTimerListener subclass
117+
tap_timer.listener = holman.TapTimerListener()
115118
tap_timer.connect()
116119

117120
manager.run()
@@ -123,6 +126,28 @@ As with Holman tap timer discovery, remember to start the Bluetooth event loop w
123126

124127
Once a Holman tap timer is connected you can start the tap with `TapTimer.start(runtime=1)`. Pass this a runtime (in minutes) for how long to run the tap.
125128

129+
## Development
130+
131+
The project uses [uv](https://docs.astral.sh/uv/) for environment and dependency management.
132+
133+
```
134+
uv sync # create .venv with the SDK and dev tools
135+
uv run pytest # run the tests (no Bluetooth hardware needed)
136+
uv run ruff check . # lint
137+
uv run ruff format . # format
138+
uv run pyrefly check # type check
139+
uv build # build sdist and wheel into dist/
140+
```
141+
142+
The tests replace the `gatt` library with an in-memory fake (`tests/conftest.py`), so they don't need `python3-dbus` or `bluetoothd`. Testing against a real tap timer still requires the system setup above; to use the apt-installed `python3-dbus` and `python3-gi` from the uv environment, create it on the system interpreter they were built for, then run `holmanctl` from it:
143+
144+
```
145+
sudo apt-get install python3-dbus python3-gi
146+
uv venv --system-site-packages --python /usr/bin/python3
147+
uv sync
148+
sudo .venv/bin/holmanctl --discover
149+
```
150+
126151
## Support
127152

128153
Please open an issue.

‎holman/__init__.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
from .holman import TapTimerManager, TapTimerManagerListener, TapTimer, TapTimerListener
1+
from .holman import TapTimer, TapTimerListener, TapTimerManager, TapTimerManagerListener
2+
3+
__all__ = [
4+
"TapTimer",
5+
"TapTimerListener",
6+
"TapTimerManager",
7+
"TapTimerManagerListener",
8+
]

‎holman/holman.py‎

Lines changed: 52 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
"""
22
Module for managing Holman Bluetooth tap timers.
33
"""
4+
45
import gatt
56

67

@@ -9,7 +10,7 @@ class TapTimerManager(gatt.DeviceManager):
910
Entry point for managing and discovering Holman ``TapTimer``s.
1011
"""
1112

12-
def __init__(self, adapter_name='hci0'):
13+
def __init__(self, adapter_name="hci0"):
1314
"""
1415
Instantiates a ``TapTimerManager``
1516
@@ -36,9 +37,8 @@ def start_discovery(self, service_uuids=None):
3637
super().start_discovery(service_uuids=TapTimer.SERVICE_UUIDS)
3738

3839
def make_device(self, mac_address):
39-
device = gatt.Device(
40-
mac_address=mac_address, manager=self, managed=False)
41-
if device.alias() != 'Tap Timer':
40+
device = gatt.Device(mac_address=mac_address, manager=self, managed=False)
41+
if device.alias() != "Tap Timer":
4242
return None
4343
return TapTimer(mac_address=mac_address, manager=self)
4444

@@ -51,7 +51,7 @@ def device_discovered(self, device):
5151
self.listener.tap_timer_discovered(device)
5252

5353

54-
class TapTimerManagerListener(object):
54+
class TapTimerManagerListener:
5555
"""
5656
Base class for receiving discovery events from ``TapTimerManager``.
5757
@@ -87,14 +87,12 @@ class TapTimer(gatt.Device):
8787
notified with all events
8888
"""
8989

90-
HOLMAN_CO3015_SERVICE_UUID = '0a75f000-f9ad-467a-e564-3c19163ad543'
91-
HOLMAN_CO3011_SERVICE_UUID = 'c521f000-0d70-4d4f-8e43-40d84c50ab38' # model BTX1
92-
STATE_CHARACTERISTIC_UUID = '0000f004-0000-1000-8000-00805f9b34fb'
93-
MANUAL_CHARACTERISTIC_UUID = '0000f006-0000-1000-8000-00805f9b34fb'
90+
HOLMAN_CO3015_SERVICE_UUID = "0a75f000-f9ad-467a-e564-3c19163ad543"
91+
HOLMAN_CO3011_SERVICE_UUID = "c521f000-0d70-4d4f-8e43-40d84c50ab38" # model BTX1
92+
STATE_CHARACTERISTIC_UUID = "0000f004-0000-1000-8000-00805f9b34fb"
93+
MANUAL_CHARACTERISTIC_UUID = "0000f006-0000-1000-8000-00805f9b34fb"
9494

95-
SERVICE_UUIDS = [
96-
HOLMAN_CO3015_SERVICE_UUID,
97-
HOLMAN_CO3011_SERVICE_UUID]
95+
SERVICE_UUIDS = [HOLMAN_CO3015_SERVICE_UUID, HOLMAN_CO3011_SERVICE_UUID]
9896

9997
def __init__(self, mac_address, manager):
10098
"""
@@ -150,36 +148,56 @@ def disconnect_succeeded(self):
150148
def services_resolved(self):
151149
super().services_resolved()
152150

153-
holman_service = next((
154-
service for service in self.services
155-
if service.uuid in self.SERVICE_UUIDS), None)
151+
holman_service = next(
152+
(
153+
service
154+
for service in self.services
155+
if service.uuid in self.SERVICE_UUIDS
156+
),
157+
None,
158+
)
156159
if holman_service is None:
157160
if self.listener:
158161
# TODO: Use proper exception subclass
159-
self.listener.connect_failed(
160-
Exception("Holman GATT service missing"))
162+
self.listener.connect_failed(Exception("Holman GATT service missing"))
161163
return
162164

163-
self._manual_characteristic = next((
164-
char for char in holman_service.characteristics
165-
if char.uuid == self.MANUAL_CHARACTERISTIC_UUID), None)
165+
self._manual_characteristic = next(
166+
(
167+
char
168+
for char in holman_service.characteristics
169+
if char.uuid == self.MANUAL_CHARACTERISTIC_UUID
170+
),
171+
None,
172+
)
166173
if self._manual_characteristic is None:
167-
# TODO: Use proper exception subclass
168-
self.listener.connect_failed(
169-
Exception(
170-
"Holman GATT characteristic %s missing",
171-
self.MANUAL_CHARACTERISTIC_UUID))
174+
if self.listener:
175+
# TODO: Use proper exception subclass
176+
self.listener.connect_failed(
177+
Exception(
178+
f"Holman GATT characteristic "
179+
f"{self.MANUAL_CHARACTERISTIC_UUID} missing"
180+
)
181+
)
172182
return
173183

174-
self._state_characteristic = next((
175-
char for char in holman_service.characteristics
176-
if char.uuid == self.STATE_CHARACTERISTIC_UUID), None)
184+
self._state_characteristic = next(
185+
(
186+
char
187+
for char in holman_service.characteristics
188+
if char.uuid == self.STATE_CHARACTERISTIC_UUID
189+
),
190+
None,
191+
)
177192
if self._state_characteristic is None:
178-
# TODO: Use proper exception subclass
179-
self.listener.connect_failed(
180-
Exception(
181-
"Holman GATT characteristic %s missing",
182-
self.STATE_CHARACTERISTIC_UUID))
193+
if self.listener:
194+
# TODO: Use proper exception subclass
195+
self.listener.connect_failed(
196+
Exception(
197+
f"Holman GATT characteristic "
198+
f"{self.STATE_CHARACTERISTIC_UUID} missing"
199+
)
200+
)
183201
return
184202
self._refresh_state()
185203

@@ -236,6 +254,7 @@ class TapTimerListener:
236254
Base class of listeners for a ``TapTimer`` with empty handler
237255
implementations.
238256
"""
257+
239258
def started_connecting(self):
240259
pass
241260

0 commit comments

Comments
 (0)