OpenSMI-Core 0.4__tar.gz → 0.4.1__tar.gz

{opensmi_core-0.4 → opensmi_core-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenSMI-Core
-Version: 0.4
+Version: 0.4.1
 Summary: Smart Machine Interface core functionality for server and client applications.
 Author-email: Carsten Harms <Carsten.Harms@dfki.de>, Simon Jungbluth <Simon.Jungbluth@smartfactory.de>
 License-Expression: MIT

{opensmi_core-0.4 → opensmi_core-0.4.1}/src/OpenSMI_Core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenSMI-Core
-Version: 0.4
+Version: 0.4.1
 Summary: Smart Machine Interface core functionality for server and client applications.
 Author-email: Carsten Harms <Carsten.Harms@dfki.de>, Simon Jungbluth <Simon.Jungbluth@smartfactory.de>
 License-Expression: MIT

opensmi_core-0.4.1/src/OpenSMI_Core.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.4.1",
+  "distance": 0,
+  "node": "gb332e932b41897204fcea659cd4b99c6cc4f228d",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-13"
+}

{opensmi_core-0.4 → opensmi_core-0.4.1}/src/opensmi/core/lifecycle_mixin.py

@@ -5,23 +5,30 @@
 """Mixin for async lifecycle management for mixin-composed classes.
 
 Concepts
+========
 
-Resource mixin: a plain class (does not inherit `LifecycleMixin`) with one or
-multiple ``@lifecycle``-decorated async-generator method(s). Code before yield is init;
-code after yield is shutdown.
+Resource
+    A single `lifecycle`-decorated async-generator method. Code before ``yield`` initializes it;
+    code after ``yield`` shuts it down. A resource is the unit of ordering:
+    ``after``, ``before`` and ``requires`` refer to resources, not classes.
 
-Composed class: the concrete class that inherits its resource mixins and
-`LifecycleMixin`. This is the only class that should inherit `LifecycleMixin`.
+Resource mixin
+    A plain class (does not inherit `LifecycleMixin`) that provides one or more resources.
 
-Ordering: resources init in dependency order and shut down in the exact
-reverse order. Order is resolved once, in `LifecycleMixin.__init_subclass__`, from
-``after`` / ``before`` arguments of ``@lifecycle``-decorated methods.
+Composed class
+    The concrete class that inherits its resource mixins and `LifecycleMixin`.
+    This is the only class that should inherit `LifecycleMixin`.
+
+Ordering
+    Resources are initialized in dependency order and shut down in the exact reverse order. Order is
+    resolved once, in `LifecycleMixin.__init_subclass__`, from ``after`` / ``before``
+    arguments of `lifecycle`-decorated methods. ``requires`` is checked at the same point
+    but imposes no ordering.
 """
 
 import graphlib
 import inspect
 import time
-from asyncio import CancelledError
 from collections.abc import AsyncGenerator, Callable
 from typing import Final, Self, TypeVar, overload
 
