matter-python-client 0.4.1__py3-none-any.whl

matter_server/common/errors.py

@@ -0,0 +1,94 @@
+"""Matter Exceptions."""
+
+from __future__ import annotations
+
+# mapping from error_code to Exception class
+ERROR_MAP: dict[int, type] = {}
+
+
+class MatterError(Exception):
+    """Generic Matter exception."""
+
+    error_code = 0
+
+    def __init_subclass__(cls, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
+        """Register a subclass."""
+        super().__init_subclass__(*args, **kwargs)
+        ERROR_MAP[cls.error_code] = cls
+
+
+class UnknownError(MatterError):
+    """Error raised when there an unknown/invalid command is requested."""
+
+    error_code = 0  # to map all generic errors
+
+
+class NodeCommissionFailed(MatterError):
+    """Error raised when interview of a device failed."""
+
+    error_code = 1
+
+
+class NodeInterviewFailed(MatterError):
+    """Error raised when interview of a device failed."""
+
+    error_code = 2
+
+
+class NodeNotReady(MatterError):
+    """Error raised when performing action on node that has not been fully added."""
+
+    error_code = 3
+
+
+class NodeNotResolving(MatterError):
+    """Error raised when no CASE session could be established."""
+
+    error_code = 4
+
+
+class NodeNotExists(MatterError):
+    """Error raised when performing action on node that does not exist."""
+
+    error_code = 5
+
+
+class VersionMismatch(MatterError):
+    """Issue raised when SDK version mismatches."""
+
+    error_code = 6
+
+
+class SDKStackError(MatterError):
+    """Generic SDK stack error."""
+
+    error_code = 7
+
+
+class InvalidArguments(MatterError):
+    """Error raised when there are invalid arguments provided for a command."""
+
+    error_code = 8
+
+
+class InvalidCommand(MatterError):
+    """Error raised when there an unknown/invalid command is requested."""
+
+    error_code = 9
+
+
+class UpdateCheckError(MatterError):
+    """Error raised when there was an error during searching for updates."""
+
+    error_code = 10
+
+
+class UpdateError(MatterError):
+    """Error raised when there was an error during applying updates."""
+
+    error_code = 11
+
+
+def exception_from_error_code(error_code: int) -> type[MatterError]:
+    """Return correct Exception class from error_code."""
+    return ERROR_MAP.get(error_code, MatterError)

matter_server/common/helpers/api.py

@@ -0,0 +1,70 @@
+"""Several helpers for the WebSockets API."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from dataclasses import MISSING, dataclass
+import inspect
+from typing import Any, TypeVar, get_type_hints
+
+from matter_server.common.helpers.util import parse_value
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+@dataclass
+class APICommandHandler:
+    """Model for an API command handler."""
+
+    command: str
+    signature: inspect.Signature
+    type_hints: dict[str, Any]
+    target: Callable[..., Coroutine[Any, Any, Any]]
+
+    @classmethod
+    def parse(
+        cls, command: str, func: Callable[..., Coroutine[Any, Any, Any]]
+    ) -> "APICommandHandler":
+        """Parse APICommandHandler by providing a function."""
+        return APICommandHandler(
+            command=command,
+            signature=inspect.signature(func),
+            type_hints=get_type_hints(func),
+            target=func,
+        )
+
+
+def api_command(command: str) -> Callable[[_F], _F]:
+    """Decorate a function as API route/command."""
+
+    def decorate(func: _F) -> _F:
+        func.api_cmd = command  # type: ignore[attr-defined]
+        return func
+
+    return decorate
+
+
+def parse_arguments(
+    func_sig: inspect.Signature,
+    func_types: dict[str, Any],
+    args: dict | None = None,
+    strict: bool = False,
+) -> dict[str, Any]:
+    """Parse (and convert) incoming arguments to correct types."""
+    if args is None:
+        args = {}
+    final_args = {}
+    # ignore extra args if not strict
+    if strict:
+        for key, value in args.items():
+            if key not in func_sig.parameters:
+                raise KeyError(f"Invalid parameter: '{key}'")
+    # parse arguments to correct type
+    for name, param in func_sig.parameters.items():
+        value = args.get(name)
+        if param.default is inspect.Parameter.empty:
+            default = MISSING
+        else:
+            default = param.default
+        final_args[name] = parse_value(name, value, func_types[name], default)
+    return final_args

matter_server/common/helpers/json.py

@@ -0,0 +1,48 @@
+"""Helpers to work with (de)serializing of json."""
+
+from base64 import b64encode
+from typing import Any
+
+from chip.clusters.Types import Nullable
+from chip.tlv import float32, uint
+import orjson
+
+JSON_ENCODE_EXCEPTIONS = (TypeError, ValueError)
+JSON_DECODE_EXCEPTIONS = (orjson.JSONDecodeError,)
+
+
+def json_encoder_default(obj: Any) -> Any:
+    """Convert Special objects.
+
+    Hand other objects to the original method.
+    """
+    # pylint: disable=too-many-return-statements
+    if getattr(obj, "do_not_serialize", None):
+        return None
+    if isinstance(obj, (set, tuple)):
+        return list(obj)
+    if isinstance(obj, float32):
+        return float(obj)
+    if isinstance(obj, uint):
+        return int(obj)
+    if isinstance(obj, Nullable):
+        return None
+    if isinstance(obj, bytes):
+        return b64encode(obj).decode("utf-8")
+    if isinstance(obj, Exception):
+        return str(obj)
+    if type(obj) is type:  # pylint: disable=unidiomatic-typecheck
+        return f"{obj.__module__}.{obj.__qualname__}"
+    raise TypeError
+
+
+def json_dumps(data: Any) -> str:
+    """Dump json string."""
+    return orjson.dumps(
+        data,
+        option=orjson.OPT_NON_STR_KEYS | orjson.OPT_INDENT_2,
+        default=json_encoder_default,
+    ).decode("utf-8")
+
+
+json_loads = orjson.loads

matter_server/common/helpers/util.py

@@ -0,0 +1,359 @@
+"""Utils for Matter server (and client)."""
+
+from __future__ import annotations
+
+import base64
+from base64 import b64decode
+import binascii
+from dataclasses import MISSING, asdict, fields, is_dataclass
+from datetime import datetime
+from enum import Enum
+from functools import cache
+from importlib.metadata import PackageNotFoundError, version as pkg_version
+import logging
+import platform
+import socket
+from types import NoneType, UnionType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from chip.clusters.Types import Nullable, NullValue
+from chip.tlv import float32, uint
+
+if TYPE_CHECKING:
+    from _typeshed import DataclassInstance
+    from chip.clusters.ClusterObjects import (
+        ClusterAttributeDescriptor,
+        ClusterObjectDescriptor,
+    )
+
+    _T = TypeVar("_T", bound=DataclassInstance)
+
+CHIP_CLUSTERS_PKG_NAME = "home-assistant-chip-clusters"
+CHIP_CORE_PKG_NAME = "home-assistant-chip-core"
+
+cached_fields = cache(fields)
+cached_type_hints = cache(get_type_hints)
+
+
+def create_attribute_path_from_attribute(
+    endpoint_id: int, attribute: type[ClusterAttributeDescriptor]
+) -> str:
+    """Create path/identifier for an Attribute."""
+    return create_attribute_path(
+        endpoint_id, attribute.cluster_id, attribute.attribute_id
+    )
+
+
+def create_attribute_path(
+    endpoint: int | None, cluster_id: int | None, attribute_id: int | None
+) -> str:
+    """
+    Create path/identifier string for an Attribute.
+
+    Returns same output as `Attribute.AttributePath` string representation.
+    endpoint/cluster_id/attribute_id
+    """
+    return f"{endpoint}/{cluster_id}/{attribute_id}"
+
+
+def parse_attribute_path(
+    attribute_path: str,
+) -> tuple[int | None, int | None, int | None]:
+    """Parse AttributePath string into tuple of endpoint_id, cluster_id, attribute_id."""
+    endpoint_id_str, cluster_id_str, attribute_id_str = attribute_path.split("/")
+    endpoint_id = int(endpoint_id_str) if endpoint_id_str.isnumeric() else None
+    cluster_id = int(cluster_id_str) if cluster_id_str.isnumeric() else None
+    attribute_id = int(attribute_id_str) if attribute_id_str.isnumeric() else None
+    return (endpoint_id, cluster_id, attribute_id)
+
+
+def dataclass_to_dict(obj_in: DataclassInstance) -> dict:
+    """Convert dataclass instance to dict."""
+
+    return asdict(
+        obj_in,
+        dict_factory=lambda x: {
+            # ensure the dict key is a string
+            str(k): v
+            for (k, v) in x
+        },
+    )
+
+
+def parse_utc_timestamp(datetime_string: str) -> datetime:
+    """Parse datetime from string."""
+    return datetime.fromisoformat(datetime_string)
+
+
+def _get_descriptor_key(descriptor: ClusterObjectDescriptor, key: str | int) -> str:
+    """Return correct Cluster attribute key for a tag id."""
+    if (isinstance(key, str) and key.isnumeric()) or isinstance(key, int):
+        if field := descriptor.GetFieldByTag(int(key)):
+            return cast(str, field.Label)
+    return cast(str, key)
+
+
+def parse_value(
+    name: str,
+    value: Any,
+    value_type: Any,
+    default: Any = MISSING,
+    allow_none: bool = False,
+    allow_sdk_types: bool = False,
+) -> Any:
+    """
+    Try to parse a value from raw (json) data and type annotations.
+
+    If allow_sdk_types is False, any SDK specific custom data types will be converted.
+    """
+    # pylint: disable=too-many-return-statements,too-many-branches
+
+    if isinstance(value_type, str):
+        # this shouldn't happen, but just in case
+        value_type = get_type_hints(value_type, globals(), locals())
+
+    # handle value is None/missing but a default value is set
+    if value is None and not isinstance(default, type(MISSING)):
+        return default
+    # handle value is None and sdk type is Nullable
+    if value is None and value_type is Nullable:
+        return Nullable() if allow_sdk_types else None
+    # handle value is None (but that is allowed according to the annotations)
+    if value is None and value_type is NoneType:
+        return None
+
+    if isinstance(value, dict):
+        if descriptor := getattr(value_type, "descriptor", None):
+            # handle matter TLV dicts where the keys are just tag identifiers
+            value = {_get_descriptor_key(descriptor, x): y for x, y in value.items()}
+        # handle a parse error in the sdk which is returned as:
+        # {'TLVValue': None, 'Reason': None} or {'TLVValue': None}
+        if value.get("TLVValue", MISSING) is None:
+            if value_type in (None, Nullable, Any):
+                return None
+            value = None
+
+    if is_dataclass(value_type) and isinstance(value, dict):
+        return dataclass_from_dict(value_type, value)  # type: ignore[arg-type]
+    # get origin value type and inspect one-by-one
+    origin: Any = get_origin(value_type)
+    if origin in (list, tuple, set) and isinstance(value, (list, tuple, set)):
+        return origin(
+            parse_value(name, subvalue, get_args(value_type)[0])
+            for subvalue in value
+            if subvalue is not None
+        )
+    # handle dictionary where we should inspect all values
+    if origin is dict:
+        subkey_type = get_args(value_type)[0]
+        subvalue_type = get_args(value_type)[1]
+        return {
+            parse_value(subkey, subkey, subkey_type): parse_value(
+                f"{subkey}.value",
+                subvalue,
+                subvalue_type,
+                allow_none=allow_none,
+                allow_sdk_types=allow_sdk_types,
+            )
+            for subkey, subvalue in value.items()
+        }
+    # handle Union type
+    if origin is Union or origin is UnionType:
+        sub_value_types = get_args(value_type)
+        # return early if value is None and None or Nullable allowed
+        if value is None and Nullable in sub_value_types and allow_sdk_types:
+            return NullValue
+        if value is None and NoneType in sub_value_types:
+            return None
+        # try all possible types
+        for sub_arg_type in sub_value_types:
+            # try them all until one succeeds
+            try:
+                return parse_value(
+                    name,
+                    value,
+                    sub_arg_type,
+                    allow_none=allow_none,
+                    allow_sdk_types=allow_sdk_types,
+                )
+            except (KeyError, TypeError, ValueError):
+                pass
+        # if we get to this point, all possibilities failed
+        # find out if we should raise or log this
+        err = (
+            f"Value {value} of type {type(value)} is invalid for {name}, "
+            f"expected value of type {value_type}"
+        )
+        if NoneType not in sub_value_types:
+            # raise exception, we have no idea how to handle this value
+            raise TypeError(err)
+        # failed to parse the (sub) value but None allowed, log only
+        logging.getLogger(__name__).warning(err)
+        return None
+    if origin is type:
+        return get_type_hints(value, globals(), locals())
+    # handle Any as value type (which is basically unprocessable)
+    if value_type is Any:
+        return value
+    # handle value is None (but that is allowed)
+    if value is None and allow_none:
+        return None
+    # raise if value is None and the value is required according to annotations
+    if value is None:
+        raise KeyError(f"`{name}` of type `{value_type}` is required.")
+
+    try:
+        if issubclass(value_type, Enum):
+            # handle enums from the SDK that have a value that does not exist in the enum (sigh)
+            # pylint: disable=protected-access
+            if value not in value_type._value2member_map_:
+                # we do not want to crash so we return the raw value
+                return value
+            return value_type(value)
+        if issubclass(value_type, datetime):
+            return parse_utc_timestamp(value)
+    except TypeError:
+        # happens if value_type is not a class
+        pass
+
+    # common type conversions (e.g. int as string)
+    if value_type is float and isinstance(value, int):
+        return float(value)
+    if value_type is int and isinstance(value, str) and value.isnumeric():
+        return int(value)
+    # handle bytes values (sent over the wire as base64 encoded strings)
+    if value_type is bytes and isinstance(value, str):
+        try:
+            return b64decode(value.encode("utf-8"))
+        except binascii.Error:
+            # unfortunately sometimes the data is malformed
+            # as it is not super important we ignore it (for now)
+            return b""
+
+    # handle NOCStruct.noc which is typed/specified as bytes but parsed
+    # as integer in the tlv parser somehow.
+    # https://github.com/home-assistant/core/issues/113279
+    # https://github.com/home-assistant/core/issues/116304
+    if name == "NOCStruct.noc" and not isinstance(value, bytes):
+        return b""
+
+    # Matter SDK specific types
+    if value_type is uint and (
+        isinstance(value, int) or (isinstance(value, str) and value.isnumeric())
+    ):
+        return uint(value) if allow_sdk_types else int(value)
+    if value_type is float32 and (
+        isinstance(value, (float, int))
+        or (isinstance(value, str) and value.isnumeric())
+    ):
+        return float32(value) if allow_sdk_types else float(value)
+
+    # If we reach this point, we could not match the value with the type and we raise
+    if not isinstance(value, value_type):
+        raise TypeError(
+            f"Value {value} of type {type(value)} is invalid for {name}, "
+            f"expected value of type {value_type}"
+        )
+    return value
+
+
+def dataclass_from_dict(
+    cls: type[_T],
+    dict_obj: dict,
+    strict: bool = False,
+    allow_sdk_types: bool = False,
+) -> _T:
+    """
+    Create (instance of) a dataclass by providing a dict with values.
+
+    Including support for nested structures and common type conversions.
+    If strict mode enabled, any additional keys in the provided dict will result in a KeyError.
+    """
+    dc_fields = cached_fields(cls)
+    if strict:
+        extra_keys = dict_obj.keys() - {f.name for f in dc_fields}
+        if extra_keys:
+            raise KeyError(
+                f"Extra key(s) {','.join(extra_keys)} not allowed for {str(cls)}"
+            )
+    type_hints = cached_type_hints(cls)
+    return cls(
+        **{
+            field.name: parse_value(
+                f"{cls.__name__}.{field.name}",
+                dict_obj.get(field.name),
+                type_hints[field.name],
+                field.default,
+                allow_none=not strict,
+                allow_sdk_types=allow_sdk_types,
+            )
+            for field in dc_fields
+            if field.init
+        }
+    )
+
+
+def package_version(pkg_name: str) -> str:
+    """
+    Return the version of an installed package.
+
+    Will return `0.0.0` if the package is not found.
+    """
+    try:
+        installed_version = pkg_version(pkg_name)
+        if installed_version is None:
+            return "0.0.0"  # type: ignore[unreachable]
+        return installed_version
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+@cache
+def chip_clusters_version() -> str:
+    """Return the version of the CHIP SDK (clusters package) that is installed."""
+    return package_version(CHIP_CLUSTERS_PKG_NAME)
+
+
+@cache
+def chip_core_version() -> str:
+    """Return the version of the CHIP SDK (core package) that is installed."""
+    if platform.system() == "Darwin":
+        # TODO: Fix this once we can install our own wheels on macos.
+        return chip_clusters_version()
+    return package_version(CHIP_CORE_PKG_NAME)
+
+
+def convert_hex_string(hex_str: str | bytes) -> str:
+    """Convert (Base64 encoded) byte array received from the sdk to a regular (unicode) string."""
+    if isinstance(hex_str, str):
+        # note that the bytes string can be optionally base64 encoded
+        # when we send it back and forth over our api
+        hex_str = base64.b64decode(hex_str)
+
+    return "".join(f"{byte:02x}" for byte in hex_str)
+
+
+def convert_mac_address(hex_mac: str | bytes) -> str:
+    """Convert (Base64 encoded) byte array MAC received from the sdk to a regular mac-address."""
+    if isinstance(hex_mac, str):
+        # note that the bytes string can be optionally base64 encoded
+        hex_mac = base64.b64decode(hex_mac)
+
+    return ":".join("{:02x}".format(byte) for byte in hex_mac)  # pylint: disable=C0209
+
+
+def convert_ip_address(hex_ip: str | bytes, ipv6: bool = False) -> str:
+    """Convert (Base64 encoded) byte array IP received from the Matter SDK to a regular IP."""
+    if isinstance(hex_ip, str):
+        # note that the bytes string can be optionally base64 encoded
+        hex_ip = base64.b64decode(hex_ip)
+    return socket.inet_ntop(socket.AF_INET6 if ipv6 else socket.AF_INET, hex_ip)