|
| 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 | + |
0 commit comments