build: lock pyright alongside mypy; camas 0.1.18 -> 0.1.29

[JPHutchins]

Warning

LLM Disclosure

This PR was authored by claude-opus-5[1m] on behalf of @JPHutchins, who asked to begin the smpclient phase of the screaming-goblin breaking effort (intercreate/smpmgr#103) — audit the outstanding issues, and as a nice-to-have "lock pyright type checking if we don't have it already". This is the non-breaking infrastructure step, landed on main first so the smp port is gated by both type checkers from its first line rather than retrofitted afterward.

What

Adds pyright as a second, gating type checker (typecheck = Parallel(mypy, pyright)) and bumps camas[mcp] 0.1.18 → 0.1.29.

Mirrors the configuration smp adopted in JPHutchins/smp#67, so the editor (Pylance) and the camas CLI share one [tool.pyright] — standard mode over src, tests, examples.

Everything below was found by pyright on code mypy already passed. No behavior changes.

Why now

The screaming-goblin port to smp's Frame[T]/msgspec API rewrites the request path wholesale. Having both checkers gating before that starts is much cheaper than retrofitting one after — and this half is non-breaking, so per the epic's own branch rule it belongs on main.

The findings

1. @override must be applied inside @property (7 sites, 5 transports)

Every transport property was decorated:

@override
@property
def mtu(self) -> int: ...

which applies override to the property object rather than to the function. mypy accepts it; pyright reports reportArgumentType. Verified empirically that @property outermost is accepted by both checkers and correct at runtime, then swapped all 7.

2. Explicit ... bodies on Protocol stubs (10 sites, 2 files)

SMPTransport and SerialFraming methods had docstring-only bodies. Where the declared return type is not None-compatible, pyright reports reportReturnType — "must return value on all code paths".

Added the explicit ... body already used by smpclient.generics, applied uniformly rather than only where the return type happened to trip the check.

3. bytes/bytearray boundaries are now honest (4 sites)

mypy implicitly promotes bytearray/memoryview → bytes; pyright does not, and the typing spec has deprecated the promotion.

Setting disableBytesTypePromotions = false to paper over the difference was tried and rejected: it makes case bytes() look exhaustive when at runtime it does not match a bytearray, and it duly broke the assert_never in SMPBumbleTransport._next_chunk. That is the promotion being unsound, so it stays off and the four boundaries are stated accurately instead:

Site	Change
SMPBLETransport._notify_callback	takes bytearray — that is what bleak passes it
SMPBLETransport.receive	Header.loads(bytes(...)) — an 8-byte copy of the sliced receive buffer
SMPBumbleTransport.receive	same
SMPUDPTransport.receive	returns bytes(message) instead of returning its bytearray accumulator from a -> bytes signature

4. bleak 3 specifics (4 sites)

• BleakGATTCharacteristic is no longer re-exported from the bleak top level (reportPrivateImportUsage) — imported from bleak.backends.characteristic, in the transport and in its test.

• The backend predicates were typed too narrowly. _bluez_backend/_winrt_backend took BaseBleakClient, but off-platform one of BleakClientBlueZDBus/BleakClientWinRT is a local Protocol stub. The and-guarded branch leaves pyright holding BaseBleakClient | BleakClientWinRT — correctly, since a false if can mean "was WinRT, but MTU != 20":

  if (
      self._winrt_backend(self._client._backend)
      and self._max_write_without_response_size == 20
  ):
      ...
  elif self._bluez_backend(self._client._backend):  # <-- union arrives here

  Both predicates only read __class__.__name__, so they now take a _ClientBackend alias covering the real backend plus both stubs.

• The Windows MTU workaround is legitimate; only its declared type disagrees. It assigns an int to BleakGATTCharacteristic._max_write_without_response_size, which bleak declares Callable[[], int]. bleak's own getter explicitly supports this:

  # for backwards compatibility
  if isinstance(self._max_write_without_response_size, int):
      return self._max_write_without_response_size
  
  return self._max_write_without_response_size()

  — bleak/backends/characteristic.py

  Behavior unchanged; the type error is suppressed at that one line.

Verification

camas matrix green across Python 3.10–3.14 — 5/5, each running ruff check, pydoclint, mypy, pyright, and the full non-integration test suite.

✓ uv run --python 3.10 camas check      ✓ uv run --python 3.13 camas check
✓ uv run --python 3.11 camas check      ✓ uv run --python 3.14 camas check
✓ uv run --python 3.12 camas check

Known residuals (deliberate, not oversights)

• pyright warnings do not gate. generics.py emits 8 reportInvalidTypeVarUse warnings (Protocol TypeVars that should be covariant). That file is reshaped by the smp port — smp's SMPRequest already has the correct covariance — so they are left for the port rather than fixed and discarded. Turning on --warnings is the natural lock-tightening follow-up once the port lands.
• CI has no format_check leaf. github_task=check never verifies formatting (ruff check catches import order via I, not formatting); only the mutating all task formats. smp's check includes format_check. Out of scope here — worth a follow-up.

Issues

Part of the epic intercreate/smpmgr#103. Prerequisite infrastructure for the smpclient screaming-goblin port (which will close #124).

🤖 Generated with Claude Code

[JPHutchins]

LGTM