axis 72__tar.gz → 73__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis
-Version: 72
+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,19 +21,23 @@ 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.1.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: 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.13; 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"
@@ -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:

{axis-72 → axis-73}/README.md

@@ -38,6 +38,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:

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.")

axis-73/axis/cli/main.py

@@ -0,0 +1,205 @@
+"""Axis CLI composition root and compatibility exports.
+
+This module serves as the explicit bootstrap and import surface for the
+plugin-pack based CLI architecture.
+"""
+
+# ruff: noqa: RUF022,TC003
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+from axis.cli.core.context import CliContext
+from axis.cli.core.gateway import DeviceGateway
+from axis.cli.core.io import TerminalIO
+from axis.cli.core.registry import CommandRegistry
+from axis.cli.core.router import CliRouter
+from axis.cli.packs import (
+    accounts as accounts_pack,
+    api as api_pack,
+    devices as devices_pack,
+    events as events_pack,
+    navigation as navigation_pack,
+)
+
+DeviceEntry = devices_pack.DeviceEntry
+DeviceStore = devices_pack.DeviceStore
+
+# Compatibility exports from packs
+get_config_path = devices_pack.get_config_path
+load_devices = devices_pack.load_devices
+save_devices = devices_pack.save_devices
+to_toml_compatible = devices_pack.to_toml_compatible
+fetch_device_serial_and_extra = devices_pack.fetch_device_serial_and_extra
+extract_model_number = devices_pack.extract_model_number
+extract_serial_number = devices_pack.extract_serial_number
+prompt_for_device = devices_pack.prompt_for_device
+config_to_toml_dict = devices_pack.config_to_toml_dict
+_format_device_label = devices_pack._format_device_label
+_format_device_operations_label = devices_pack._format_device_operations_label
+AXIS_OUI = devices_pack.AXIS_OUI
+AXIS_SERVICE_TYPE = devices_pack.AXIS_SERVICE_TYPE
+is_axis_macaddress = devices_pack.is_axis_macaddress
+discover_axis_devices = devices_pack.discover_axis_devices
+select_discovered_device = devices_pack.select_discovered_device
+filter_discovered_devices = devices_pack.filter_discovered_devices
+validate_and_fetch_device = devices_pack.validate_and_fetch_device
+print_registered_devices = devices_pack.print_registered_devices
+migrate_unknown_entry = devices_pack.migrate_unknown_entry
+find_serial_by_host = devices_pack.find_serial_by_host
+select_device = devices_pack.select_device
+get_device_credentials = devices_pack.get_device_credentials
+run_on_selected_device = devices_pack.run_on_selected_device
+register_or_update_device = devices_pack.register_or_update_device
+delete_device = devices_pack.delete_device
+edit_device_credentials = devices_pack.edit_device_credentials
+health_check_device = devices_pack.health_check_device
+HealthCheckResult = devices_pack.HealthCheckResult
+
+fetch_supported_apis = api_pack.fetch_supported_apis
+list_supported_apis_async = api_pack.list_supported_apis_async
+run_api_read_action = api_pack.run_api_read_action
+api_drill_down_async = api_pack.api_drill_down_async
+
+fetch_event_instances = events_pack.fetch_event_instances
+list_event_instances_async = events_pack.list_event_instances_async
+events_menu_async = events_pack.events_menu_async
+_live_listen_async = events_pack._live_listen_async
+
+_validate_username = accounts_pack._validate_username
+_select_privilege = accounts_pack._select_privilege
+_account_init_confirm = accounts_pack._account_init_confirm
+_account_init_operation = accounts_pack._account_init_operation
+account_management_async = accounts_pack.account_management_async
+_list_users_async = accounts_pack._list_users_async
+_create_or_update_user_async = accounts_pack._create_or_update_user_async
+_delete_user_async = accounts_pack._delete_user_async
+
+selected_device_operations = navigation_pack.selected_device_operations
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Axis interactive CLI")
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable verbose debug output for raw device/API responses.",
+    )
+    return parser.parse_args(argv)
+
+
+def _debug_enabled_from_env() -> bool:
+    value = os.getenv("AXIS_CLI_DEBUG", "").strip().lower()
+    return value in {"1", "true", "yes", "on"}
+
+
+def _configure_logging(debug_enabled: bool) -> None:
+    loglevel = logging.DEBUG if debug_enabled else logging.INFO
+    logging.basicConfig(format="%(message)s", level=loglevel, force=True)
+
+
+def compose_builtin_packs(registry: CommandRegistry, router: CliRouter) -> None:
+    """Register built-in CLI packs explicitly from a single composition root."""
+    devices_pack.register(registry, router)
+    api_pack.register(registry, router)
+    events_pack.register(registry, router)
+    accounts_pack.register(registry, router)
+    navigation_pack.register(registry, router)
+
+
+def build_cli_runtime(config_path: Path) -> CliContext:
+    """Create shared runtime context for the CLI process."""
+    registry = CommandRegistry()
+    router = CliRouter()
+    compose_builtin_packs(registry, router)
+    return CliContext(
+        config_path=config_path,
+        device_gateway=DeviceGateway(),
+        command_registry=registry,
+        router=router,
+    )
+
+
+def main(*, debug: bool | None = None) -> None:
+    """Run the interactive device registry CLI."""
+    debug_enabled = _debug_enabled_from_env() if debug is None else debug
+    _configure_logging(debug_enabled)
+
+    if debug_enabled:
+        os.environ["AXIS_CLI_DEBUG"] = "1"
+        print("Debug mode enabled. Verbose responses will be shown.")  # noqa: T201
+
+    config_path = get_config_path()
+    runtime = build_cli_runtime(config_path)
+
+    if runtime.router is None:
+        msg = "Router runtime is unavailable."
+        raise RuntimeError(msg)
+
+    terminal_io = TerminalIO()
+    while True:
+        try:
+            asyncio.run(runtime.router.run(runtime, terminal_io, start_node_id="main"))
+        except KeyboardInterrupt:
+            print("\nInterrupted. Use 'e' to exit.")  # noqa: T201
+            continue
+
+
+__all__ = [
+    "DeviceEntry",
+    "DeviceStore",
+    "compose_builtin_packs",
+    "build_cli_runtime",
+    "main",
+    "get_config_path",
+    "load_devices",
+    "save_devices",
+    "to_toml_compatible",
+    "fetch_device_serial_and_extra",
+    "extract_model_number",
+    "extract_serial_number",
+    "prompt_for_device",
+    "config_to_toml_dict",
+    "_format_device_label",
+    "AXIS_OUI",
+    "AXIS_SERVICE_TYPE",
+    "is_axis_macaddress",
+    "discover_axis_devices",
+    "select_discovered_device",
+    "filter_discovered_devices",
+    "validate_and_fetch_device",
+    "print_registered_devices",
+    "migrate_unknown_entry",
+    "find_serial_by_host",
+    "select_device",
+    "get_device_credentials",
+    "run_on_selected_device",
+    "register_or_update_device",
+    "fetch_supported_apis",
+    "list_supported_apis_async",
+    "run_api_read_action",
+    "api_drill_down_async",
+    "fetch_event_instances",
+    "list_event_instances_async",
+    "events_menu_async",
+    "_live_listen_async",
+    "_validate_username",
+    "_select_privilege",
+    "_account_init_confirm",
+    "_account_init_operation",
+    "account_management_async",
+    "_list_users_async",
+    "_create_or_update_user_async",
+    "_delete_user_async",
+    "selected_device_operations",
+]
+
+
+if __name__ == "__main__":
+    args = _parse_args()
+    main(debug=args.debug)

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

@@ -0,0 +1 @@
+"""Built-in CLI plugin packs."""