tdl-xoa-driver 1.0.0b1__py3-none-any.whl

xoa_driver/internals/core/transporter/protocol/payload/descriptor.py

@@ -0,0 +1,119 @@
+
+from __future__ import annotations
+from abc import (
+    abstractmethod,
+    ABC
+)
+from io import BytesIO
+import struct
+
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Protocol,
+    Type,
+    TypeVar,
+)
+
+from typing_extensions import (
+    NoReturn,
+    Self,
+)
+
+from .field import FieldSpecs
+from .exceptions import FirmwareVersionError
+
+# region Types
+
+GenericType = TypeVar("GenericType")
+
+
+class SetInstance(Protocol):
+    _buffer: BytesIO
+
+
+class GetInstance(Protocol):
+    _buffer: memoryview
+    _stencil: tuple[tuple[str, int], ...]
+
+# endregion
+
+
+class FieldDescriptor(ABC, Generic[GenericType]):
+    '''
+    Descriptor representing getter and setter of the field
+    '''
+    __slots__ = ("idx", "specs", "public_name",)
+
+    def __init__(self: Self, idx: int, specs: FieldSpecs) -> None:
+        # Will be called from the Meta class
+        self.idx = idx
+        self.specs = specs
+
+    def __set_name__(self, owner, name: str) -> None:
+        self.public_name = name
+
+    @abstractmethod
+    def __set__(self: Self, instance, value: GenericType) -> None:
+        # Executed at the runtimne
+        raise NotImplementedError()
+
+    @abstractmethod
+    def __get__(self: Self, instance, cls) -> GenericType | Self:
+        # Executed at the runtimne
+        raise NotImplementedError()
+
+
+class RequestFieldDescr(FieldDescriptor[GenericType]):
+    __slots__ = ("to_xmp_context", "fmt")
+
+    def __init__(self: Self, idx: int, specs: FieldSpecs, user_type: Type[Any]) -> None:
+        super().__init__(idx, specs)
+        self.fmt = self.specs.format()
+        self.to_xmp_context: Callable[[Any], Any] = self.specs.get_context_formatter(user_type, False)
+
+    def __set__(self: Self, instance: SetInstance, value: GenericType) -> None:
+        """Transform values from Python to Bxmp and store them in to the buffer"""
+        # Executed at the runtimne
+        val_ = self.to_xmp_context(value)
+        instance._buffer.write(self.specs.pack(self.fmt, val=val_))
+
+    def __get__(self: Self, instance: SetInstance, cls) -> NoReturn | Self:
+        # Executed at the runtimne
+        if instance is None:
+            return self
+        raise RuntimeError from None
+
+
+class ResponseFieldDescr(FieldDescriptor[GenericType]):
+    __slots__ = ("to_py_context",)
+
+    def __init__(self: Self, idx: int, specs: FieldSpecs, user_type: Type[Any]) -> None:
+        super().__init__(idx, specs)
+        self.to_py_context: Callable[[Any], Any] = self.specs.get_context_formatter(user_type, True)
+
+    def __set__(self: Self, instance: GetInstance, value: GenericType) -> NoReturn:
+        # Executed at the runtimne
+        raise RuntimeError from None
+
+    def __get__(self: Self, instance: GetInstance, cls) -> GenericType | Self:
+        """Unpack values from the buffer and converting to expected type if required"""
+        # Executed at the runtimne
+        if instance is None:
+            return self
+        format_, offset_ = instance._stencil[self.idx]
+        try:
+            val_ = self.specs.unpack(
+                format=format_,
+                buffer=instance._buffer,
+                offset=offset_,
+            )
+        except struct.error:
+            raise FirmwareVersionError(
+                cmd_name=instance.__class__.__qualname__,
+                field_name=self.public_name,
+                min_version=self.specs.min_version,
+            ) from None
+        else:
+            return self.to_py_context(val_)

xoa_driver/internals/core/transporter/protocol/payload/exceptions.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+
+class XmpException(Exception):
+    ...
+
+
+class FirmwareVersionError(XmpException):
+    def __init__(self, cmd_name: str, field_name: str, min_version: int | None) -> None:
+        self.cmd_name = cmd_name
+        self.field_name = field_name
+        self.min_version = min_version
+        self.msg = f"The field: [{self.field_name}] of command {self.cmd_name} is available only from the firmware version: {self.min_version}"
+        super().__init__(self.msg)
+
+
+class FieldDeclarationError(TypeError):
+    def __init__(self, f_name: str) -> None:
+        self.msg = f"Structure Field {f_name!r} must be described with <field method>"
+        super().__init__(self.msg)

