axis 67__tar.gz → 69__tar.gz

axis-69/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: axis
+Version: 69
+Summary: A Python library for communicating with devices from Axis Communications
+Author-email: Robert Svensson <Kane610@users.noreply.github.com>
+License: MIT
+Project-URL: Source Code, https://github.com/Kane610/axis
+Project-URL: Bug Reports, https://github.com/Kane610/axis/issues
+Project-URL: Forum, https://community.home-assistant.io/t/axis-camera-component/
+Keywords: axis,vapix,homeassistant
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.14.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.12
+Requires-Dist: faust-cchardet>=2.1.18
+Requires-Dist: httpx>=0.26
+Requires-Dist: orjson>3.9
+Requires-Dist: packaging>23
+Requires-Dist: xmltodict>=0.13.0
+Provides-Extra: requirements
+Requires-Dist: aiohttp==3.13.5; extra == "requirements"
+Requires-Dist: httpx==0.28.1; extra == "requirements"
+Requires-Dist: orjson==3.11.8; extra == "requirements"
+Requires-Dist: packaging==26.2; extra == "requirements"
+Requires-Dist: xmltodict==1.0.4; extra == "requirements"
+Provides-Extra: requirements-test
+Requires-Dist: mypy==1.20.2; 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-cov==7.1.0; extra == "requirements-test"
+Requires-Dist: respx==0.23.1; extra == "requirements-test"
+Requires-Dist: ruff==0.15.12; extra == "requirements-test"
+Requires-Dist: types-xmltodict==v1.0.1.20260408; extra == "requirements-test"
+Provides-Extra: requirements-dev
+Requires-Dist: pre-commit==4.6.0; extra == "requirements-dev"
+Dynamic: license-file
+
+# 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
+```
+
+## 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`.
+
+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.

axis-69/README.md

@@ -0,0 +1,54 @@
+# 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
+```
+
+## 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`.
+
+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.

{axis-67 → axis-69}/axis/__main__.py

@@ -28,10 +28,12 @@ async def axis_device(
     username: str,
     password: str,
     web_proto: WebProtocol,
+    stream_mode: str = "rtsp",
     is_companion: bool = False,
 ) -> axis.device.AxisDevice:
     """Create a Axis device."""
     session = create_session()
+    websocket_enabled, websocket_force = websocket_flags_from_mode(stream_mode)
     device = AxisDevice(
         Configuration(
             session,
@@ -41,6 +43,8 @@ async def axis_device(
             password=password,
             is_companion=is_companion,
             web_proto=web_proto,
+            websocket_enabled=websocket_enabled,
+            websocket_force=websocket_force,
         )
     )
 
@@ -74,6 +78,7 @@ async def main(
     params: bool,
     events: bool,
     web_proto: WebProtocol,
+    stream_mode: str,
 ) -> None:
     """CLI method for library."""
     LOGGER.info("Connecting to Axis device")
@@ -84,6 +89,7 @@ async def main(
         username,
         password,
         web_proto=web_proto,
+        stream_mode=stream_mode,
     )
 
     if not device:
@@ -126,6 +132,15 @@ async def close_session(session: aiohttp.ClientSession) -> None:
     await session.close()
 
 
+def websocket_flags_from_mode(stream_mode: str) -> tuple[bool, bool]:
+    """Translate CLI stream mode to websocket enable/force flags."""
+    if stream_mode == "auto":
+        return True, False
+    if stream_mode == "event":
+        return True, True
+    return False, False
+
+
 if __name__ == "__main__":
     parser = argparse.ArgumentParser()
     parser.add_argument("host", type=str)
@@ -135,6 +150,11 @@ if __name__ == "__main__":
     parser.add_argument("--proto", type=str, default="http")
     parser.add_argument("--events", action="store_true")
     parser.add_argument("--params", action="store_true")
+    parser.add_argument(
+        "--stream-mode",
+        choices=["auto", "rtsp", "event"],
+        default="rtsp",
+    )
     parser.add_argument("-D", "--debug", action="store_true")
     args = parser.parse_args()
 
@@ -163,6 +183,7 @@ if __name__ == "__main__":
                 params=args.params,
                 events=args.events,
                 web_proto=WebProtocol(args.proto),
+                stream_mode=args.stream_mode,
             )
         )
 

axis-69/axis/interfaces/aiohttp_digest.py

