OpenSMI-Core 0.1__py3-none-any.whl

opensmi/core/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Common functionality for both server and client."""
+
+from importlib import metadata
+
+from .async_task_mixin import AsyncTaskMixin as AsyncTaskMixin
+from .enums import LifecycleState as LifecycleState
+from .lifecycle_mixin import LifecycleMixin as LifecycleMixin
+from .lifecycle_mixin import lifecycle as lifecycle
+from .logging import LogFormat as LogFormat
+from .logging import setup_logging as setup_logging
+from .signal import Signal as Signal
+from .ua_enums import MachineryItemState as MachineryItemState
+from .ua_enums import MachineryOperationMode as MachineryOperationMode
+from .ua_enums import SkillState as SkillState
+from .unit_all import Unit as Unit
+
+__version__ = metadata.version("OpenSMI-Core")

opensmi/core/async_task_mixin.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Mixin for reliable tracking of fire-and-forget asyncio tasks."""
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+
+class AsyncTaskMixin:
+    """Mixin for reliable tracking of fire-and-forget asyncio tasks.
+
+    Avoids such tasks disappearing while executing when garbage collected
+    (https://docs.python.org/3/library/asyncio-task.html#creating-tasks).
+    """
+
+    __tasks: set[asyncio.Task[None]] | None = None
+
+    def _create_task(
+        self,
+        coro: Coroutine[Any, Any, None],  # pyright: ignore[reportExplicitAny]
+        *,
+        name: str,
+    ) -> None:
+        """Schedule and track a background coroutine.
+
+        The coroutine must return ``None``.
+        """
+        if self.__tasks is None:
+            self.__tasks = set()
+
+        task = asyncio.create_task(coro, name=name)
+        self.__tasks.add(task)
+        task.add_done_callback(self.__tasks.discard)
+
+    @property
+    def _pending_tasks(self) -> set[asyncio.Task[None]]:
+        """Return currently running tracked tasks."""
+        if self.__tasks is None:
+            return set()
+        return self.__tasks.copy()
+
+    async def _cancel_tasks(self) -> None:
+        """Cancel and await all tracked tasks."""
+        if self.__tasks is None:
+            return  # nothing to cancel
+        tasks = self.__tasks.copy()
+
+        for task in tasks:
+            _ = task.cancel()
+
+        if tasks:
+            _ = await asyncio.gather(*tasks, return_exceptions=True)

opensmi/core/base_server.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Base class for both client `RemoteServer` and server `Server`."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+from weakref import WeakValueDictionary
+
+from asyncua import ua
+
+from opensmi.core.base_ua_object import BaseUaObject
+from opensmi.core.protocols import NamespaceProvider
+from opensmi.core.ua import NodeIdDefinition
+
+_UaObjectType = TypeVar("_UaObjectType", bound=BaseUaObject)
+
+
+class BaseServer(Generic[_UaObjectType]):
+    """Base class for both client `RemoteServer` and server `Server`."""
+
+    def __init__(self, **kwargs) -> None:
+        """*Cooperative* constructor."""
+        super().__init__(**kwargs)
+
+        self._ua_objects: WeakValueDictionary[ua.NodeId, _UaObjectType] = WeakValueDictionary()
+        """Maps OPC UA nodes to UaObjects with weak references."""
+        self._namespace_map: dict[str, int] = {}
+
+    def get_ua_object(self, ua_node_id: ua.NodeId) -> _UaObjectType:
+        """Return the ``UaObject`` which corresponds to the given ``ua_node``.
+
+        :raises KeyError: If no ``UaObject`` is found.
+        """
+        return self._ua_objects[ua_node_id]
+
+    def get_ua_object_optional(self, ua_node_id: ua.NodeId) -> _UaObjectType | None:
+        """Return the ``UaObject`` which corresponds to the given ``ua_node`` or ``None``."""
+        return self._ua_objects.get(ua_node_id, default=None)
+
+    def register_ua_object(self, ua_object: _UaObjectType) -> None:
+        """Register the given ``UaObject`` to the server."""
+        assert ua_object is not None
+        assert isinstance(ua_object.ua_node.nodeid, ua.NodeId)
+
+        self._ua_objects[ua_object.ua_node.nodeid] = ua_object
+
+    def unregister_ua_object(self, ua_object: _UaObjectType) -> None:
+        """Unregister the given ``UaObject`` from the server."""
+        assert ua_object is not None
+        assert isinstance(ua_object.ua_node.nodeid, ua.NodeId)
+
+        _ = self._ua_objects.pop(ua_object.ua_node.nodeid)
+
+    def ua_get_namespace_index(self, uri: str | type[NamespaceProvider]) -> ua.Int16:
+        """Return the namespace index for the given namespace ``uri``.
+
+        :raises KeyError: If the namespace URI is unknown.
+        """
+        if not isinstance(uri, str):
+            uri = uri.URI
+
+        return ua.Int16(self._namespace_map[uri])
+
+    def ua_get_node_id(self, identifier: NodeIdDefinition) -> ua.NodeId:
+        """Return the complete OPC UA node ID for the given ``identifier``.
+
+        :raises KeyError: If the namespace URI of the identifier is unknown.
+        """
+        return ua.NodeId(
+            Identifier=identifier.id,
+            NamespaceIndex=self.ua_get_namespace_index(identifier.ns_uri),
+        )

