MTPPy2.0 0.1.5__py3-none-any.whl

mtppy/utils/data_item.py

@@ -0,0 +1,446 @@
+"""DataItem and DataItemCollection, core API for data management and notification."""
+
+from __future__ import annotations
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+
+import copy
+from collections.abc import (
+    Callable,
+    Iterator,
+    KeysView,
+    MutableMapping,
+)
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import utils.type_conversion as tc
+    from mtppy.part5.communication_object import CommunicationObject
+
+from mtppy.part3.definitions.mtp_access import MTPAccess
+from mtppy.part5.definitions.w3c_xml_data_types import W3cXmlDataTypes
+from mtppy.utils.logging import logger
+
+
+class DataItem:
+    """Represent a scalar typed value hosted by a data-item collection.
+
+    A DataItem validates and stores its value according to a W3C XML data
+    type. It can notify an internal callback and any number of external
+    communication observers when its value is written.
+
+    The class is hosted by a
+    [DataItemCollection][mtppy.utils.data_item.DataItemCollection],
+    the base class for
+    [DataAssembly][mtppy.part3.data_assembly_set.data_assembly.DataAssembly].
+
+    A DataItem is associated with an Attribute of a DataAssembly definition
+    within MTP 2.0.
+
+    Attributes:
+        name: DataItem name.
+        w3c_xml_data_type: DataItem value type.
+        access: DataItem access mode.
+        init_value: Initial, type-corrected value.
+        description: Human-readable description.
+        ext_wrt_cb: Callback invoked for external writes.
+        int_wrt_cb: Callback invoked for internal writes.
+        communication_objects: External communication observers notified on
+            value writes.
+        comm_obj: Backwards-compatible alias for the first communication
+            observer.
+        _value: Current type-corrected value.
+        _is_notifying: Whether an internal notification is in progress.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        w3c_xml_data_type: W3cXmlDataTypes,
+        access: MTPAccess,
+        init_value: tc.ANY_TYPE | None = 0,
+        description: str = "",
+        external_write_cb: Callable[[tc.ANY_TYPE], None] | None = None,
+        internal_write_cb: Callable[[tc.ANY_TYPE], None] | None = None,
+    ) -> None:
+        """Initialize a DataItem.
+
+        Args:
+            name: Name of the data item.
+            w3c_xml_data_type: W3C XML type used to convert assigned values.
+            access: Access mode for the data item.
+            init_value: Initial value. ``None`` is treated as ``0``.
+            description: Human-readable description.
+            external_write_cb: Callback for external writes received through
+                the data item.
+            internal_write_cb: Callback for internal writes to the data item.
+
+        Raises:
+            TypeError: If ``w3c_xml_data_type`` or ``access`` is not the
+                expected enumeration type.
+        """
+        self.name: str = name
+        # Type checking
+        if not isinstance(
+            w3c_xml_data_type,
+            W3cXmlDataTypes,
+        ):  # pyright: ignore[reportUnnecessaryIsInstance]
+            exc_msg = f"data type {w3c_xml_data_type} not supported"
+            raise TypeError(exc_msg)
+        self.w3c_xml_data_type: W3cXmlDataTypes = w3c_xml_data_type
+        if not isinstance(
+            access,
+            MTPAccess,
+        ):  # pyright: ignore[reportUnnecessaryIsInstance]
+            exc_msg = f"access type {access} not supported"
+            raise TypeError(exc_msg)
+        self.access: MTPAccess = access
+        self._is_notifying: bool = False
+
+        if init_value is None:
+            init_value = 0
+
+        self.description: str = description
+        type_casted_value = self._correct_type(init_value)
+        self.init_value: tc.ANY_TYPE = type_casted_value
+        self._value: tc.ANY_TYPE = type_casted_value
+        self.communication_objects: list[CommunicationObject] = []
+        self.ext_wrt_cb: Callable[[tc.ANY_TYPE], None] | None = external_write_cb
+        self.int_wrt_cb: Callable[[tc.ANY_TYPE], None] | None = internal_write_cb
+
+    def get_value(self) -> tc.ANY_TYPE:
+        """Return the current value of the DataItem.
+
+        Returns:
+            The current value, already converted to the DataItem's
+            pythonic ``w3c_xml_data_type``
+        """
+        return self._value
+
+    def get_value_str(self) -> str:
+        """Return a human-readable string representation of the DataItem.
+
+        Returns:
+            A string of the form ``"<name>=<value>"``, e.g. ``"WQC=128"``.
+        """
+        return f"{self.name}={self._value}"
+
+    def _notify_local_subscribers(self, value: tc.ANY_TYPE) -> None:
+        """Notify the internal subscriber and  update the stored value.
+
+        Recursive writes made by the internal callback update the value
+        directly while the outer notification remains active.
+
+        Args:
+            value: Type-corrected value to publish internally.
+        """
+        if self._is_notifying:  # Our callbacks did all the checks, now finally write
+            self._value = value
+            return
+        self._is_notifying = True
+        try:
+            if self.int_wrt_cb is not None:
+                logger.mtp(f"{self.name}:={value} => {self.int_wrt_cb.__name__}")
+                self.int_wrt_cb(value)
+            else:
+                self._value = value
+        finally:
+            self._is_notifying = False
+
+    def _notify_external_subscribers(self) -> None:
+        """Notify each attached external communication observer."""
+        if not self.communication_objects:
+            logger.opcua(f"{self.name}:={self._value} => no communication object")
+            return
+
+        for communication_object in self.communication_objects:
+            communication_object.write_value_callback(self._value)
+            logger.opcua(f"{self.name}:={self._value} => notified")
+
+    @property
+    def comm_obj(self) -> CommunicationObject | None:
+        """Return the first communication object, if one is attached.
+
+        Returns:
+            The first attached observer, or ``None`` when no observer exists.
+        """
+        return self.communication_objects[0] if self.communication_objects else None
+
+    @comm_obj.setter
+    def comm_obj(self, communication_object: CommunicationObject | None) -> None:
+        """Replace all observers with one communication object.
+
+        Args:
+            communication_object: Observer to retain, or ``None`` to remove
+                all observers.
+        """
+        self.communication_objects = (
+            [] if communication_object is None else [communication_object]
+        )
+
+    def set_value(self, value: tc.ANY_TYPE) -> None:
+        """Set the value and notify internal and external subscribers.
+
+        Args:
+            value: Value to convert, store, and publish.
+        """
+        corrected_value = self._correct_type(value)
+        if self.get_value() != corrected_value:
+            self._notify_local_subscribers(corrected_value)
+        # do we really always want to try to notify external subscribers? No,
+        # we shall wait until all the internal updates are finished
+        if not self._is_notifying:
+            self._notify_external_subscribers()
+
+        logger.debug(f"New value for {self.name} is {self._value}")
+
+    def _correct_type(self, value: tc.ANY_TYPE) -> tc.ANY_TYPE:
+        """Convert a value to the DataItem's configured type.
+
+        Args:
+            value: Value.
+
+        Returns:
+            Converted value, or ``int`` when conversion fails.
+        """
+        conversion_function = self.w3c_xml_data_type.converse
+        if conversion_function is not None:
+            try:
+                return conversion_function(value)
+            except (ValueError, TypeError) as e:
+                logger.warning(
+                    f"{self.name} - converting '{value}' to "
+                    f"type {self.w3c_xml_data_type}: {e}",
+                )
+                # tbd: understand this - it magically works - why?
+                return int
+        else:
+            exc_msg = f"data type {self.w3c_xml_data_type} not supported"
+            raise TypeError(exc_msg)
+
+    def attach_communication_object(
+        self,
+        communication_object: CommunicationObject,
+    ) -> None:
+        """Attach an external communication observer.
+
+        Duplicate observers are ignored. Observers are notified in attachment
+        order whenever the DataItem is written.
+
+        Args:
+            communication_object: Communication object that exposes this
+                DataItem to an external client.
+        """
+        if communication_object not in self.communication_objects:
+            self.communication_objects.append(communication_object)
+
+
+class DataItemCollection(MutableMapping[str, DataItem]):
+    """Key-immutable, dict-like container of [DataItem][mtppy.utils.data_item.DataItem]
+    instances.
+
+    The collection is populated at construction time from the ClassVar
+    ``CLASS_DATA_ITEMS`` mapping declared statically on the owning class
+    (and all of its bases in MRO order). Each entry is deep-copied so that two
+    collections derived from the same class do not share DataItems.
+
+    The collection supports both mapping-style (``da["WQC"]``) and
+    attribute-style (``da.WQC``) access to the current *value* of
+    a DataItem.
+
+    Both the dict-keys and the attributes of the class are immutable, that is
+    a lhs ``da["NEW"]`` does not add a new entry with key "NDW" to the
+    DataItemCollection. The same is true for lhs da.new or self.new - this
+    hardens the class against typos.
+
+    Note:
+        In cases where the SNAKE_CASE string holding constant is not distinguishable
+        from the CamelCase PNO MTP 2.0 name, our best practice is to have the constant
+        name end with an _, e.g. WQC_, P_, PV_
+
+    Attention:
+        The collection is key-immutable and attribute-immutable. Setting an unknown
+        key or attribute raises [KeyError][keyerror], while reading an unknown
+        attribute raises [AttributeError][attributeerror]. Consequently,
+        ``hasattr(collection, name)`` returns ``False`` for missing attributes,
+        as it does for normal Python objects.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the collection from the class-level ``CLASS_DATA_ITEMS``.
+
+        Walks the class MRO in reverse order so that base-class entries are
+        inserted first and subclass entries take precedence on duplicate
+        keys. Each declared data item is deep-copied to avoid shared state
+        between instances.
+        """
+        self._data_items: dict[str, DataItem] = {}  # "SrcChannel" : ...
+        for cls in reversed(self.__class__.__mro__):
+            params = getattr(cls, "CLASS_DATA_ITEMS", None)
+            if params is None:
+                continue
+            for key, data_item in params.items():
+                self._data_items[key] = copy.deepcopy(data_item)
+
+        # whenever a public attribute is added to this class it
+        # needs to be added in __setattr__ to the currently
+        # empty list if name in ()
+
+    def __setitem__(self, key: str, value: tc.ANY_TYPE) -> None:
+        """Set the value of an existing data item.
+
+        Args:
+            key: The data item name. Must already exist in the collection.
+            value: The new value. It is converted to the data item's
+                declared type via its subscription/value setter.
+
+        Raises:
+            KeyError: If ``key`` is not a known data item of the collection
+                (the collection is key-immutable).
+        """
+        if key in self._data_items:
+            self._data_items[key].set_value(value)
+        else:
+            exc_msg = f"Cannot add new key key='{key}', assembly is key-immutable."
+            raise KeyError(exc_msg)
+
+    def __delitem__(self, key: str) -> None:
+        """Delete a data item from the collection.
+
+        Args:
+            key: The data item name.
+
+        Raises:
+            TypeError: Always. The collection is key-immutable and does
+                not support deletion of items.
+        """
+        exc_msg = f"delete attempt key='{key}': assembly is key-immutable."
+        raise TypeError(exc_msg)
+
+    # Standard MutableMapping interface
+    def __getitem__(self, key: str) -> tc.ANY_TYPE:
+        """Return the current value of the data item identified by ``key``.
+
+        Args:
+            key: The data item name.
+
+        Returns:
+            The current value of the data item (already type-cast by the
+            underlying [DataItem][mtppy.utils.data_item.DataItem]).
+        """
+        return self._data_items[key].get_value()
+
+    def __iter__(self) -> Iterator[str]:
+        """Return an iterator over the data item names.
+
+        Returns:
+            An iterator yielding the registered data item keys.
+        """
+        return iter(self._data_items)
+
+    def __len__(self) -> int:
+        """Return the number of data items in the collection.
+
+        Returns:
+            The number of registered data items.
+        """
+        return len(self._data_items)
+
+    def keys(self) -> KeysView[str]:
+        """Return a view of the data item names.
+
+        Returns:
+            A ``KeysView`` of the registered data item keys.
+        """
+        return self._data_items.keys()
+
+    def values(self) -> list[tc.ANY_TYPE]:
+        """Return the current values of all data items.
+
+        Returns:
+            A list with the current value of every data item, in the same
+            order as `keys`.
+        """
+        return [item.get_value() for item in self._data_items.values()]
+
+    def items(self) -> list[tuple[str, tc.ANY_TYPE]]:
+        """Return the current ``{name: value}`` dict of all data items.
+
+        Returns:
+            A list of ``(key, value)`` tuples for every data item, where
+            ``value`` is the current (already type-cast) value.
+        """
+        return [(k, v.get_value()) for k, v in self._data_items.items()]
+
+    def get_item(self, key: str) -> DataItem:
+        """Access the underlying [DataItem][mtppy.utils.data_item.DataItem] for
+        introspection.
+
+        Unlike [``__getitem__``][], this returns the full DataItem object
+        instead of only its current value, allowing callers to inspect or
+        modify attributes such as the data type, access mode or
+        subscription callback.
+
+        Args:
+            key: The data item name.
+
+        Returns:
+            The [DataItem][mtppy.utils.data_item.DataItem] instance registered
+            under ``key``.
+        """
+        return self._data_items[key]
+
+    def __getattr__(self, name: str) -> tc.ANY_TYPE:
+        """Enable both dict style on the rhs, that is dict-style
+        (``da["OSLevel"]``) and attribute-style (``da.OSLevel``) read access.
+
+        Missing attributes raise ``AttributeError`` so that ``hasattr`` follows
+        normal Python behavior.
+        """
+        try:
+            if name in self._data_items:
+                return self._data_items[name].get_value()
+            key = getattr(self.__class__, name)
+        except AttributeError as exc:
+            exc_msg = f"DataItemCollection has no attribute '{name}'"
+            raise AttributeError(exc_msg) from exc
+        if key in self._data_items:
+            return self._data_items[key].get_value()
+        exc_msg = f"DataItemCollection has no attribute '{name}'"
+        raise AttributeError(exc_msg)
+
+    def __setattr__(self, name: str, value: tc.ANY_TYPE) -> None:
+        """Enable both lhs dict style (``da["OSLevel"]``) and
+            attribute-style (`da.OSLevel``) write access.
+
+        Internal attributes and private names are stored
+        normally. Everything else is mapped to the matching class
+        constant key, if one exists, and validated/cast through the
+        underlying ``DataItem``.
+        """
+        if name.startswith("_"):  # or name in (set of protected names)
+            super().__setattr__(name, value)
+            return
+        if name in self._data_items:
+            self._data_items[name].set_value(value)
+        elif any(name in cls.__dict__ for cls in type(self).__mro__) or any(
+            name in getattr(cls, "__annotations__", {}) for cls in type(self).__mro__
+        ):
+            super().__setattr__(name, value)
+        else:
+            exc_msg = f"Cannot add unknown attribute '{name}' to data item collection."
+            raise KeyError(exc_msg)
+
+    def __repr__(self) -> str:
+        """Return an unambiguous string representation of the collection.
+
+        Returns:
+            A string of the form ``"data_items={...}"`` containing the
+            current ``name -> value`` mapping of every registered data item.
+        """
+        params = {k: v.get_value() for k, v in self._data_items.items()}
+        return f"class={self.__class__.__name__},data_items={params})"

mtppy/utils/data_item_com_test.py

@@ -0,0 +1,82 @@
+"""Test Suite for DataItem and OPCUACommunicationObject."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from unittest.mock import Mock
+
+from mtppy.part3.definitions.mtp_access import MTPAccess
+from mtppy.part5.communication_object import (
+    MODBUSCommunicationObject,
+    OPCUACommunicationObject,
+)
+from mtppy.part5.definitions.w3c_xml_data_types import W3cXmlDataTypes
+from mtppy.utils.data_item import DataItem
+
+
+def test_internal_write_triggers_only_subscriber_callbacks():
+    # Mock the subscription callback
+    mock_ext_wrt_cb = Mock()
+
+    # Mock the OPCUACommunicationObject
+    mock_comm_obj = Mock(spec=OPCUACommunicationObject)
+    mock_comm_obj.write_value_callback = Mock()
+    mock_comm_obj._node_id = "dummy"
+
+    # Create a DataItem instance with the mocked subscription callback
+    data_item = DataItem(
+        name="TestItem",
+        w3c_xml_data_type=W3cXmlDataTypes.INT,
+        access=MTPAccess.ReadWriteAccess,
+        init_value=0,
+        external_write_cb=mock_ext_wrt_cb,
+    )
+
+    # Attach the mocked communication object
+    data_item.attach_communication_object(mock_comm_obj)
+
+    # Set a new value and ensure callbacks are triggered
+    new_value = 42
+    data_item.set_value(new_value)
+
+    # Assert that the subscription callback was never called
+    mock_ext_wrt_cb.assert_not_called
+
+    # Assert that the communication object's write_value_callback was called with the correct value
+    mock_comm_obj.write_value_callback.assert_called_once_with(new_value)
+
+
+def test_modbus_communication_object_writes_data_item_value_to_register() -> None:
+    modbus_client = Mock()
+    communication_object = MODBUSCommunicationObject(modbus_client, "42")
+    data_item = DataItem(
+        name="TestItem",
+        w3c_xml_data_type=W3cXmlDataTypes.INT,
+        access=MTPAccess.ReadWriteAccess,
+        init_value=0,
+    )
+
+    data_item.attach_communication_object(communication_object)
+    data_item.set_value(7)
+
+    modbus_client.write_register.assert_called_once_with(address=42, value=7)
+
+
+def test_data_item_notifies_all_attached_communication_objects() -> None:
+    first_communication_object = Mock()
+    second_communication_object = Mock()
+    data_item = DataItem(
+        name="TestItem",
+        w3c_xml_data_type=W3cXmlDataTypes.INT,
+        access=MTPAccess.ReadWriteAccess,
+        init_value=0,
+    )
+
+    data_item.attach_communication_object(first_communication_object)
+    data_item.attach_communication_object(second_communication_object)
+    data_item.set_value(7)
+
+    first_communication_object.write_value_callback.assert_called_once_with(7)
+    second_communication_object.write_value_callback.assert_called_once_with(7)