xoa_driver/internals/core/transporter/protocol/payload/field.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+from functools import lru_cache
+
+from ipaddress import (
+    IPv4Address,
+    IPv6Address,
+)
+import struct
+from typing import (
+    Any,
+    Callable,
+    List,
+    Tuple,
+    Type,
+    cast,
+    get_args,
+)
+from dataclasses import (
+    is_dataclass,
+    astuple,
+)
+from itertools import islice
+
+from .utils import flatten
+from .types import (
+    XmpType,
+    FMT_ORDER_NETWORK,
+    # Numerical
+    XmpInt,
+    XmpLong,
+    XmpByte,
+    XmpShort,
+    # Preconverted
+    XmpHex,
+    XmpIPv4Address,
+    XmpIPv6Address,
+    XmpMacAddress,
+    # Preconverted Dynamic
+    XmpStr,
+    XmpSequence,
+)
+
+
+TYPES_FIXED = (
+    XmpInt,
+    XmpLong,
+    XmpByte,
+    XmpShort,
+    XmpIPv4Address,
+    XmpIPv6Address,
+    XmpMacAddress,
+)
+TYPES_COMBI = (XmpHex,)
+TYPES_DYNAMIC = (XmpStr,)
+TYPES_COMPOSED = (XmpSequence,)
+
+# Important: The instances of the FieldSpecs will live as a class variables
+# which mean wea are not able to update its attributes during runtime.
+# Instead it suppose to provide values or methods which return an value under the instance of Pkt Body struct
+
+
+@lru_cache
+def _build_format(format_letter: str, repetition: int | None = None) -> str:
+    return f"{FMT_ORDER_NETWORK}{repetition if repetition is not None else ''}{format_letter}"
+
+
+class FieldSpecs:
+    """Executed at initialization time"""
+    __slots__ = (
+        "xmp_type",
+        "min_version",
+        "max_version",
+        "deprecated",
+        "deprecation_reason",
+    )
+
+    def __init__(
+        self,
+        xmp_type: XmpType,
+        min_version: int | None = None,
+        max_version: int | None = None,
+        deprecated: bool = False,
+        deprecation_reason: str | None = None,
+    ) -> None:
+        self.xmp_type = xmp_type
+        self.min_version = min_version
+        self.max_version = max_version
+        self.deprecated = deprecated
+        self.deprecation_reason = deprecation_reason
+
+    @property
+    def is_dynamic(self) -> bool:
+        return False
+
+    def format(self, bsize: int | None = None) -> str:
+        return _build_format(self.xmp_type.data_format, self.xmp_type.repetitions)
+
+    def calc_bsize(self, buff: memoryview | None = None, left_offset: int = 0) -> int | None:
+        if self.is_dynamic:
+            return None
+        format_ = self.format()
+        return struct.calcsize(format_)
+
+    def get_context_formatter(self, client_type: Type[Any], is_response: bool) -> Callable[[Any], Any]:
+        if not isinstance(client_type, (int, IPv4Address, IPv6Address)):
+            if is_response:
+                return lambda v: client_type(self.xmp_type.client_format(v))
+            return lambda v: self.xmp_type.server_format(client_type(v))
+        if is_response:
+            return self.xmp_type.client_format
+        return self.xmp_type.server_format
+
+    def pack(self, format: str, val: Any) -> bytes:
+        return struct.pack(format, val)
+
+    def unpack(self, format: str, buffer: memoryview, offset: int) -> Any:
+        return next(iter(struct.unpack_from(format, buffer, offset)), b"")
+
+
+class StrSpec(FieldSpecs):
+    xmp_type: XmpStr
+
+    def __init__(
+        self,
+        xmp_type: XmpStr,
+        min_version: int | None = None,
+        max_version: int | None = None,
+        deprecated: bool = False,
+        deprecation_reason: str | None = None,
+    ) -> None:
+        super().__init__(xmp_type, min_version, max_version, deprecated, deprecation_reason)
+
+    @property
+    def is_dynamic(self) -> bool:
+        return True
+
+    def format(self, bsize: int | None = None) -> str:
+        return _build_format(self.xmp_type.data_format, bsize)
+
+    def calc_bsize(self, buff: memoryview | None = None, left_offset: int = 0) -> int | None:
+        if buff is None:
+            return None
+        in_memory_slice = buff[left_offset:]
+        current_size = next(
+            (
+                idx
+                for idx, ord_n in enumerate(in_memory_slice)
+                if ord_n == 0 and not bool(idx % 4)
+            ),
+            in_memory_slice.nbytes
+        )
+        return max(self.xmp_type.min_len or 0, current_size)
+
+    def get_context_formatter(self, client_type: Type[Any], is_response: bool) -> Callable[[Any], Any]:
+        if is_response:
+            return self.xmp_type.client_format
+        return self.xmp_type.server_format
+
+    def pack(self, format: str, val: bytes) -> bytes:
+        return val
+
+
+class HexSpec(FieldSpecs):
+    xmp_type: XmpHex
+
+    def __init__(
+        self,
+        xmp_type: XmpHex,
+        min_version: int | None = None,
+        max_version: int | None = None,
+        deprecated: bool = False,
+        deprecation_reason: str | None = None,
+    ) -> None:
+        super().__init__(xmp_type, min_version, max_version, deprecated, deprecation_reason)
+
+    @property
+    def is_dynamic(self) -> bool:
+        return self.xmp_type.repetitions is None
+
+    def format(self, bsize: int | None = None) -> str:
+        return _build_format(self.xmp_type.data_format, bsize)
+
+    def calc_bsize(self, buff: memoryview | None = None, left_offset: int = 0) -> int | None:
+        if self.is_dynamic:
+            if buff is None:
+                return None
+            return len(buff[left_offset:])
+        return self.xmp_type.repetitions
+
+    def pack(self, format: str, val: Any) -> bytes:
+        return val
+
+    def unpack(self, format: str, buffer: memoryview, offset: int) -> Any:
+        return next(iter(struct.unpack_from(format, buffer, offset)), b"")
+
+
+def _prepare_client_chunks(client_type: Type[Any], xmp_types_chunks: tuple) -> Callable[[Any], List[Tuple[Any, ...]]]:
+    """Selecting the function for parsing data chunks from XMP types to Python types"""
+    def converted_dcls(val_):
+        type_paired = (zip(chunk, xmp_types_chunks) for chunk in val_)
+        return (map(lambda v: v[1].client_format(v[0]), pair) for pair in type_paired)
+
+    def converted_val(val_):
+        return map(xmp_types_chunks[0].client_format, val_)
+
+    converted = converted_dcls if is_dataclass(client_type) else converted_val
+    return lambda val: [client_type(*vals) for vals in converted(val)]
+
+
+def _prepare_serv_chunks(client_type: Type[Any], xmp_types_chunks: tuple) -> Callable[[Any], List[Tuple[Any, ...]]]:
+    """Selecting the function for parsing data chunks from Python types to XMP types"""
+    if is_dataclass(client_type):
+        return lambda val: [
+            tuple(map(lambda v: v[1].server_format(v[0]), zip(chunk, xmp_types_chunks)))
+            for chunk in map(astuple, val)
+        ]
+    return lambda val: list(map(xmp_types_chunks[0].server_format, val))
+
+
+class SequenceSpec(FieldSpecs):
+    xmp_type: XmpSequence
+
+    def __init__(
+        self,
+        xmp_type: XmpSequence,
+        min_version: int | None = None,
+        max_version: int | None = None,
+        deprecated: bool = False,
+        deprecation_reason: str | None = None,
+    ) -> None:
+        super().__init__(xmp_type, min_version, max_version, deprecated, deprecation_reason)
+
+    @property
+    def is_dynamic(self) -> bool:
+        return self.xmp_type.length is None
+
+    def calc_bsize(self, buff: memoryview | None = None, left_offset: int = 0) -> int | None:
+        format_ = _build_format(self.xmp_type.data_format)
+        return struct.calcsize(format_) * (self.xmp_type.length or 1)
+
+    def get_context_formatter(self, client_type: Type[Any], is_response: bool) -> Callable[[Any], List[Tuple[Any, ...]]]:
+        try:
+            client_type = get_args(client_type)[0]
+        except IndexError as e:
+            raise e
+        if is_response:
+            return _prepare_client_chunks(
+                client_type=client_type,
+                xmp_types_chunks=self.xmp_type.types_chunk
+            )
+        return _prepare_serv_chunks(
+            client_type=client_type,
+            xmp_types_chunks=self.xmp_type.types_chunk
+        )
+
+    def pack(self, format: str, val: list[Any]) -> bytes:
+        length = self.xmp_type.length or len(val)
+        pack_fmt = f"{FMT_ORDER_NETWORK}{self.xmp_type.data_format * length}"
+        return struct.pack(pack_fmt, *flatten(val))
+
+    def unpack(self, format: str, buffer: memoryview, offset: int) -> list[Any]:
+        buff_ = buffer[offset:]
+        limit = len(buff_) % cast(int, self.calc_bsize())
+        buff_ = buff_[:-limit] if limit else buff_
+        raw_sequence = islice(struct.iter_unpack(format, buff_), self.xmp_type.length)
+        return list(raw_sequence)
+
+
+def field(
+    xmp_type: XmpType,
+    *,
+    min_version: int | None = None,
+    max_version: int | None = None,
+    deprecated: bool = False,
+    deprecation_reason: str | None = None
+) -> Any:
+    """Method used for describe field parameters of an XMP packet structure"""
+
+    if isinstance(xmp_type, TYPES_COMPOSED):
+        specs_type = SequenceSpec
+    elif isinstance(xmp_type, TYPES_DYNAMIC):
+        specs_type = StrSpec
+    elif isinstance(xmp_type, TYPES_FIXED):
+        specs_type = FieldSpecs
+    elif isinstance(xmp_type, TYPES_COMBI):
+        specs_type = HexSpec
+    else:
+        return None
+
+    return specs_type(
+        xmp_type=xmp_type,  # type: ignore[The type of xmp_type is already validated]
+        min_version=min_version,
+        max_version=max_version,
+        deprecated=deprecated,
+        deprecation_reason=deprecation_reason,
+    )