opensmi/core/base_ua_object.py

@@ -0,0 +1,120 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Base class for all UA objects, both client- and server-side."""
+
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+import structlog
+from asyncua.common.node import Node
+from structlog.stdlib import BoundLogger
+from typing_extensions import deprecated
+
+if TYPE_CHECKING:
+    from opensmi.core.base_server import BaseServer
+
+_ServerType = TypeVar("_ServerType", bound="BaseServer")
+
+
+class BaseUaObject(Generic[_ServerType]):
+    """Base class for all UA objects, both client- and server-side."""
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        server: _ServerType | None = None,
+        **kwargs,
+    ) -> None:
+        """*Cooperative* constructor.
+
+        :param name: The name of the UA object. Defaults to the class name.
+        :param server: The associated server of the UA object. Note that there must be at least one non ``None`` in
+            the hierarchy.
+        """
+        if name is None:
+            name = self.__class__.__name__
+        elif not isinstance(name, str) or name == "":
+            msg = f"Given name '{name}' is not valid!"
+            raise TypeError(msg)
+
+        self._name: str = name
+        self._server: _ServerType | None = server
+        self._ua_node: Node | None = None
+        self._logger: structlog.BoundLogger = structlog.get_logger(
+            f"opensmi.{self.__class__.__name__}", name=self.name
+        )
+
+        super().__init__(**kwargs)  # cooperative __init__() after we are done
+
+    @property
+    def ua_node(self) -> Node:
+        """Return the internal OPC UA node."""
+        if self._ua_node is not None:
+            return self._ua_node
+
+        msg = f"UA node of {self!r} is unknown, something went wrong!"
+        raise RuntimeError(msg)
+
+    @ua_node.setter
+    def ua_node(self, ua_node: Node) -> None:
+        """Set main OPC UA node to an existing node (due to XML import, etc.). Only possible once."""
+        if self._ua_node is not None:
+            msg = f"Main OPC UA node of {self!r} already exists!"
+            raise RuntimeError(msg)
+
+        self._ua_node = ua_node
+        self.server.register_ua_object(self)
+
+    @property
+    def name(self) -> str:
+        """Name of the object."""
+        return self._name
+
+    @property
+    @deprecated("Use path instead")
+    def full_name(self) -> str:
+        parent = getattr(self, "parent", None)
+        if isinstance(parent, BaseUaObject):
+            return f"{parent.full_name}/{self.name}"
+        return f"/{self.name}"
+
+    @property
+    def path(self) -> PurePosixPath:
+        """Return the full path of the object."""
+        if isinstance(parent := getattr(self, "parent", None), BaseUaObject):
+            return parent.path / self.name
+        return PurePosixPath("/") / self.name
+
+    @property
+    def logger(self) -> BoundLogger:
+        """Logger associated with the `UaObject` instance."""
+        return self._logger  # type: ignore
+
+    # TODO
+    # @override
+    # def _repr_items(self) -> Iterator[tuple[str, object]]:
+    #     yield "name", self._name
+    #     yield "ua_node", self._ua_node
+    #     yield from super()._repr_items()
+
+    @property
+    def server(self) -> _ServerType:
+        """Return the associated server."""
+        if self._server is not None:
+            return self._server
+
+        parent = getattr(self, "parent", None)
+        assert parent is not None
+
+        server = getattr(parent, "server", None)
+        assert server is not None
+
+        self._server = server
+        return server  # type: ignore
+
+    @server.setter
+    def server(self, server: _ServerType) -> None:
+        self._server = server

opensmi/core/config.py

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Functions to load configuration dataclasses from TOML files."""
+
+import tomllib
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from pathlib import Path
+from types import UnionType
+from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
+
+_T = TypeVar("_T")
+
+
+def load_toml(path: str | Path) -> dict[str, Any]:
+    """Load a TOML file into a dictionary."""
+    with Path(path).open("rb") as f:
+        return tomllib.load(f)
+
+
+def load_dataclass(data_cls: type[_T], path: str | Path) -> _T:
+    """Load a dataclass configuration from a TOML file."""
+    return from_dict(data_cls, load_toml(path))
+
+
+def from_dict(data_cls: type[_T], data: dict[str, Any]) -> _T:
+    """Create a dataclass instance from a (TOML) dictionary."""
+    if not is_dataclass(data_cls):
+        msg = f"{data_cls.__name__} is not a dataclass"
+        raise TypeError(msg)
+
+    type_hints = get_type_hints(data_cls)
+    known_fields: set[str] = {field_.name for field_ in fields(data_cls)}
+
+    unknown: set[str] = set(data) - known_fields
+    if unknown:
+        msg = f"Unknown configuration option(s) for {data_cls.__name__}: " + ", ".join(sorted(unknown))
+        raise ValueError(msg)
+
+    kwargs = {name: _convert(value, type_hints[name]) for name, value in data.items()}
+    # Fields not present in TOML are deliberately omitted.
+    # The dataclass default/default_factory will be used.
+    return data_cls(**kwargs)
+
+
+def _convert(value: Any, target_type: Any) -> Any:
+    """Convert a (TOML) value to the requested Python type."""
+    origin = get_origin(target_type)
+
+    # Optional[T] / T | None
+    if origin in (Union, UnionType):
+        args = get_args(target_type)
+
+        if value is None and type(None) in args:
+            return None
+
+        non_none = [arg for arg in args if arg is not type(None)]
+        if len(non_none) == 1:
+            return _convert(value, non_none[0])
+
+    # Enum
+    if isinstance(target_type, type) and issubclass(target_type, Enum):
+        try:
+            return target_type(value)
+        except ValueError as exc:
+            valid = ", ".join(repr(member.value) for member in target_type)
+            msg = f"Invalid value {value!r} for {target_type.__name__}; expected one of: {valid}"
+            raise ValueError(msg) from exc
+
+    # Nested dataclass
+    if isinstance(target_type, type) and is_dataclass(target_type):
+        if not isinstance(value, dict):
+            msg = f"Expected a TOML table for {target_type.__name__}, got {type(value).__name__}"
+            raise TypeError(msg)
+        return from_dict(target_type, value)
+
+    # list[T]
+    if origin is list:
+        assert isinstance(value, list)
+        (item_type,) = get_args(target_type)
+        return [_convert(item, item_type) for item in value]
+
+    # dict[K, V]
+    if origin is dict:
+        assert isinstance(value, dict)
+        key_type, value_type = get_args(target_type)
+        return {_convert(key, key_type): _convert(item, value_type) for key, item in value.items()}
+
+    # Basic types are already returned by tomllib.
+    return value

