aiopyronix 0.1.0__tar.gz

aiopyronix-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+coverage.xml
+htmlcov/
+*.log
+.env*
+dist/
+build/

aiopyronix-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+This project follows [Semantic Versioning](https://semver.org/). Until 1.0, a
+minor version may change the public API.
+
+## 0.1.0
+
+First release. The PyronixCloud client and panel protocol move out of the
+[Pyronix HomeControl integration](https://github.com/Herbertmt978/HA-Pyronix)
+0.3.0 unchanged, with a public API, type information and full branch test
+coverage.

aiopyronix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herbertmt978
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiopyronix-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: aiopyronix
+Version: 0.1.0
+Summary: Asynchronous PyronixCloud client for Pyronix alarm panels, with explicit sessions
+Project-URL: Source, https://github.com/Herbertmt978/aiopyronix
+Project-URL: Issues, https://github.com/Herbertmt978/aiopyronix/issues
+Project-URL: Changelog, https://github.com/Herbertmt978/aiopyronix/blob/main/CHANGELOG.md
+Author: Herbertmt978
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alarm,asyncio,home-assistant,homecontrol,pyronix
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.13.0
+Requires-Dist: cryptography>=47.0.0
+Description-Content-Type: text/markdown
+
+# aiopyronix
+
+[![PyPI](https://img.shields.io/pypi/v/aiopyronix)](https://pypi.org/project/aiopyronix/)
+[![CI](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml)
+[![Licence: MIT](https://img.shields.io/badge/Licence-MIT-0F766E.svg)](https://github.com/Herbertmt978/aiopyronix/blob/main/LICENSE)
+
+An asynchronous Python client for Pyronix alarm panels reached through
+PyronixCloud, the service used by the HomeControl 2.0 app.
+
+It powers the [Pyronix HomeControl integration for Home Assistant](https://github.com/Herbertmt978/HA-Pyronix),
+and it can be used on its own. This is independent community software. It is
+not an official Pyronix, Hikvision or Home Assistant product.
+
+## Design
+
+The client controls an intruder alarm, so caution takes priority over convenience:
+
+- **Explicit sessions.** Nothing connects when a `PanelClient` is created. A
+  session opens only when `connect()` is called. There is no polling or
+  automatic reconnection.
+- **Idle sessions close.** A session closes after five minutes without a
+  `connect()` or `control()` call. Heartbeats keep the socket alive, but they
+  do not extend that limit.
+- **Commands are sent once.** `control()` arms or disarms exactly one area and
+  waits for the panel to confirm it. When the outcome cannot be confirmed, it
+  raises `CommandUnconfirmedError`. The command is never repeated, even after
+  a lost connection.
+- **A narrow command set.** Only single-area arm and disarm are possible. The
+  library has no forced omissions, outputs, installer functions or cloud
+  account changes.
+- **Nothing sensitive is logged.** The library does not log. Its error
+  messages are fixed text and never contain credentials, panel data or wire
+  payloads.
+
+Status updates and commands share one WebSocket. Each frame is encrypted with
+a session key agreed through ECDH (P-256) and checked for integrity and
+sequence.
+
+## Installation
+
+```bash
+pip install aiopyronix
+```
+
+Python 3.14 or later is required.
+
+## Connection details
+
+`PanelClient` needs the connection details that the HomeControl 2.0 app saves
+when you sign in:
+
+| Field | Meaning |
+| --- | --- |
+| `AppUser`, `PushId`, `DeviceId` | The app installation registered with PyronixCloud |
+| `PanelId` | The eight-character panel identifier |
+| `SystemName` | The panel name shown in the app |
+| `PanelPwd` | The app password stored for the panel |
+| `UserCode` | The panel user code, four to eight digits |
+
+`AppVersion`, `AppType`, `OSName`, `OSVersion`, `NetworkType` and `AppLang`
+are optional. Other keys are discarded. The Home Assistant integration
+includes a [setup helper](https://github.com/Herbertmt978/HA-Pyronix#connect-your-own-alarm)
+that reads these details from your own signed-in app.
+
+## Usage
+
+```python
+import asyncio
+import json
+from pathlib import Path
+
+import aiohttp
+
+from aiopyronix import CommandUnconfirmedError, PanelClient
+
+
+async def main() -> None:
+    auth = json.loads(Path("pyronix.json").read_text())
+    async with aiohttp.ClientSession() as http:
+        client = PanelClient(http, auth)
+        try:
+            snapshot = await client.connect()
+            for index, area in snapshot["areas"].items():
+                print(index, area["name"], area["status"])
+
+            if 0 in snapshot["can_arm"]:
+                try:
+                    await client.control("arm", 0)
+                except CommandUnconfirmedError:
+                    print("Check the panel before trying again")
+        finally:
+            await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+`connect()` returns once every area the user may control has reported its
+state. Calling it on an open session returns the current state and restarts
+the idle timer.
+
+### Callbacks
+
+- `on_update(snapshot)` runs whenever the panel reports new state.
+- `on_state()` runs when `state`, `detail` or `idle_expires_at` changes.
+- `create_task(coroutine)` starts the session's background reader. It defaults
+  to `asyncio.create_task`. Home Assistant passes
+  `entry.async_create_background_task`.
+
+### State
+
+- `snapshot()` returns an independent copy of the latest `Snapshot`: the
+  `areas`, the `can_arm` and `can_disarm` area sets, `permissions_received`,
+  `observed_at` and, when reported, `firmware`.
+- `state` is `disconnected`, `connecting`, `connected` or `error`. After an
+  error, `detail` holds a fixed explanation.
+- `idle_expires_at` is the wall-clock time at which an idle session will close.
+
+Area `value` codes are listed in `STATUS`: `0` Unset, `1` Set, `2` Alarmed,
+`3` Setting, `4` Cannot Set, `5` Can Override and `6` Set Cancelled. An arm
+request counts as confirmed once the area reports Setting. Arming is refused
+while an area reports Cannot Set or Can Override.
+
+### Errors
+
+All errors derive from `ProtocolError`:
+
+| Exception | Meaning |
+| --- | --- |
+| `AuthenticationError` | The cloud or panel rejected the credentials. Ask for new details; do not retry automatically. |
+| `PanelBusyError` | Another command on this client is still waiting for its result. |
+| `CommandUnconfirmedError` | The command may have reached the panel, but its outcome is unknown. `snapshot` holds the latest state, if the session is still open. |
+| `ProtocolError` | Any other connection, validation or panel failure. |
+
+## Development
+
+```bash
+python -m pip install -e . --group dev
+ruff check .
+ruff format --check .
+mypy
+pytest --cov
+```
+
+The tests use a simulated panel and require 100% branch coverage. They never
+contact PyronixCloud.
+
+## Licence
+
+[MIT](LICENSE)

aiopyronix-0.1.0/README.md

@@ -0,0 +1,150 @@
+# aiopyronix
+
+[![PyPI](https://img.shields.io/pypi/v/aiopyronix)](https://pypi.org/project/aiopyronix/)
+[![CI](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml)
+[![Licence: MIT](https://img.shields.io/badge/Licence-MIT-0F766E.svg)](https://github.com/Herbertmt978/aiopyronix/blob/main/LICENSE)
+
+An asynchronous Python client for Pyronix alarm panels reached through
+PyronixCloud, the service used by the HomeControl 2.0 app.
+
+It powers the [Pyronix HomeControl integration for Home Assistant](https://github.com/Herbertmt978/HA-Pyronix),
+and it can be used on its own. This is independent community software. It is
+not an official Pyronix, Hikvision or Home Assistant product.
+
+## Design
+
+The client controls an intruder alarm, so caution takes priority over convenience:
+
+- **Explicit sessions.** Nothing connects when a `PanelClient` is created. A
+  session opens only when `connect()` is called. There is no polling or
+  automatic reconnection.
+- **Idle sessions close.** A session closes after five minutes without a
+  `connect()` or `control()` call. Heartbeats keep the socket alive, but they
+  do not extend that limit.
+- **Commands are sent once.** `control()` arms or disarms exactly one area and
+  waits for the panel to confirm it. When the outcome cannot be confirmed, it
+  raises `CommandUnconfirmedError`. The command is never repeated, even after
+  a lost connection.
+- **A narrow command set.** Only single-area arm and disarm are possible. The
+  library has no forced omissions, outputs, installer functions or cloud
+  account changes.
+- **Nothing sensitive is logged.** The library does not log. Its error
+  messages are fixed text and never contain credentials, panel data or wire
+  payloads.
+
+Status updates and commands share one WebSocket. Each frame is encrypted with
+a session key agreed through ECDH (P-256) and checked for integrity and
+sequence.
+
+## Installation
+
+```bash
+pip install aiopyronix
+```
+
+Python 3.14 or later is required.
+
+## Connection details
+
+`PanelClient` needs the connection details that the HomeControl 2.0 app saves
+when you sign in:
+
+| Field | Meaning |
+| --- | --- |
+| `AppUser`, `PushId`, `DeviceId` | The app installation registered with PyronixCloud |
+| `PanelId` | The eight-character panel identifier |
+| `SystemName` | The panel name shown in the app |
+| `PanelPwd` | The app password stored for the panel |
+| `UserCode` | The panel user code, four to eight digits |
+
+`AppVersion`, `AppType`, `OSName`, `OSVersion`, `NetworkType` and `AppLang`
+are optional. Other keys are discarded. The Home Assistant integration
+includes a [setup helper](https://github.com/Herbertmt978/HA-Pyronix#connect-your-own-alarm)
+that reads these details from your own signed-in app.
+
+## Usage
+
+```python
+import asyncio
+import json
+from pathlib import Path
+
+import aiohttp
+
+from aiopyronix import CommandUnconfirmedError, PanelClient
+
+
+async def main() -> None:
+    auth = json.loads(Path("pyronix.json").read_text())
+    async with aiohttp.ClientSession() as http:
+        client = PanelClient(http, auth)
+        try:
+            snapshot = await client.connect()
+            for index, area in snapshot["areas"].items():
+                print(index, area["name"], area["status"])
+
+            if 0 in snapshot["can_arm"]:
+                try:
+                    await client.control("arm", 0)
+                except CommandUnconfirmedError:
+                    print("Check the panel before trying again")
+        finally:
+            await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+`connect()` returns once every area the user may control has reported its
+state. Calling it on an open session returns the current state and restarts
+the idle timer.
+
+### Callbacks
+
+- `on_update(snapshot)` runs whenever the panel reports new state.
+- `on_state()` runs when `state`, `detail` or `idle_expires_at` changes.
+- `create_task(coroutine)` starts the session's background reader. It defaults
+  to `asyncio.create_task`. Home Assistant passes
+  `entry.async_create_background_task`.
+
+### State
+
+- `snapshot()` returns an independent copy of the latest `Snapshot`: the
+  `areas`, the `can_arm` and `can_disarm` area sets, `permissions_received`,
+  `observed_at` and, when reported, `firmware`.
+- `state` is `disconnected`, `connecting`, `connected` or `error`. After an
+  error, `detail` holds a fixed explanation.
+- `idle_expires_at` is the wall-clock time at which an idle session will close.
+
+Area `value` codes are listed in `STATUS`: `0` Unset, `1` Set, `2` Alarmed,
+`3` Setting, `4` Cannot Set, `5` Can Override and `6` Set Cancelled. An arm
+request counts as confirmed once the area reports Setting. Arming is refused
+while an area reports Cannot Set or Can Override.
+
+### Errors
+
+All errors derive from `ProtocolError`:
+
+| Exception | Meaning |
+| --- | --- |
+| `AuthenticationError` | The cloud or panel rejected the credentials. Ask for new details; do not retry automatically. |
+| `PanelBusyError` | Another command on this client is still waiting for its result. |
+| `CommandUnconfirmedError` | The command may have reached the panel, but its outcome is unknown. `snapshot` holds the latest state, if the session is still open. |
+| `ProtocolError` | Any other connection, validation or panel failure. |
+
+## Development
+
+```bash
+python -m pip install -e . --group dev
+ruff check .
+ruff format --check .
+mypy
+pytest --cov
+```
+
+The tests use a simulated panel and require 100% branch coverage. They never
+contact PyronixCloud.
+
+## Licence
+
+[MIT](LICENSE)

aiopyronix-0.1.0/RELEASING.md

@@ -0,0 +1,67 @@
+# Releasing aiopyronix
+
+Releases are built and uploaded by GitHub Actions. No PyPI API token exists:
+PyPI trusts the `Release` workflow through
+[trusted publishing](https://docs.pypi.org/trusted-publishers/), and each
+upload carries a signed attestation of the workflow run that built it.
+
+## One-time setup
+
+- **GitHub:** the public repository `Herbertmt978/aiopyronix`, with issues
+  enabled. Its `pypi` environment accepts deployments only from tags matching
+  `v*`.
+- **PyPI:** a trusted publisher for the `aiopyronix` project, bound to owner
+  `Herbertmt978`, repository `aiopyronix`, workflow `release.yml` and
+  environment `pypi`. Before the first upload it is a pending publisher; the
+  first successful upload creates the project.
+
+Changing the workflow file name, the environment name or the repository owner
+breaks publishing until the PyPI publisher is updated to match.
+
+## Versioning
+
+The project follows [Semantic Versioning](https://semver.org/). Before 1.0:
+
+- a patch release fixes behaviour without changing the public API;
+- a minor release adds or changes public API, or changes what reaches the
+  panel. The changelog calls out any change to commands, confirmation or
+  session lifetime.
+
+The version is written once, in `pyproject.toml`. The release workflow stops
+unless the tag is exactly `v` followed by that version.
+
+## Cutting a release
+
+1. Update `version` in `pyproject.toml` and add a `CHANGELOG.md` entry.
+2. Run the checks locally:
+
+   ```bash
+   ruff check .
+   ruff format --check .
+   mypy
+   pytest --cov
+   ```
+
+3. Merge to `main` and wait for CI to pass.
+4. Publish a GitHub release whose tag is `v<version>`, targeting `main`:
+
+   ```bash
+   gh release create v0.1.1 --target main --title 0.1.1 --notes-file notes.md
+   ```
+
+5. The `Release` workflow reruns CI, checks the tag, builds the sdist and
+   wheel, and uploads both to PyPI. Confirm the new version at
+   <https://pypi.org/project/aiopyronix/>.
+6. In [HA-Pyronix](https://github.com/Herbertmt978/HA-Pyronix), update the
+   pin in `manifest.json` and `requirements-dev.txt`, then run its tests on
+   the minimum and current Home Assistant versions.
+
+A published version cannot be replaced on PyPI. If a release is wrong, yank it
+on PyPI and publish a new patch version.
+
+## Licence
+
+aiopyronix is MIT licensed, like the integration. Its runtime dependencies are
+also OSI approved: aiohttp (Apache-2.0) and cryptography (Apache-2.0 or
+BSD-3-Clause). The wheel records the licence as an SPDX expression and
+includes the `LICENSE` file.

aiopyronix-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiopyronix"
+version = "0.1.0"
+description = "Asynchronous PyronixCloud client for Pyronix alarm panels, with explicit sessions"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Herbertmt978" }]
+requires-python = ">=3.14"
+dependencies = [
+  "aiohttp>=3.13.0",
+  "cryptography>=47.0.0",
+]
+keywords = ["pyronix", "homecontrol", "alarm", "asyncio", "home-assistant"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Home Automation",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/Herbertmt978/aiopyronix"
+Issues = "https://github.com/Herbertmt978/aiopyronix/issues"
+Changelog = "https://github.com/Herbertmt978/aiopyronix/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "mypy==2.4.1",
+  "pytest==9.0.3",
+  "pytest-asyncio==1.4.0",
+  "pytest-cov==7.1.0",
+  "ruff==0.17.3",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/CHANGELOG.md", "/RELEASING.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+# Unhandled task exceptions and resource warnings are defects here, not noise.
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["aiopyronix"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+files = ["src/aiopyronix"]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+# Home Assistant Core's rule selection, so the library reads like the integration.
+select = [
+  "A001", "ASYNC", "B", "BLE", "C", "COM818", "D", "DTZ003", "DTZ004", "DTZ011", "E", "F",
+  "FLY", "FURB", "G", "I", "INP", "ISC", "ICN001", "ICN002", "LOG", "N804", "N805", "N806",
+  "N815", "PERF", "PGH", "PIE", "PL", "PT", "PTH", "PYI", "RET", "RSE", "RUF", "S102", "S103",
+  "S107", "S108", "S301", "S306", "S307", "S313", "S314", "S315", "S316", "S317", "S318",
+  "S319", "S601", "S602", "S604", "S608", "S609", "SIM", "SLF", "SLOT", "T100", "T20", "TC",
+  "TID", "TRY", "UP", "W",
+]
+ignore = [
+  "D202", "D203", "D213", "D406", "D407", "D417", "E501", "PLC1901", "PLR0911", "PLR0912",
+  "PLR0913", "PLR0915", "PLR0917", "PLR2004", "PLW0108", "PLW2901", "PT011", "PT018",
+  "RUF001", "RUF012", "SIM102", "SIM103", "SIM108", "TC001", "TC002", "TC003", "TRY003",
+  "COM812",
+]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+known-first-party = ["aiopyronix", "tests"]
+combine-as-imports = true
+split-on-trailing-comma = false
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"__future__.annotations".msg = "Not needed; the library requires Python 3.14"
+"async_timeout".msg = "use asyncio.timeout instead"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 25
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests exercise private session state directly.
+"tests/*.py" = ["D", "SLF001"]

aiopyronix-0.1.0/src/aiopyronix/__init__.py

@@ -0,0 +1,37 @@
+"""Asynchronous PyronixCloud client for Pyronix alarm panels.
+
+A session opens only when the caller asks for it. Each arm or disarm request is
+sent once and never repeated. Connection fields and wire payloads are never logged.
+"""
+
+from .client import (
+    OPTIONAL_AUTH,
+    REQUIRED_AUTH,
+    STATUS,
+    AreaState,
+    AuthenticationError,
+    CommandUnconfirmedError,
+    ConnectionState,
+    PanelBusyError,
+    PanelClient,
+    Snapshot,
+    empty_snapshot,
+    validate_auth,
+)
+from .protocol import ProtocolError
+
+__all__ = [
+    "OPTIONAL_AUTH",
+    "REQUIRED_AUTH",
+    "STATUS",
+    "AreaState",
+    "AuthenticationError",
+    "CommandUnconfirmedError",
+    "ConnectionState",
+    "PanelBusyError",
+    "PanelClient",
+    "ProtocolError",
+    "Snapshot",
+    "empty_snapshot",
+    "validate_auth",
+]