# Notes for LLM contributors

A short orientation file for an LLM working in this repo. Skim before making
changes and keep edits consistent with what's described here. Read
[README.md](README.md) for the user-facing intro.

## What this project is

`pySwitchbot` is a pure-Python library for controlling SwitchBot IoT devices
over **Bluetooth LE** (with some SwitchBot cloud HTTP calls). It backs the
SwitchBot integration in [Home Assistant](https://www.home-assistant.io/).

Built on [`bleak`](https://github.com/hbldh/bleak) +
[`bleak-retry-connector`](https://github.com/Bluetooth-Devices/bleak-retry-connector)
for the BLE transport, `aiohttp` for the cloud API, and
`cryptography`/`pyOpenSSL` for encrypted devices (locks, etc.). It ships its
own advertisement parsing — it does not depend on the `bluetooth-devices`
adv-parser stack.

## Disclosing autonomous contributions

This repo receives a high volume of autonomous, agent-generated pull requests.
When an account is AI-driven, maintainers can only review and have a real
technical discussion if they know **who is responsible** for it.

- If a PR is produced by an autonomous agent, **name the human or team
  responsible** in the PR description (and ideally on the account profile).
- Undisclosed drive-by PRs with no human owner are routinely closed — a single
  line of attribution is what makes the change reviewable.

## Code style

- **Docstrings: terse, default to single-line.** A docstring is the function's
  contract, not a narrative. Almost every docstring should be one line —
  `"""Summary."""`. Multi-line is the exception, only when there's non-obvious
  caller-visible behaviour the signature and parameter names don't convey.
  Note `D1xx` (missing-docstring) rules are ignored — don't add docstrings
  just to satisfy a linter; add them when they carry contract.

- **Comments: same bar — default to none.** Add one only when the _why_ is
  non-obvious: a hidden constraint, a subtle invariant, a workaround for a
  specific device quirk or bug. If removing the comment wouldn't confuse a
  future reader, don't write it. **Don't remove existing comments** unless the
  code they describe is gone.

- **Keep it out of docstrings/comments:** rationale/motivation, issue numbers
  ("closes #N"), and prose that just restates the code. Those belong in the PR
  body and commit message — git already remembers.

- **Python 3.11+.** `python_requires=">=3.11"`, ruff `target-version = "py311"`,
  pyupgrade `--py311-plus`. Don't introduce 3.12+-only syntax.

- **Line length 88**, ruff-enforced (`E501` itself is ignored, but ruff-format
  reflows to 88). Imports sorted by ruff/isort,
  `known-first-party = ["pySwitchbot", "tests"]`.

## Where things live

| Path                      | What                                                                                                                                      |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `switchbot/__init__.py`   | Public API surface — re-exports device classes, enums, `GetSwitchbotDevices`, `parse_advertisement_data`                                  |
| `switchbot/adv_parser.py` | Central BLE advertisement dispatcher — maps service/model bytes to a device type + parser. Touch this to detect a new device              |
| `switchbot/adv_parsers/`  | One pure-function parser per device family (`bot.py`, `curtain.py`, `lock.py`, `meter.py`, `hub2.py`, …)                                  |
| `switchbot/devices/`      | One module per device class (what callers instantiate); `device.py` holds the `SwitchbotDevice` / `SwitchbotEncryptedDevice` base classes |
| `switchbot/const/`        | Enums and constants by domain; `SwitchbotModel` and the exception classes                                                                 |
| `switchbot/models.py`     | `SwitchBotAdvertisement` dataclass                                                                                                        |
| `switchbot/discovery.py`  | `GetSwitchbotDevices` — BLE scan + per-type getters                                                                                       |
| `tests/`                  | Pytest suite                                                                                                                              |

Adding a device usually touches: a parser in `adv_parsers/`, a dispatch entry
in `adv_parser.py`, a class in `devices/`, model/const in `const/`, and an
export in `__init__.py`.

## Running tests

No Poetry/uv — plain pip + setuptools.

```bash
pip install -r requirements_dev.txt .
pytest --cov=switchbot tests
```

CI (`.github/workflows/ci.yaml`) runs the suite on Python 3.11–3.14 plus the
pre-commit hooks, and uploads coverage to Codecov.

## Commit / PR conventions

- **Conventional Commits**, enforced by the `commitizen` commit-msg pre-commit
  hook (default ruleset). Types: `build`, `chore`, `ci`, `docs`, `feat`,
  `fix`, `perf`, `refactor`, `revert`, `style`, `test`. Examples:
  - `feat: add support for the SwitchBot Hub 3`
  - `fix(lock): handle empty advertisement payload`
- **Use a feature branch.** PRs opened from a fork's default branch are
  auto-closed by `auto-close-default-branch-prs.yml`.
- **Pre-commit auto-fixes; re-stage.** `ruff --fix`, `ruff-format`,
  `pyupgrade`, `codespell`, prettier, and the standard pre-commit-hooks run on
  commit and rewrite files in place; when a hook edits a file the commit
  aborts — re-stage and commit again. (pre-commit.ci also autofixes on PRs.)
- **No PR template / no CONTRIBUTING.md** — the body is freeform; describe what
  the change does and why, and link the issue if one exists.
- **Releases are manual:** cutting a GitHub Release triggers
  `python-publish.yml` to build and publish to PyPI. There is no
  semantic-release; nothing auto-bumps from commit types.

## Reporting security issues

Report suspected vulnerabilities privately to the maintainers — not in a public
issue, PR, or commit that names the bug class and affected code path.