opensmi/core/enums.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+from enum import IntEnum, auto
+
+
+class LifecycleState(IntEnum):
+    """Represents the lifecycle state of an instance of machine, skill, component, etc."""
+
+    NEW = auto()
+    """ Instance is created, but not (async) initialized. """
+    INITIALIZING = auto()
+    """ Instance is currently (async) initializing. """
+    INITIALIZED = auto()
+    """ Instance is initialized successfully and ready to be used. """
+    INITIALIZATION_FAILED = auto()
+    """ Instance initialization failed and instance may need to be shut down. """
+    SHUTTING_DOWN = auto()
+    """ Instance is currently (async) shutting down. """
+    SHUTDOWN = auto()
+    """ Instance is shut down successfully and cannot be used anymore. Final state."""
+    SHUTDOWN_FAILED = auto()
+    """ Instance shutdown failed and cannot be used anymore. Final state."""

opensmi/core/errors.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+from collections.abc import Hashable
+
+
+class OpenSmiError(Exception):
+    """Base for all OpenSMI related errors."""
+
+
+class SkillNotSuspendableError(OpenSmiError):
+    """Is raised when failing to suspend a skill that is not suspendable."""
+
+
+class OpenSmiRuntimeError(OpenSmiError):
+    """Is raised by user code when something goes wrong.
+
+    Use this exception instead of the build-in ``RuntimeError``.
+    """
+
+    def __init__(self, msg: str, error_code: str = "") -> None:
+        """Construct a new PyUaAdapterError with the given error message and error code."""
+        self.msg = msg
+        self.error_code = error_code
+
+
+class NoValidValueReadError(OpenSmiError):
+    """Is raised when trying to read a `UaVariable` whose value is ``None``."""
+
+
+class SkillHaltedError(OpenSmiRuntimeError):
+    """Is raised when a skill other than the own skill is halted.
+
+    (i.e. when calling other skills)
+    """
+
+
+class OutOfRangeError(OpenSmiRuntimeError):
+    """Is raised when failing to write a value to a variable that is out of range."""
+
+
+class NamespaceUninitializedError(OpenSmiError):
+    """Is raised when trying to get node ids from a namespace before it was initialized."""
+
+
+class RequiredVariableMissingError(OpenSmiError):
+    """Is raised when a required variable is missing."""
+
+
+class ValidationError(ValueError):
+    """Is raised when trying to validate an object that doesn't pass validation.
+
+    Will only be raised during initialization.
+    """
+
+
+class CycleError(Exception):
+    """Raised when a dependency graph of ``@lifecycle`` decorated methods contains a cycle.
+
+    See `LifecycleMixin` for more details.
+    """
+
+    def __init__(self, path: list[Hashable]) -> None:
+        """Construct a new CycleError with the given path containing the cycle."""
+        node: Hashable = path[-1]
+        super().__init__(f"cycle detected at {node!r} (path: {path!r})")