@@ -47,7 +54,7 @@ _FuncOrFuncs = _Func | tuple[_Func, ...] | list[_Func]
 def lifecycle(_func: _LifecycleFunc) -> _LifecycleFunc: ...
 @overload
 def lifecycle(
-    _func: None = None, *, after: _FuncOrFuncs = (), before: _FuncOrFuncs = ()
+    _func: None = None, *, after: _FuncOrFuncs = (), before: _FuncOrFuncs = (), requires: _FuncOrFuncs = ()
 ) -> Callable[[_LifecycleFunc], _LifecycleFunc]: ...
 def lifecycle(
     _func: _LifecycleFunc | None = None,
@@ -56,7 +63,7 @@ def lifecycle(
     before: _FuncOrFuncs = (),
     requires: _FuncOrFuncs = (),
 ) -> _LifecycleFunc | Callable[[_LifecycleFunc], _LifecycleFunc]:
-    """Mark an async generator method as a lifecycle resource.
+    """Mark an async generator method as a resource.
 
     Code before ``yield`` runs during initialization; code after ``yield``
     runs during shutdown, in reverse lifecycle order.
@@ -92,13 +99,13 @@ def lifecycle(
         setattr(func, _ATTR_LIFECYCLE_REQUIRES, tuple(_normalize(requires)))
         return func
 
-    if _func is not None:  # bare @resource, no args
+    if _func is not None:  # bare @lifecycle, no args
         return _decorator(_func)
-    return _decorator  # @resource(after=(...))
+    return _decorator  # @lifecycle(after=(...))
 
 
 class LifecycleMixin:
-    """Mixin managing the lifecycle of classes with ``@resource`` decorated methods."""
+    """Mixin managing the lifecycle of classes with `lifecycle` decorated methods."""
 
     __order: list[_Func] | None = None
     __generators: dict[_Func, AsyncGenerator[None, None]] | None = None
@@ -124,7 +131,7 @@ class LifecycleMixin:
         On failure, rollback anything already started, in reverse.
 
         :raises BaseException: Reraised exception from failed resource initialization.
-        :raises ExceptionGroup: If exceptions were caught during rollback.
+        :raises BaseExceptionGroup: If exceptions were caught during rollback.
         """
         if self.__state != LifecycleState.NEW:
             return self
@@ -133,10 +140,12 @@ class LifecycleMixin:
         self.__generators = {}
 
         started: list[_Func] = []
+        current: _Func | None = None
         time_start = time.monotonic()
         try:
             assert self.__order is not None
             for func in self.__order:
+                current = func
                 get_logger(self, _LOGGER).debug("starting...", func=func.__qualname__)
                 agen = func(self)
                 await agen.__anext__()  # run resource init (until it yields)
@@ -144,21 +153,19 @@ class LifecycleMixin:
                 started.append(func)
                 get_logger(self, _LOGGER).debug("started successfully", func=func.__qualname__)
         except BaseException as init_exception:
-            if isinstance(init_exception, CancelledError):
-                get_logger(self, _LOGGER).error("Initialization cancelled")
-            else:
-                get_logger(self, _LOGGER).exception("Failed to initialize!")
+            if current is not None:
+                init_exception.add_note(
+                    f"{type(self).__name__}: failed starting {current.__qualname__}; "
+                    f"{len(started)} resource(s) had been started before it."
+                )
             self.__state = LifecycleState.INITIALIZATION_FAILED
             rollback_exceptions: list[Exception] = await self.__shutdown(started)
             if rollback_exceptions:
                 msg = (
-                    f"Resource failed to initialize, and rollback {len(rollback_exceptions)} "
+                    f"Resource failed to initialize, and rollback of {len(rollback_exceptions)} "
                     "resource(s) failed to shut down cleanly."
                 )
-                raise ExceptionGroup(
-                    msg,
-                    [init_exception, *rollback_exceptions],  # pyright: ignore[reportArgumentType]
-                ) from init_exception
+                raise BaseExceptionGroup(msg, [init_exception, *rollback_exceptions]) from init_exception
             raise
 
         self.__state = LifecycleState.INITIALIZED
@@ -256,7 +263,7 @@ def _build_edges(funcs: set[_Func]) -> dict[_Func, set[_Func]]:
 
     for func in funcs:
         # hard requirement: target must be present
-        required_funcs: tuple[type, ...] = getattr(func, _ATTR_LIFECYCLE_REQUIRES, ())
+        required_funcs: tuple[_Func, ...] = getattr(func, _ATTR_LIFECYCLE_REQUIRES, ())
         for dep in required_funcs:
             if dep not in funcs:
                 msg = (
@@ -266,12 +273,12 @@ def _build_edges(funcs: set[_Func]) -> dict[_Func, set[_Func]]:
                 raise TypeError(msg)
 
         # soft hint: only wire the edge if the target actually ended up present
-        after_funcs: tuple[type, ...] = getattr(func, _ATTR_LIFECYCLE_AFTER, ())
+        after_funcs: tuple[_Func, ...] = getattr(func, _ATTR_LIFECYCLE_AFTER, ())
         for after_func in after_funcs:
             if after_func in funcs:
                 edges[func].add(after_func)
 
-        before_funcs: tuple[type, ...] = getattr(func, _ATTR_LIFECYCLE_BEFORE, ())
+        before_funcs: tuple[_Func, ...] = getattr(func, _ATTR_LIFECYCLE_BEFORE, ())
         for before_func in before_funcs:
             if before_func in funcs:
                 edges[before_func].add(func)

opensmi_core-0.4/src/OpenSMI_Core.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.4",
-  "distance": 0,
-  "node": "gf395f24046a13a5a9c4b6536f16e250aada34582",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-12"
-}