---
name: dependency-pins
description: Use when bumping any dependency, upgrading the HA test harness (pytest-homeassistant-custom-component) or HA floor, or handling Dependabot PRs/security alerts — per-package pin rationale for pytest, mypy, dbus-fast, Pillow, respx, and serialx, all of which are constrained by Home Assistant or the test harness.
---

# HA-constrained dependency pins

- **`pytest` is pinned by `pytest-homeassistant-custom-component`** (currently `pytest==9.0.3`). Dependabot is configured to ignore standalone `pytest` bumps (see `.github/dependabot.yml`). When upgrading the HA test harness (`pytest-homeassistant-custom-component`), check whether the new version pins a different `pytest` and bump `pytest` in `pyproject.toml` to match. If upstream ever loosens the pin, remove the `pytest` ignore rule from `dependabot.yml`.
- **`mypy` is no longer capped** — the harness's `ast-serialize==0.3.0` hard pin (which blocked mypy 2.2+) was dropped in 0.13.348, so mypy resolves freely and Dependabot manages it again (the `mypy` ignore rule was removed from `dependabot.yml`). If a future harness release re-pins `ast-serialize`, re-add the ignore rule and cap mypy to the last version that resolves.
- **`dbus-fast` and `Pillow` are provided by HA core and deliberately absent from `manifest.json`** (HACS default-store review nit: a custom-integration pin fights core's own constraints on upgrade). At HA runtime, Pillow arrives transitively via `python-escpos` under HA's constraint file, and `bluez.py` gracefully degrades when `dbus-fast` is absent. Both stay pinned in `pyproject.toml` for dev/CI only — match HA core's pins when upgrading the test harness. The exclusion is enforced by `MANIFEST_EXCLUDES` in `scripts/sync_manifest_requirements.py` and `HA_PROVIDED` in `scripts/check_requirements_sync.py` (keep the two sets mirrored). Dependabot is configured to ignore standalone `pillow` and `dbus-fast` bumps (see `.github/dependabot.yml`).
- **`respx` is pinned by `pytest-homeassistant-custom-component`** (currently `respx==0.23.1`). Dependabot is configured to ignore standalone `respx` bumps (see `.github/dependabot.yml`). When upgrading the HA test harness, check whether the new version pins a different `respx` and bump it in `pyproject.toml` to match.
- **`serialx` is pinned by HA core** (`package_constraints.txt`): `==1.7.0` (HA 2026.5.0), `==1.7.3` (HA 2026.5.4), `==1.8.0` (HA 2026.6.0), `==1.8.2` (HA 2026.7.4 – 2026.8.1), `==1.10.0` (HA 2026.9.3; 1.9–1.10 changed only kwarg pass-through and Win32 error types). HA installs manifest requirements with `-c package_constraints.txt`, so an exact pin in `manifest.json` is unsatisfiable on any HA version that carries a different pin. `manifest.json` carries `>=1.7.0,<2`; this is safe because the 1.7→1.8 change only touched the async write API and this integration uses the sync API throughout. `pyproject.toml` pins `==1.10.0` to match the HA version used by the CI test harness (`pytest-homeassistant-custom-component==0.13.366` → HA 2026.9.3). Dependabot is configured to ignore standalone `serialx` bumps (see `.github/dependabot.yml`). When upgrading the HA test harness, check `package_constraints.txt` for the new HA version and bump the dev pin in `pyproject.toml` to match.
- **After HA version bumps, re-check Dependabot security alerts** (`https://github.com/cognitivegears/ha-escpos-thermal-printer/security/dependabot`). Most open alerts are against the HA-pinned packages above — direct (`pyproject.toml` Pillow) or `uv.lock` transitives (aiohttp, pyOpenSSL, PyJWT, orjson, requests, uv, cryptography, etc.). They only affect dev/CI environments — end users install via `manifest.json` — and auto-clear when HA releases a version with patched pins. After a HA bump (i.e. once `pytest-homeassistant-custom-component` points to the new HA), run `uv lock --upgrade` and verify which alerts close.
- **The `ignore:` block in `dependabot.yml` only suppresses *version* updates** — it does not suppress *security* updates (which trigger the Dependabot Updates worker independently and will fail noisily when the bump conflicts with an HA pin). For HA-pinned packages, dismiss the security alert as `tolerable_risk` with a note pointing at the HA pin; the alert will re-surface if a new advisory lands against the still-current pinned version.