opensmi/core/frozen.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Metaclass for frozen classes."""
+
+from typing import Any, Never
+
+
+class FrozenMeta(type):
+    """Metaclass for frozen classes."""
+
+    def __call__(cls, *args, **kwargs) -> Never:
+        """Prevent instantiation of frozen classes."""
+        msg = f"{cls.__name__} cannot be instantiated"
+        raise TypeError(msg)
+
+    def __setattr__(cls, name: str, value: Any) -> Never:
+        """Prevent overriding attributes of frozen classes."""
+        msg = f"{cls.__name__} is frozen"
+        raise TypeError(msg)
+
+    def __delattr__(cls, name: str) -> Never:
+        """Prevent deleting attributes of frozen classes.."""
+        msg = f"{cls.__name__} is frozen"
+        raise TypeError(msg)

opensmi/core/hook.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Helper for dealing with async hooks."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+
+
+async def call_hook(
+    hook: Callable[[], Awaitable[None]],
+) -> None:
+    """Call coroutine ``hook``, but provide helpful ``TypeError`` if `hook` is not a coroutine."""
+    if not inspect.iscoroutinefunction(hook):
+        hook_class = f"{hook.__self__.__class__.__name__}."  # pyright: ignore[reportFunctionMemberAccess]
+        msg = f"{hook_class}{hook.__name__}() must be declared with 'async def'."
+        raise TypeError(msg)
+
+    await hook()