python-rako-2025 0.4.4__tar.gz → 0.5.0__tar.gz

{python_rako_2025-0.4.4 → python_rako_2025-0.5.0}/.coveragerc

@@ -1,8 +1,10 @@
 [run]
 source = python_rako
+# Keep this in step with [tool.coverage.run] in pyproject.toml -- this file
+# takes precedence over it. __init__.py and bridge.py used to be omitted here,
+# which silently excluded the bridge API from the coverage gate.
 omit =
-    python_rako/__init__.py
-    python_rako/bridge.py
+    python_rako/__version__.py
 
 
 [report]

python_rako_2025-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+---
+name: Continuous Integration
+
+on: [push, pull_request]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  linting:
+    name: Linting
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out code from GitHub
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Create virtual environment
+        run: uv venv .venv --python 3.13
+      - name: Install dependencies
+        run: uv pip install --python .venv/bin/python -e '.[dev]'
+      - name: Run pre-commit on all files
+        run: .venv/bin/pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu]
+        python: ["3.12", "3.13"]
+    steps:
+      - name: Checking out code from GitHub
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Create virtual environment
+        run: uv venv .venv --python ${{ matrix.python }}
+      - name: Install dependencies
+        run: uv pip install --python .venv/bin/python -e '.[test]'
+      - name: Run tests with coverage
+        run: .venv/bin/python -m pytest
+      - name: Upload coverage to Codecov
+        if: matrix.python == '3.12' && matrix.os == 'ubuntu'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+
+  packaging:
+    name: Build & verify distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out code from GitHub
+        uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Create virtual environment
+        run: uv venv .venv --python 3.13
+      - name: Install build tooling
+        run: uv pip install --python .venv/bin/python build twine
+      - name: Build sdist and wheel
+        run: .venv/bin/python -m build
+      - name: Check distribution metadata (twine)
+        run: .venv/bin/python -m twine check dist/*

python_rako_2025-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+---
+name: Release
+
+# Two ways to run this workflow:
+#
+#  - "release: published"  -> real release. Builds, verifies the tag matches
+#    python_rako/__version__.py, and publishes to the real PyPI (environment: pypi).
+#
+#  - "workflow_dispatch"   -> dry run. Builds and publishes to TestPyPI
+#    (environment: testpypi) instead. Safe to run at any time; never touches
+#    the real PyPI. Use this to sanity-check the pipeline before cutting a
+#    real release.
+#
+# See RELEASING.md for the full maintainer walkthrough and the one-time
+# Trusted Publisher setup this workflow depends on.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build & verify distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checking out code from GitHub
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Create virtual environment
+        run: uv venv .venv --python 3.13
+
+      - name: Verify the release tag matches python_rako/__version__.py
+        if: github.event_name == 'release'
+        run: |
+          .venv/bin/python scripts/bump_version.py check "${{ github.event.release.tag_name }}"
+
+      - name: Install build tooling
+        run: uv pip install --python .venv/bin/python build twine
+
+      - name: Build sdist and wheel
+        run: .venv/bin/python -m build
+
+      - name: Check distribution metadata (twine)
+        run: .venv/bin/python -m twine check dist/*
+
+      - name: Smoke-test the built wheel in a clean venv
+        run: |
+          uv venv /tmp/smoke-venv --python 3.13
+          uv pip install --python /tmp/smoke-venv/bin/python dist/*.whl
+          /tmp/smoke-venv/bin/python -c "import python_rako; print('python_rako', python_rako.__version__)"
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI (dry run)
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/python-rako-2025
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing
+      attestations: write  # required for build provenance attestations
+      contents: read
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          attestations: true
+          skip-existing: true  # dry runs of an unchanged version must not fail
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/python-rako-2025
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing
+      attestations: write  # required for build provenance attestations
+      contents: read
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

{python_rako_2025-0.4.4 → python_rako_2025-0.5.0}/.gitignore

@@ -88,7 +88,6 @@ venv
 .venv
 Pipfile*
 share/*
-/Scripts/
 
 # vimmy stuff
 *.swp

{python_rako_2025-0.4.4 → python_rako_2025-0.5.0}/.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 ---
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.15
+    rev: v0.16.4
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix]
       - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -16,20 +16,20 @@ repos:
       - id: check-docstring-first
       - id: check-json
       - id: check-yaml
-      - id: check-byte-order-marker
+      - id: fix-byte-order-marker
       - id: check-case-conflict
       - id: check-executables-have-shebangs
       - id: check-ast
       - id: detect-private-key
       - id: forbid-new-submodules
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v2.3.1
     hooks:
       - id: mypy
         files: ^python_rako/.+\.py$
         exclude: ^python_rako/__version__\.py$
         additional_dependencies: [types-requests]
   - repo: https://github.com/adrienverge/yamllint.git
-    rev: v1.37.1
+    rev: v1.38.0
     hooks:
       - id: yamllint

python_rako_2025-0.5.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.5.0] - 2026-08-30
+
+### Added
+
+- Full UDP status decoder (`python_rako.protocol`): every documented instruction
+  (OFF, FADE_UP/DOWN, SC1–SC4, IDENT, LEVEL_SET, STORE, STOP, CUSTOM_232,
+  HOLIDAY, SET_SCENE, FADE, SET_LEVEL), the empirically observed undocumented
+  0x33 level-toggle, and a typed `UnknownStatusMessage` for anything else —
+  nothing is silently dropped any more. Messages carry a `MessageOrigin`
+  (sensor vs control, derived from flags bit 3) and 10-bit room ids.
+- `StatusListener`: supervised broadcast listener with automatic restart and
+  backoff, health reporting, a 300 ms duplicate window (the bridge re-sends
+  some keypad events ~200 ms apart), and subscriber fan-out.
+- Echo-verified commands: `Bridge.send_command`, `set_room_scene`,
+  `set_room_level`, `set_channel_level`, `fade_up`, `fade_down`, `stop_fade`
+  wait for the bridge's own status broadcast to confirm the command took
+  effect (typically 150–300 ms), retry once on silence, then raise
+  `RakoCommandError`. The echoed message is returned so callers update state
+  from what the bridge actually did.
+- `BridgeStateSnapshot`: room/channel state with per-channel provenance
+  (`StateSource`) and a `reconcile()` rule that never overwrites a fresher
+  level broadcast with a stale scene-derived level, nor resurrects a scene for
+  a room whose last event was a fade.
+- `Bridge.get_scene_cache_http()` reads the scene cache over HTTP
+  (`scenes.htm`) so polling never contends with the UDP listener socket.
+- **Command pacing** (`python_rako.pacing.CommandQueue`): every command now goes
+  through a per-bridge FIFO queue that sends no faster than
+  `min_command_interval` (default `DEFAULT_MIN_COMMAND_INTERVAL` = 1.25 s —
+  measured on a live bridge: 1.0 s spacing was loss-free, 0.75 s silently
+  dropped a command; default = fastest clean interval x 1.25 margin) and never
+  overlaps a command still waiting
+  for its echo. Requests that arrive too fast are queued, never dropped — the
+  bridge silently ignores commands sent too close together. Commands for the
+  same `(room, channel)` coalesce: a newer one replaces a waiting one in place,
+  keeping its queue position, so a slider drag becomes a single send and the
+  superseded callers get the echo of the command that actually ran. Diagnostics
+  via `bridge.command_queue.stats` (depth, oldest age, sent/coalesced/failed),
+  `drain()` for orderly shutdown, `paced=False` on `send_command`/`set_*` as a
+  direct escape hatch, and a runtime-settable `bridge.min_command_interval`.
+  A fade and its stop are treated as one gesture: the stop for the target of
+  the fade just sent skips the queue and the interval (so a short tap stays
+  short), neither half can coalesce the other away, and pacing resumes from the
+  stop. New exception `RakoQueueClosedError` (a `RakoCommandError`) for
+  commands a closed queue will never send.
+- `scripts/measure_interval.py`: live tool that finds the bridge's real minimum
+  safe interval by sending echo-verified off/on pairs at decreasing intervals,
+  and recommends a `min_interval` from the result.
+- `Bridge` is now an async context manager; `Bridge.close()` releases sockets.
+- `discover_bridge(timeout=5.0)`; new exceptions `RakoDiscoveryError`,
+  `RakoUnsupportedCommandError`, `RakoProtocolError`.
+- `tests_integration/` rewritten on the new state/listener/echo-verify API,
+  gated behind `RAKO_LIVE=1` (mutating tests additionally behind
+  `RAKO_LIVE_MUTATE=1` and an operator-chosen `RAKO_TEST_ROOM`/
+  `RAKO_TEST_CHANNEL`) and the `live` pytest marker, so a plain `pytest` run
+  never collects them; `tests/test_state.py` gained a full-pipeline regression
+  test replaying every Phase-0 capture through `decode_packet` and
+  `BridgeStateSnapshot.apply`. New characterisation tools under `scripts/`
+  (`listen.py`, `snapshot.py`, `latency.py`) mirror the Phase 0 tooling
+  against the new API for exploring a live bridge by hand.
+
+### Changed
+
+- **Behaviour change:** `set_*` methods no longer report success on a UDP
+  timeout. With a listener attached they raise `RakoCommandError` when the
+  bridge does not confirm; without one they return `None` and warn.
+  `BridgeCommanderUDP`/`BridgeCommanderHTTP` are deprecated delegates.
+- `rako.xml` parsing runs off the event loop (`asyncio.to_thread`); the
+  unnecessary parse lock was removed.
+- Scene-cache parsing now handles extended (10-bit) room ids correctly.
+- Tooling refresh: ruff/mypy/pre-commit pins updated, Python 3.12/3.13 CI matrix.
+
+### Removed
+
+- Dead code: `UDPMessageRateLimit`, `get_predicted_channel_brightness`.
+
+### Fixed
+
+- Release pipeline: the release workflow no longer overwrites
+  `python_rako/__version__.py` with the raw git tag (which produced an
+  invalid Python file). It now verifies the release tag matches
+  `__version__.py` and fails loudly on mismatch instead of publishing a
+  broken build.
+- Release workflow now publishes to PyPI using **Trusted Publishing**
+  (OIDC) instead of long-lived API tokens, with build attestations, a
+  pre-publish smoke test (build the wheel, install it into a clean venv,
+  import it), and a `workflow_dispatch`-triggered TestPyPI dry run.
+- CI now also builds the sdist/wheel and runs `twine check` on every pull
+  request, so packaging breakage is caught before release day, not during
+  it.
+
+<!--
+When cutting a release, move the entries above into a new section here,
+e.g.:
+
+## [0.5.0] - 2026-09-01
+
+### Fixed
+
+- ...
+-->
+
+[Unreleased]: https://github.com/SimonLeigh/python-rako/compare/v0.5.0...master
+[0.5.0]: https://github.com/SimonLeigh/python-rako/releases/tag/v0.5.0
+
+<!--
+Note for the first tagged release under this process: no git tags exist in
+this repository yet (0.4.1 was released without ever tagging the commit).
+Once v0.5.0 (or whichever version comes first) is tagged, switch the link
+above to a compare link, e.g.:
+  [Unreleased]: https://github.com/SimonLeigh/python-rako/compare/v0.5.0...HEAD
+  [0.5.0]: https://github.com/SimonLeigh/python-rako/releases/tag/v0.5.0
+-->

{python_rako_2025-0.4.4 → python_rako_2025-0.5.0}/Makefile

@@ -107,18 +107,18 @@ install-dev: clean
 
 .PHONY: bump-patch
 bump-patch: ## Bump patch version (x.y.Z) and commit
-	@python -c "import re; content = open('python_rako/__version__.py').read().strip(); match = re.search(r'(\d+)\.(\d+)\.(\d+)', content); major, minor, patch = match.groups(); new_version = f'{major}.{minor}.{int(patch) + 1}'; open('python_rako/__version__.py', 'w').write(f'__version__ = \"{new_version}\"\n'); print(f'Bumped version to {new_version}')"
-	@git add python_rako/__version__.py
-	@git commit -m "Bump version to $$(python -c "import re; content = open('python_rako/__version__.py').read(); match = re.search(r'\"([^\"]+)\"', content); print(match.group(1))")"
+	python scripts/bump_version.py bump patch
+	git add python_rako/__version__.py
+	git commit -m "Bump version to $$(python scripts/bump_version.py current)"
 
 .PHONY: bump-minor
 bump-minor: ## Bump minor version (x.Y.z) and commit
-	@python -c "import re; content = open('python_rako/__version__.py').read().strip(); match = re.search(r'(\d+)\.(\d+)\.(\d+)', content); major, minor, patch = match.groups(); new_version = f'{major}.{int(minor) + 1}.0'; open('python_rako/__version__.py', 'w').write(f'__version__ = \"{new_version}\"\n'); print(f'Bumped version to {new_version}')"
-	@git add python_rako/__version__.py
-	@git commit -m "Bump version to $$(python -c "import re; content = open('python_rako/__version__.py').read(); match = re.search(r'\"([^\"]+)\"', content); print(match.group(1))")"
+	python scripts/bump_version.py bump minor
+	git add python_rako/__version__.py
+	git commit -m "Bump version to $$(python scripts/bump_version.py current)"
 
 .PHONY: bump-major
 bump-major: ## Bump major version (X.y.z) and commit
-	@python -c "import re; content = open('python_rako/__version__.py').read().strip(); match = re.search(r'(\d+)\.(\d+)\.(\d+)', content); major, minor, patch = match.groups(); new_version = f'{int(major) + 1}.0.0'; open('python_rako/__version__.py', 'w').write(f'__version__ = \"{new_version}\"\n'); print(f'Bumped version to {new_version}')"
-	@git add python_rako/__version__.py
-	@git commit -m "Bump version to $$(python -c "import re; content = open('python_rako/__version__.py').read(); match = re.search(r'\"([^\"]+)\"', content); print(match.group(1))")"
+	python scripts/bump_version.py bump major
+	git add python_rako/__version__.py
+	git commit -m "Bump version to $$(python scripts/bump_version.py current)"