axis 71__tar.gz → 73__tar.gz

{axis-71 → axis-73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis
-Version: 71
+Version: 73
 Summary: A Python library for communicating with devices from Axis Communications
 Author-email: Robert Svensson <Kane610@users.noreply.github.com>
 License: MIT
@@ -21,20 +21,24 @@ Requires-Dist: aiohttp>=3.12
 Requires-Dist: faust-cchardet>=2.1.18
 Requires-Dist: orjson>3.9
 Requires-Dist: packaging>23
+Requires-Dist: tomli>=2.0
+Requires-Dist: tomli-w>=1.0
 Requires-Dist: xmltodict>=0.13.0
+Requires-Dist: zeroconf==0.150.0
 Provides-Extra: requirements
-Requires-Dist: aiohttp==3.13.5; extra == "requirements"
+Requires-Dist: aiohttp==3.14.1; extra == "requirements"
 Requires-Dist: orjson==3.11.9; extra == "requirements"
 Requires-Dist: packaging==26.2; extra == "requirements"
 Requires-Dist: xmltodict==1.0.4; extra == "requirements"
+Requires-Dist: zeroconf==0.150.0; extra == "requirements"
 Provides-Extra: requirements-test
-Requires-Dist: mypy==2.0.0; extra == "requirements-test"
-Requires-Dist: pytest==9.0.3; extra == "requirements-test"
-Requires-Dist: pytest-aiohttp==1.1.0; extra == "requirements-test"
-Requires-Dist: pytest-asyncio==1.3.0; extra == "requirements-test"
+Requires-Dist: mypy==2.1.0; extra == "requirements-test"
+Requires-Dist: pytest==9.1.1; extra == "requirements-test"
+Requires-Dist: pytest-aiohttp==1.1.1; extra == "requirements-test"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "requirements-test"
 Requires-Dist: pytest-cov==7.1.0; extra == "requirements-test"
-Requires-Dist: ruff==0.15.12; extra == "requirements-test"
-Requires-Dist: types-xmltodict==v1.0.1.20260508; extra == "requirements-test"
+Requires-Dist: ruff==0.15.20; extra == "requirements-test"
+Requires-Dist: types-xmltodict==v1.0.1.20260518; extra == "requirements-test"
 Provides-Extra: requirements-dev
 Requires-Dist: pre-commit==4.6.0; extra == "requirements-dev"
 Dynamic: license-file
@@ -79,6 +83,22 @@ Initial `ty` support is configured as an opt-in check and does not replace `mypy
 uvx ty check
 ```
 
+## CLI navigation contract
+
+The interactive CLI in `axis/cli/` follows a menu-first model.
+Router runtime is the only interactive execution path.
+
+- Canonical route graph: `main -> devices -> device_operations -> {api|events|accounts}`.
+- `device_operations` routes to feature submenus using router navigation, not direct feature command execution.
+- Feature nodes (`api`, `events`, `accounts`) own their local menu layout and selected-device context rendering.
+- `b` always navigates to `parent_id`; `e` always exits.
+
+To keep the CLI reusable boundary clear:
+
+- CLI concerns (menu keys, prompts, render text, router state) stay in `axis/cli/`.
+- `axis/interfaces/` and `axis/models/` must remain presentation-agnostic and reusable by non-CLI consumers.
+- Domain layers return typed data/errors; CLI adapters map them to user-facing text and flow.
+
 ## Initialization architecture
 
 Vapix initialization is phase-based and driven by handler metadata:
@@ -89,7 +109,42 @@ Vapix initialization is phase-based and driven by handler metadata:
 
 Handlers declare phase membership through `handler_groups` and may customize phase eligibility through `should_initialize_in_group`.
 
+## Request and response typing
+
+`Vapix.api_request()` is the single typed request entrypoint.
+
+- Request models declare their decode contract with `ApiRequest[ResponseT]`.
+- Every `ApiRequest` subclass must set `response_type` explicitly.
+- Decoded/read requests use their concrete response model as `response_type`.
+- Write-style requests use `BytesResponse` as `response_type`.
+
+Examples:
+
+```python
+@dataclass
+class ListApisRequest(ApiRequest[GetAllApisResponse]):
+	response_type = GetAllApisResponse
+
+
+@dataclass
+class SetPortsRequest(ApiRequest[ApiResponse[bytes]]):
+	response_type = BytesResponse
+```
+
+Handler methods may unwrap `.data` when they intentionally preserve a bytes-returning boundary.
+
 Example fallback policy:
 
 - `LightHandler` participates in both `API_DISCOVERY` and `PARAM_CGI_FALLBACK`.
 - In `PARAM_CGI_FALLBACK`, it initializes only when not listed in API discovery and listed in parameters.
+
+## Event Instance Model Notes
+
+`EventInstance` keeps `name` as the raw device-provided `NiceName` value.
+
+`EventInstance.source` and `EventInstance.data` are typed containers (`EventInstanceSource` and `EventInstanceData`) built from `SimpleItemInstance` payloads.
+
+For compatibility with integrations that still need the historical raw payload shape, `EventInstance` also exposes:
+
+- `raw_source`: returns `{}` or a dict or a list of dicts.
+- `raw_data`: returns `{}` or a dict or a list of dicts.

axis-73/README.md

@@ -0,0 +1,105 @@
+# axis
+
+Python project to set up a connection towards Axis Communications devices and to subscribe to specific events on the metadatastream.
+
+## Development setup
+
+`uv` is required for development setup:
+
+```bash
+uv python install 3.14
+uv sync --python 3.14 --all-extras
+```
+
+Or run the bootstrap script, which installs `uv` if needed and provisions Python 3.14 automatically:
+
+```bash
+./setup.sh
+```
+
+Dependencies are locked via `uv.lock`. Regenerate lock data when dependency inputs change:
+
+```bash
+uv lock
+```
+
+Run checks with `uv`:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy axis
+uv run pytest
+```
+
+Initial `ty` support is configured as an opt-in check and does not replace `mypy`:
+
+```bash
+uvx ty check
+```
+
+## CLI navigation contract
+
+The interactive CLI in `axis/cli/` follows a menu-first model.
+Router runtime is the only interactive execution path.
+
+- Canonical route graph: `main -> devices -> device_operations -> {api|events|accounts}`.
+- `device_operations` routes to feature submenus using router navigation, not direct feature command execution.
+- Feature nodes (`api`, `events`, `accounts`) own their local menu layout and selected-device context rendering.
+- `b` always navigates to `parent_id`; `e` always exits.
+
+To keep the CLI reusable boundary clear:
+
+- CLI concerns (menu keys, prompts, render text, router state) stay in `axis/cli/`.
+- `axis/interfaces/` and `axis/models/` must remain presentation-agnostic and reusable by non-CLI consumers.
+- Domain layers return typed data/errors; CLI adapters map them to user-facing text and flow.
+
+## Initialization architecture
+
+Vapix initialization is phase-based and driven by handler metadata:
+
+- `API_DISCOVERY`: handlers initialized after API discovery.
+- `PARAM_CGI_FALLBACK`: handlers that may initialize from parameter support when not listed in discovery.
+- `APPLICATION`: handlers initialized after applications are loaded.
+
+Handlers declare phase membership through `handler_groups` and may customize phase eligibility through `should_initialize_in_group`.
+
+## Request and response typing
+
+`Vapix.api_request()` is the single typed request entrypoint.
+
+- Request models declare their decode contract with `ApiRequest[ResponseT]`.
+- Every `ApiRequest` subclass must set `response_type` explicitly.
+- Decoded/read requests use their concrete response model as `response_type`.
+- Write-style requests use `BytesResponse` as `response_type`.
+
+Examples:
+
+```python
+@dataclass
+class ListApisRequest(ApiRequest[GetAllApisResponse]):
+	response_type = GetAllApisResponse
+
+
+@dataclass
+class SetPortsRequest(ApiRequest[ApiResponse[bytes]]):
+	response_type = BytesResponse
+```
+
+Handler methods may unwrap `.data` when they intentionally preserve a bytes-returning boundary.
+
+Example fallback policy:
+
+- `LightHandler` participates in both `API_DISCOVERY` and `PARAM_CGI_FALLBACK`.
+- In `PARAM_CGI_FALLBACK`, it initializes only when not listed in API discovery and listed in parameters.
+
+## Event Instance Model Notes
+
+`EventInstance` keeps `name` as the raw device-provided `NiceName` value.
+
+`EventInstance.source` and `EventInstance.data` are typed containers (`EventInstanceSource` and `EventInstanceData`) built from `SimpleItemInstance` payloads.
+
+For compatibility with integrations that still need the historical raw payload shape, `EventInstance` also exposes:
+
+- `raw_source`: returns `{}` or a dict or a list of dicts.
+- `raw_data`: returns `{}` or a dict or a list of dicts.

{axis-71 → axis-73}/axis/__main__.py

@@ -17,7 +17,7 @@ if TYPE_CHECKING:
 LOGGER = logging.getLogger(__name__)
 
 
-def event_handler(event: "Event") -> None:
+def event_handler(event: Event) -> None:
     """Receive and print events from RTSP stream."""
     LOGGER.info(event)
 
@@ -61,8 +61,8 @@ async def axis_device(
             "Connected to device at %s but not registered or user not admin.", host
         )
 
-    except (TimeoutError, axis.RequestError):
-        LOGGER.error("Error connecting to the Axis device at %s", host)
+    except (TimeoutError, axis.RequestError) as err:
+        LOGGER.error("Error connecting to the Axis device at %s: %s", host, err)
 
     except axis.AxisException:
         LOGGER.exception("Unknown Axis communication error occurred")

axis-73/axis/cli/__init__.py

@@ -0,0 +1,4 @@
+"""Axis CLI package.
+
+This package contains the command-line interface for Axis configuration validation and TOML export.
+"""

axis-73/axis/cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core CLI runtime primitives."""

axis-73/axis/cli/core/context.py

@@ -0,0 +1,25 @@
+# ruff: noqa: D100,D101,TC003
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from axis.cli.core.gateway import DeviceGateway
+    from axis.cli.core.registry import CommandRegistry
+    from axis.cli.core.router import CliRouter
+
+DeviceEntry = dict[str, Any]
+DeviceStore = dict[str, DeviceEntry]
+
+
+@dataclass
+class CliContext:
+    config_path: Path
+    device_gateway: DeviceGateway
+    command_registry: CommandRegistry | None = None
+    router: CliRouter | None = None
+    selected_serial: str | None = None
+    selected_device: DeviceEntry | None = None

axis-73/axis/cli/core/contracts.py

@@ -0,0 +1,32 @@
+# ruff: noqa: D100,D101,D102
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol
+
+if TYPE_CHECKING:
+    from axis.cli.core.context import CliContext
+    from axis.cli.core.io import CliIO
+
+
+@dataclass(frozen=True)
+class CommandCapabilities:
+    requires_device: bool = False
+    destructive: bool = False
+    read_only_safe: bool = True
+
+
+@dataclass
+class CommandResult:
+    status: Literal["ok", "error", "cancelled"] = "ok"
+    message: str | None = None
+    payload: object | None = None
+
+
+class Command(Protocol):
+    id: str
+    title: str
+    capabilities: CommandCapabilities
+
+    async def run(self, ctx: CliContext, io: CliIO) -> CommandResult: ...

axis-73/axis/cli/core/gateway.py

@@ -0,0 +1,52 @@
+# ruff: noqa: D100,D101,D102
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from aiohttp import ClientSession
+
+from axis.device import AxisDevice
+from axis.errors import RequestError
+from axis.models.configuration import Configuration
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from axis.cli.core.context import DeviceEntry
+
+
+class DeviceGateway:
+    async def run[ReturnT](
+        self,
+        device_entry: DeviceEntry,
+        operation: Callable[[AxisDevice], Awaitable[ReturnT]],
+    ) -> ReturnT | None:
+        config_data = device_entry.get("config", {})
+        if not isinstance(config_data, dict):
+            print("Stored device config is incomplete. Please re-add the device.")  # noqa: T201
+            return None
+
+        host = str(config_data.get("host", "")).strip()
+        username = str(config_data.get("username", "")).strip()
+        password = str(config_data.get("password", ""))
+        if not host or not username:
+            print("Stored device config is incomplete. Please re-add the device.")  # noqa: T201
+            return None
+
+        try:
+            async with ClientSession() as session:
+                config = Configuration(
+                    session=session,
+                    host=host,
+                    username=username,
+                    password=password,
+                )
+                device = AxisDevice(config)
+                return await operation(device)
+        except RequestError as exc:
+            print(f"Device request failed: {exc}")  # noqa: T201
+        except (ValueError, KeyError, OSError) as exc:
+            print(f"Failed to connect to selected device: {exc}")  # noqa: T201
+
+        return None

axis-73/axis/cli/core/io.py

@@ -0,0 +1,25 @@
+# ruff: noqa: D100,D101,D102
+
+from __future__ import annotations
+
+import getpass
+from typing import Protocol
+
+
+class CliIO(Protocol):
+    def prompt(self, text: str) -> str: ...
+
+    def prompt_password(self, text: str) -> str: ...
+
+    def write(self, text: str) -> None: ...
+
+
+class TerminalIO:
+    def prompt(self, text: str) -> str:
+        return input(text)
+
+    def prompt_password(self, text: str) -> str:
+        return getpass.getpass(text)
+
+    def write(self, text: str) -> None:
+        print(text)  # noqa: T201

axis-73/axis/cli/core/registry.py

@@ -0,0 +1,26 @@
+# ruff: noqa: D100,D101,D102
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from axis.cli.core.contracts import Command
+
+
+@dataclass
+class CommandRegistry:
+    _commands: dict[str, Command] = field(default_factory=dict)
+
+    def register_command(self, command: Command) -> None:
+        if command.id in self._commands:
+            msg = f"Command '{command.id}' is already registered."
+            raise ValueError(msg)
+        self._commands[command.id] = command
+
+    def get_command(self, command_id: str) -> Command:
+        return self._commands[command_id]
+
+    def list_commands(self) -> list[Command]:
+        return list(self._commands.values())

axis-73/axis/cli/core/router.py

@@ -0,0 +1,114 @@
+# ruff: noqa: D100,D101,D102
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from axis.cli.core.context import CliContext
+    from axis.cli.core.io import CliIO
+
+
+@dataclass(frozen=True)
+class MenuItem:
+    key: str
+    label: str
+    action: str
+    command_id: str | None = None
+    next_node_id: str | None = None
+
+
+@dataclass
+class MenuNode:
+    id: str
+    title: str
+    items: list[MenuItem]
+    parent_id: str | None = None
+    render: Callable[[CliContext, CliIO], None] | None = None
+
+
+@dataclass
+class CliRouter:
+    nodes: dict[str, MenuNode] = field(default_factory=dict)
+
+    def register_node(self, node: MenuNode) -> None:
+        if node.id in self.nodes:
+            msg = f"Node '{node.id}' is already registered."
+            raise ValueError(msg)
+        self.nodes[node.id] = node
+
+    async def run(
+        self, ctx: CliContext, io: CliIO, start_node_id: str = "main"
+    ) -> None:
+        current = start_node_id
+        while True:
+            node = self.nodes[current]
+            if node.render is not None:
+                node.render(ctx, io)
+            io.write(f"\n{node.title}:")
+            for item in node.items:
+                io.write(f"  {item.key}. {item.label}")
+            io.write("  b. Back")
+            io.write("  e. Exit")
+            selection = io.prompt("Select option: ").strip().lower()
+
+            if selection == "e":
+                io.write("Exiting.")
+                raise SystemExit(0)
+            if selection == "b":
+                if node.parent_id is None:
+                    continue
+                current = node.parent_id
+                continue
+
+            matched = next((item for item in node.items if item.key == selection), None)
+            if matched is None:
+                io.write("Invalid option.")
+                continue
+
+            if matched.action == "navigate" and matched.next_node_id is not None:
+                current = matched.next_node_id
+                continue
+
+            if matched.action == "noop":
+                continue
+
+            if matched.action == "command":
+                if matched.command_id is None:
+                    io.write("Command is not configured.")
+                    continue
+
+                registry = ctx.command_registry
+                if registry is None:
+                    io.write("Command registry is unavailable.")
+                    continue
+
+                try:
+                    command = registry.get_command(matched.command_id)
+                except KeyError:
+                    io.write(f"Unknown command: {matched.command_id}")
+                    continue
+
+                result = await command.run(ctx, io)
+                payload = result.payload
+                if result.status == "ok" and isinstance(payload, dict):
+                    requested_node = payload.get("next_node_id")
+                    if isinstance(requested_node, str):
+                        if requested_node in self.nodes:
+                            if result.message:
+                                io.write(result.message)
+                            current = requested_node
+                            continue
+                        io.write(f"Unknown node: {requested_node}")
+                if result.message:
+                    io.write(result.message)
+                elif result.status == "error":
+                    io.write("Command failed.")
+                elif result.status == "cancelled":
+                    io.write("Command cancelled.")
+                continue
+
+            io.write("Unsupported action.")