xoa_driver/internals/core/transporter/protocol/payload/types.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+from ipaddress import (
+    IPv4Address,
+    IPv6Address,
+)
+from typing import (
+    Any,
+    NewType,
+    Protocol,
+    TypeVar,
+    cast,
+)
+
+FMT_ORDER_NETWORK = '!'
+FMT_BYTES_STRING = 's'
+FMT_SIG_CHAR = 'b'
+FMT_U_SIG_CHAR = 'B'
+FMT_LONG = 'q'
+FMT_U_LONG = 'Q'
+FMT_INT = 'i'
+FMT_U_INT = 'I'
+FMT_SHORT = 'h'
+FMT_U_SHORT = 'H'
+
+# region Base Type
+
+GenericType = TypeVar("GenericType", covariant=True)
+
+Hex = NewType("Hex", str)
+"""Type alias of string for indicate as string suppose to contain only valid HEX symbols"""
+
+
+class XmpType(Protocol[GenericType]):
+    __slots__ = ("data_format", "repetitions",)
+
+    repetitions: int | None
+    data_format: str
+
+    def client_format(self, val: Any) -> Any:
+        return val
+
+    def server_format(self, val: Any) -> Any:
+        return val
+
+# endregion
+
+
+# region Xmp Types
+
+class XmpByte(XmpType[int]):
+    """Description class of XMP Byte type representation"""
+
+    def __init__(self, *, signed: bool = False) -> None:
+        self.data_format = FMT_SIG_CHAR if signed else FMT_U_SIG_CHAR
+        self.repetitions = None
+
+
+class XmpInt(XmpType[int]):
+    """Description class of XMP Int type representation"""
+
+    def __init__(self, *, signed: bool = True, climb: tuple[int, int] | None = None) -> None:
+        self.data_format = FMT_INT if signed else FMT_U_INT
+        self.repetitions = None
+
+
+class XmpShort(XmpType[int]):
+    """Description class of XMP Short type representation"""
+
+    def __init__(self, *, signed: bool = True) -> None:
+        self.data_format = FMT_SHORT if signed else FMT_U_SHORT
+        self.repetitions = None
+
+
+class XmpLong(XmpType[int]):
+    """Description class of XMP Long type representation"""
+
+    def __init__(self, *, signed: bool = True) -> None:
+        self.data_format = FMT_LONG if signed else FMT_U_LONG
+        self.repetitions = None
+
+
+class XmpHex(XmpType[Hex]):
+    """Description class of XMP Hex type representation"""
+
+    def __init__(self, *, size: int | None = None) -> None:
+        """
+        if size is None means Hex string are not having a limit
+        otherwise will use fixed size
+        """
+        self.data_format = FMT_BYTES_STRING
+        self.repetitions = size
+
+    def client_format(self, val: bytes) -> Hex:
+        return Hex(val.hex())
+
+    def server_format(self, val: Hex) -> bytes:
+        if self.repetitions is not None:
+            size_ = self.repetitions * 2
+            if len(val) > size_:
+                raise ValueError(f"Expected Hex of size not bigger then {self.repetitions} bytes")
+            val = Hex(cast(str, val).zfill(size_))
+        return bytes.fromhex(val)
+
+
+class XmpIPv6Address(XmpType[IPv6Address]):
+    """Description class of XMP IPv6Address type representation"""
+
+    def __init__(self) -> None:
+        self.data_format = FMT_BYTES_STRING
+        self.repetitions = 16
+
+    def client_format(self, val: bytes) -> IPv6Address:
+        return IPv6Address(val)
+
+    def server_format(self, val: IPv6Address) -> bytes:
+        return val.packed
+
+
+class XmpIPv4Address(XmpType[IPv4Address]):
+    """Description class of XMP IPv4Address type representation"""
+
+    def __init__(self) -> None:
+        self.data_format = FMT_BYTES_STRING
+        self.repetitions = 4
+
+    def client_format(self, val: bytes) -> IPv4Address:
+        return IPv4Address(val)
+
+    def server_format(self, val: IPv4Address) -> bytes:
+        return val.packed
+
+
+class XmpMacAddress(XmpHex):
+    """Description class of XMP MacAddress type representation"""
+
+    def __init__(self) -> None:
+        self.data_format = FMT_BYTES_STRING
+        self.repetitions = 6
+
+
+class XmpStr(XmpType[str]):
+    """Description class of XMP String type representation"""
+
+    __slots__ = ("min_len",)
+
+    def __init__(self, min_len: int | None = None) -> None:
+        self.data_format = FMT_BYTES_STRING
+        self.repetitions = None
+        self.min_len = min_len
+
+    def client_format(self, val: bytes) -> str:
+        return val.partition(b'\0')[0].decode()
+
+    def server_format(self, val: str) -> bytes:
+        return val.encode()
+
+
+class XmpSequence(XmpType[tuple]):
+    """Description class of XMP Sequence type representation"""
+
+    __slots__ = ("types_chunk", "length",)
+
+    def __init__(
+        self,
+        types_chunk: list[XmpByte | XmpInt | XmpShort | XmpLong | XmpHex | XmpIPv4Address | XmpIPv6Address | XmpMacAddress],
+        length: int | None = None
+    ) -> None:
+        self.types_chunk = tuple(types_chunk)
+        self.length = length
+        self.repetitions = None
+        self.data_format = "".join(f"{t.repetitions or ''}{t.data_format}" for t in self.types_chunk)
+
+# endregion