@@ -0,0 +1,266 @@
+"""Aiohttp digest authentication handler.
+
+Implements library-managed RFC 2617 digest authentication for aiohttp requests
+to handle special characters in request parameters that break middleware-based auth.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+import secrets
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import quote, urlsplit
+
+from ..models.configuration import AuthScheme
+
+if TYPE_CHECKING:
+    from ..device import AxisDevice
+
+LOGGER = logging.getLogger(__name__)
+TIME_OUT = 15
+
+
+class AiohttpDigestAuth:
+    """Manages digest authentication for aiohttp requests."""
+
+    def __init__(self, device: AxisDevice) -> None:
+        """Initialize digest auth handler."""
+        self.device = device
+        self._nonce: str | None = None
+        self._nonce_count = 0
+
+    def should_use_library_digest(self, http_client: str, has_basic_auth: bool) -> bool:
+        """Return if aiohttp requests should use library-managed digest auth.
+
+        Args:
+            http_client: Name of HTTP client ("aiohttp" or "httpx").
+            has_basic_auth: Whether basic auth is configured.
+
+        Returns:
+            True if library-managed digest should be used.
+
+        """
+        return (
+            http_client == "aiohttp"
+            and not has_basic_auth
+            and self.device.config.auth_scheme != AuthScheme.BASIC
+        )
+
+    def request_target(
+        self, url: str, params: dict[str, str] | None, should_encode: bool
+    ) -> tuple[str, dict[str, str] | None]:
+        """Return request URL and params for aiohttp request.
+
+        With library-managed digest auth, pre-encode params into the URL so the
+        signed URI exactly matches the request-target on the wire.
+
+        Args:
+            url: Base request URL.
+            params: Optional query parameters.
+            should_encode: Whether to pre-encode params for digest signing.
+
+        Returns:
+            Tuple of (request_url, request_params) to use in actual request.
+
+        """
+        if params is None or not should_encode:
+            return url, params
+
+        separator = "&" if "?" in url else "?"
+        encoded_parts = [
+            f"{quote(k, safe='')}={quote(v, safe='')}" for k, v in params.items()
+        ]
+        encoded_query = "&".join(encoded_parts)
+        encoded_url = f"{url}{separator}{encoded_query}"
+        return encoded_url, None
+
+    def extract_challenge(self, headers: Any) -> str | None:
+        """Return digest challenge header when present.
+
+        Args:
+            headers: Response headers (dict-like or aiohttp MultiDictProxy).
+
+        Returns:
+            Digest challenge string if present, None otherwise.
+
+        """
+        candidates: list[str] = []
+        if hasattr(headers, "getall"):
+            candidates.extend(cast("list[str]", headers.getall("WWW-Authenticate", [])))
+        else:
+            for name, value in cast("dict[str, str]", headers).items():
+                if name.lower() == "www-authenticate":
+                    candidates.append(value)
+
+        for value in candidates:
+            if value.lower().startswith("digest "):
+                return value
+        return None
+
+    def build_authorization(
+        self,
+        method: str,
+        request_url: str,
+        digest_challenge: str,
+    ) -> str | None:
+        """Build digest authorization header from challenge and request URI.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            request_url: Full request URL (will extract path + query).
+            digest_challenge: Digest challenge string from WWW-Authenticate header.
+
+        Returns:
+            Authorization header value or None if digest cannot be built.
+
+        """
+        challenge_values = {
+            key.lower(): value.strip('"')
+            for key, value in re.findall(
+                r"(\w+)=((?:\"[^\"]*\")|(?:[^,]+))", digest_challenge
+            )
+        }
+
+        realm = challenge_values.get("realm")
+        nonce = challenge_values.get("nonce")
+        if realm is None or nonce is None:
+            return None
+
+        algorithm = challenge_values.get("algorithm", "MD5").upper()
+        if algorithm != "MD5":
+            LOGGER.debug("Unsupported digest algorithm for aiohttp path: %s", algorithm)
+            return None
+
+        uri = self._digest_uri(request_url)
+        qop = None
+        if qop_header := challenge_values.get("qop"):
+            qop_values = [value.strip() for value in qop_header.split(",")]
+            if "auth" in qop_values:
+                qop = "auth"
+
+        username = self.device.config.username
+        password = self.device.config.password
+        ha1 = hashlib.md5(f"{username}:{realm}:{password}".encode()).hexdigest()
+        ha2 = hashlib.md5(f"{method.upper()}:{uri}".encode()).hexdigest()
+
+        parts = [
+            f'username="{username}"',
+            f'realm="{realm}"',
+            f'nonce="{nonce}"',
+            f'uri="{uri}"',
+            'algorithm="MD5"',
+        ]
+
+        if opaque := challenge_values.get("opaque"):
+            parts.append(f'opaque="{opaque}"')
+
+        if qop == "auth":
+            if nonce != self._nonce:
+                self._nonce = nonce
+                self._nonce_count = 0
+
+            self._nonce_count += 1
+            nc = f"{self._nonce_count:08x}"
+            cnonce = secrets.token_hex(8)
+            response = hashlib.md5(
+                f"{ha1}:{nonce}:{nc}:{cnonce}:{qop}:{ha2}".encode()
+            ).hexdigest()
+            parts.extend(
+                [
+                    f'response="{response}"',
+                    f"qop={qop}",
+                    f"nc={nc}",
+                    f'cnonce="{cnonce}"',
+                ]
+            )
+        else:
+            response = hashlib.md5(f"{ha1}:{nonce}:{ha2}".encode()).hexdigest()
+            parts.append(f'response="{response}"')
+
+        return f"Digest {', '.join(parts)}"
+
+    def _digest_uri(self, request_url: str) -> str:
+        """Return path + query request-target URI for digest signing.
+
+        Args:
+            request_url: Full request URL.
+
+        Returns:
+            Path and query string for digest signature.
+
+        """
+        split_result = urlsplit(request_url)
+        if split_result.query:
+            return f"{split_result.path}?{split_result.query}"
+        return split_result.path
+
+    async def perform_request(
+        self,
+        session: Any,
+        method: str,
+        url: str,
+        request_data: bytes | dict[str, str] | None,
+        headers: dict[str, str] | None,
+        params: dict[str, str] | None,
+    ) -> tuple[int, dict[str, str], bytes]:
+        """Execute aiohttp request with digest auth handling.
+
+        Args:
+            session: aiohttp ClientSession.
+            method: HTTP method.
+            url: Request URL.
+            request_data: Request body (bytes or form data).
+            headers: Request headers.
+            params: Query parameters.
+
+        Returns:
+            Tuple of (status_code, response_headers, response_content).
+
+        """
+        request_url, request_params = self.request_target(url, params, True)
+        request_headers = dict(headers) if headers is not None else {}
+
+        # First attempt without auth to get challenge
+        async with session.request(
+            method,
+            request_url,
+            data=request_data,
+            headers=request_headers,
+            params=request_params,
+            auth=None,
+            timeout=TIME_OUT,
+        ) as response:
+            response_content = await response.read()
+            response_headers = dict(response.headers)
+            if response.status != 401:
+                return response.status, response_headers, response_content
+
+            digest_challenge = self.extract_challenge(response.headers)
+            if digest_challenge is None:
+                return response.status, response_headers, response_content
+
+        # Build digest auth and retry
+        digest_authorization = self.build_authorization(
+            method=method,
+            request_url=request_url,
+            digest_challenge=digest_challenge,
+        )
+        if digest_authorization is None:
+            return 401, {}, b""
+
+        retry_headers = dict(request_headers)
+        retry_headers["Authorization"] = digest_authorization
+
+        async with session.request(
+            method,
+            request_url,
+            data=request_data,
+            headers=retry_headers,
+            params=request_params,
+            auth=None,
+            timeout=TIME_OUT,
+        ) as response:
+            response_content = await response.read()
+            return response.status, dict(response.headers), response_content

{axis-67 → axis-69}/axis/interfaces/api_handler.py

@@ -8,6 +8,7 @@ from collections.abc import (
     Sequence,
     ValuesView,
 )
+import enum
 from typing import TYPE_CHECKING, Generic, final
 
 from ..errors import Forbidden, PathNotFound, Unauthorized
@@ -25,6 +26,14 @@ UnsubscribeType = Callable[[], None]
 ID_FILTER_ALL = "*"
 
 
+class HandlerGroup(enum.Enum):
+    """Group handlers by initialization phase in Vapix."""
+
+    API_DISCOVERY = "api_discovery"
+    PARAM_CGI_FALLBACK = "param_cgi_fallback"
+    APPLICATION = "application"
+
+
 class SubscriptionHandler:
     """Manage subscription and notification to subscribers."""
 
@@ -75,12 +84,14 @@ class ApiHandler(SubscriptionHandler, Generic[ApiItemT]):
 
     api_id: ApiId | None = None
     default_api_version: str | None = None
+    handler_groups: tuple[HandlerGroup, ...] = ()
     skip_support_check = False
 
     def __init__(self, vapix: Vapix) -> None:
         """Initialize API items."""
         super().__init__()
         self.vapix = vapix
+        self.vapix._register_handler(self)
         self._items: dict[str, ApiItemT] = {}
         self.initialized = False
 
@@ -101,6 +112,10 @@ class ApiHandler(SubscriptionHandler, Generic[ApiItemT]):
         """Is API listed in parameters."""
         return False
 
+    def should_initialize_in_group(self, group: HandlerGroup) -> bool:
+        """Return whether handler should initialize in the given group."""
+        return True
+
     async def _api_request(self) -> dict[str, ApiItemT]:
         """Get API data method defined by subclass."""
         raise NotImplementedError
@@ -134,15 +149,41 @@ class ApiHandler(SubscriptionHandler, Generic[ApiItemT]):
         return self.initialized
 
     @property
-    def api_version(self) -> str | None:
-        """Latest API version supported."""
-        if (
-            self.api_id is not None
-            and (discovery_item := self.vapix.api_discovery.get(self.api_id))
-            is not None
-        ):
-            return discovery_item.version
-        return self.default_api_version
+    def api_version(self) -> str:
+        """Latest API version supported.
+
+        Returns the API version in this order of precedence:
+        1. Version from device discovery (dynamic, device-specific)
+        2. Handler's default_api_version (static, library-defined)
+        3. Empty string "" (for handlers without discovery support)
+
+        Note: This property always returns a string (never None). Handlers that don't
+        support API versioning (no api_id) return empty string, which is safe because
+        they don't send api_version in their requests.
+
+        Returns:
+            str: API version (e.g., "1.0", "1.1") or empty string if not available.
+
+        """
+        discovery_version = self._get_api_discovery_version()
+        if discovery_version is not None:
+            return discovery_version
+        return self.default_api_version or ""
+
+    def _get_api_discovery_version(self) -> str | None:
+        """Get API version from discovery data when available."""
+        if self.api_id is None:
+            return None
+
+        discovery_item = self.vapix.api_discovery.get(self.api_id)
+        if discovery_item is None:
+            return None
+
+        discovery_version = getattr(discovery_item, "version", None)
+        if isinstance(discovery_version, str):
+            return discovery_version
+
+        return None
 
     def items(self) -> ItemsView[str, ApiItemT]:
         """Return items."""

{axis-67 → axis-69}/axis/interfaces/applications/application_handler.py

@@ -4,13 +4,14 @@ from abc import abstractmethod
 
 from ...models.api import ApiItemT
 from ...models.applications.application import ApplicationName, ApplicationStatus
-from ..api_handler import ApiHandler
+from ..api_handler import ApiHandler, HandlerGroup
 
 
 class ApplicationHandler(ApiHandler[ApiItemT]):
     """Generic application handler."""
 
     app_name: ApplicationName
+    handler_groups = (HandlerGroup.APPLICATION,)
 
     @property
     def supported(self) -> bool:

{axis-67 → axis-69}/axis/interfaces/basic_device_info.py

@@ -14,7 +14,7 @@ from ..models.basic_device_info import (
     GetSupportedVersionsRequest,
     GetSupportedVersionsResponse,
 )
-from .api_handler import ApiHandler
+from .api_handler import ApiHandler, HandlerGroup
 
 
 class BasicDeviceInfoHandler(ApiHandler[DeviceInformation]):
@@ -22,6 +22,7 @@ class BasicDeviceInfoHandler(ApiHandler[DeviceInformation]):
 
     api_id = ApiId.BASIC_DEVICE_INFO
     default_api_version = API_VERSION
+    handler_groups = (HandlerGroup.API_DISCOVERY,)
 
     async def _api_request(self) -> dict[str, DeviceInformation]:
         """Get default data of basic device information."""
@@ -29,9 +30,8 @@ class BasicDeviceInfoHandler(ApiHandler[DeviceInformation]):
 
     async def get_all_properties(self) -> dict[str, DeviceInformation]:
         """List all properties of basic device info."""
-        discovery_item = self.vapix.api_discovery[self.api_id]
         bytes_data = await self.vapix.api_request(
-            GetAllPropertiesRequest(discovery_item.version)
+            GetAllPropertiesRequest(self.api_version)
         )
         response = GetAllPropertiesResponse.decode(bytes_data)
         return {"0": response.data}