xoa_driver/internals/core/transporter/protocol/payload/utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import sys
+from functools import partial
+from typing import (
+    Dict,
+    ForwardRef,
+    Iterable,
+    Type,
+    Any,
+    Optional,
+    _eval_type,  # type: ignore
+)
+
+
+def resolve_annotations(raw_annotations: dict[str, Type[Any]], module_name: str | None) -> dict[str, Type[Any]]:
+    """
+    Partially taken from typing.get_type_hints.
+
+    Resolve string or ForwardRef annotations into type objects if possible.
+    """
+    base_globals: Optional[Dict[str, Any]] = None
+    if module_name:
+        if module := sys.modules.get(module_name, None):
+            base_globals = module.__dict__
+
+    validate_version = (3, 10) > sys.version_info >= (3, 9, 8) or sys.version_info >= (3, 10, 1)
+    forward_ref = (
+        partial(ForwardRef, is_argument=False, is_class=True)
+        if validate_version else
+        partial(ForwardRef, is_argument=False)
+    )
+
+    annotations = {}
+    for name, value in raw_annotations.items():
+        val_ = forward_ref(value) if isinstance(value, str) else value
+        try:
+            val_ = _eval_type(val_, base_globals, None)
+        except NameError:
+            pass
+        except TypeError:
+            if sys.version_info < (3, 9):
+                version_str = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+                raise TypeError(f"The Python version you using is: {version_str} and it's supports type hints only from <typing> module") from None
+        annotations[name] = val_
+    return annotations
+
+
+def flatten(items, ignore_types=(str, bytes)):
+    for x in items:
+        if isinstance(x, Iterable) and not isinstance(x, ignore_types):
+            yield from flatten(x)
+        else:
+            yield x