haiway 0.24.3__py3-none-any.whl → 0.25.1__py3-none-any.whl

haiway/context/disposables.py

@@ -2,19 +2,15 @@ from asyncio import (
     AbstractEventLoop,
     gather,
     get_running_loop,
-    iscoroutinefunction,
     run_coroutine_threadsafe,
     wrap_future,
 )
-from collections.abc import Callable, Coroutine, Iterable
+from collections.abc import Collection, Iterable
 from contextlib import AbstractAsyncContextManager
 from itertools import chain
 from types import TracebackType
-from typing import Any, final
 
-from haiway.context.state import StateContext
-from haiway.state import State
-from haiway.utils.mimic import mimic_function
+from haiway.state import Immutable, State
 
 __all__ = (
     "Disposable",
@@ -57,8 +53,7 @@ Creating a disposable database connection:
 """
 
 
-@final
-class Disposables:
+class Disposables(Immutable):
     """
     A container for multiple Disposable resources that manages their lifecycle.
 
@@ -112,11 +107,8 @@ class Disposables:
     ...     # All resources cleaned up automatically
     """
 
-    __slots__ = (
-        "_disposables",
-        "_loop",
-        "_state_context",
-    )
+    _disposables: Collection[Disposable]
+    _loop: AbstractEventLoop | None
 
     def __init__(
         self,
@@ -130,44 +122,17 @@ class Disposables:
         *disposables: Disposable
             Variable number of disposable resources to be managed together.
         """
-        self._disposables: tuple[Disposable, ...]
         object.__setattr__(
             self,
             "_disposables",
             disposables,
         )
-        self._state_context: StateContext | None
-        object.__setattr__(
-            self,
-            "_state_context",
-            None,
-        )
-        self._loop: AbstractEventLoop | None
         object.__setattr__(
             self,
             "_loop",
             None,
         )
 
-    def __setattr__(
-        self,
-        name: str,
-        value: Any,
-    ) -> Any:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be modified"
-        )
-
-    def __delattr__(
-        self,
-        name: str,
-    ) -> None:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be deleted"
-        )
-
     def __bool__(self) -> bool:
         """
         Check if this container has any disposables.
@@ -215,23 +180,6 @@ class Disposables:
             )
         )
 
-    async def __aenter__(self) -> None:
-        """
-        Enter all contained disposables asynchronously.
-
-        Enters all disposables in parallel and collects any State objects they return updating
-         current state context.
-        """
-
-        assert self._state_context is None, "Context reentrance is not allowed"  # nosec: B101
-        state_context = StateContext.updated(await self.prepare())
-        state_context.__enter__()
-        object.__setattr__(
-            self,
-            "_state_context",
-            state_context,
-        )
-
     async def _cleanup(
         self,
         /,
@@ -320,65 +268,3 @@ class Disposables:
 
             case _:
                 raise BaseExceptionGroup("Disposables cleanup errors", exceptions)
-
-    async def __aexit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
-    ) -> None:
-        """
-        Exit all contained disposables asynchronously.
-
-        Properly disposes of all resources by calling their __aexit__ methods in parallel.
-        If multiple disposables raise exceptions, they are collected into a BaseExceptionGroup.
-        Additionally, produced state context will be also exited resetting state to previous.
-
-        Parameters
-        ----------
-        exc_type: type[BaseException] | None
-            The type of exception that caused the context to be exited
-        exc_val: BaseException | None
-            The exception that caused the context to be exited
-        exc_tb: TracebackType | None
-            The traceback for the exception that caused the context to be exited
-
-        Raises
-        ------
-        BaseExceptionGroup
-            If multiple disposables raise exceptions during exit
-        """
-        assert self._state_context is not None, "Unbalanced context enter/exit"  # nosec: B101
-        try:
-            self._state_context.__exit__(
-                exc_type,
-                exc_val,
-                exc_tb,
-            )
-            object.__setattr__(
-                self,
-                "_state_context",
-                None,
-            )
-
-        finally:
-            await self.dispose(
-                exc_type,
-                exc_val,
-                exc_tb,
-            )
-
-    def __call__[Result, **Arguments](
-        self,
-        function: Callable[Arguments, Coroutine[Any, Any, Result]],
-    ) -> Callable[Arguments, Coroutine[Any, Any, Result]]:
-        assert iscoroutinefunction(function)  # nosec: B101
-
-        async def async_context(
-            *args: Arguments.args,
-            **kwargs: Arguments.kwargs,
-        ) -> Result:
-            async with self:
-                return await function(*args, **kwargs)
-
-        return mimic_function(function, within=async_context)

haiway/context/identifier.py

@@ -1,13 +1,14 @@
 from contextvars import ContextVar, Token
 from types import TracebackType
-from typing import Any, Self, final
+from typing import Any, ClassVar, Self
 from uuid import UUID, uuid4
 
+from haiway.state import Immutable
+
 __all__ = ("ScopeIdentifier",)
 
 
-@final
-class ScopeIdentifier:
+class ScopeIdentifier(Immutable):
     """
     Identifies and manages scope context identities.
 
@@ -18,7 +19,7 @@ class ScopeIdentifier:
     This class is immutable after instantiation.
     """
 
-    _context = ContextVar[Self]("ScopeIdentifier")
+    _context: ClassVar[ContextVar[Self]] = ContextVar[Self]("ScopeIdentifier")
 
     @classmethod
     def current(
@@ -30,7 +31,7 @@ class ScopeIdentifier:
     @classmethod
     def scope(
         cls,
-        label: str,
+        name: str,
         /,
     ) -> Self:
         """
@@ -41,7 +42,7 @@ class ScopeIdentifier:
 
         Parameters
         ----------
-        label: str
+        name: str
             The name of the scope
 
         Returns
@@ -58,82 +59,56 @@ class ScopeIdentifier:
 
             scope_id: UUID = uuid4()
             return cls(
-                label=label,
+                name=name,
                 scope_id=scope_id,
                 parent_id=scope_id,  # own id is parent_id for root
             )
 
         # create nested scope otherwise
         return cls(
-            label=label,
+            name=name,
             scope_id=uuid4(),
             parent_id=current.scope_id,
         )
 
-    __slots__ = (
-        "_token",
-        "label",
-        "parent_id",
-        "scope_id",
-        "unique_name",
-    )
+    parent_id: UUID
+    scope_id: UUID
+    name: str
+    unique_name: str
+    _token: Token[Self] | None = None
 
     def __init__(
         self,
         parent_id: UUID,
         scope_id: UUID,
-        label: str,
+        name: str,
     ) -> None:
-        self.parent_id: UUID
         object.__setattr__(
             self,
             "parent_id",
             parent_id,
         )
-        self.scope_id: UUID
         object.__setattr__(
             self,
             "scope_id",
             scope_id,
         )
-        self.label: str
         object.__setattr__(
             self,
-            "label",
-            label,
+            "name",
+            name,
         )
-        self.unique_name: str
         object.__setattr__(
             self,
             "unique_name",
-            f"[{label}] [{scope_id.hex}]",
+            f"[{name}] [{scope_id}]",
         )
-        self._token: Token[ScopeIdentifier] | None
         object.__setattr__(
             self,
             "_token",
             None,
         )
 
-    def __setattr__(
-        self,
-        name: str,
-        value: Any,
-    ) -> Any:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be modified"
-        )
-
-    def __delattr__(
-        self,
-        name: str,
-    ) -> None:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be deleted"
-        )
-
     @property
     def is_root(self) -> bool:
         """
@@ -204,7 +179,7 @@ class ScopeIdentifier:
             If this context is not active
         """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
-        ScopeIdentifier._context.reset(self._token)
+        ScopeIdentifier._context.reset(self._token)  # pyright: ignore[reportArgumentType]
         object.__setattr__(
             self,
             "_token",

haiway/context/observability.py

@@ -7,10 +7,11 @@ from logging import INFO as INFO_LOGGING
 from logging import WARNING as WARNING_LOGGING
 from logging import Logger, getLogger
 from types import TracebackType
-from typing import Any, Protocol, Self, final, runtime_checkable
+from typing import Any, ClassVar, Protocol, Self, runtime_checkable
 from uuid import UUID, uuid4
 
 from haiway.context.identifier import ScopeIdentifier
+from haiway.state import Immutable
 from haiway.types import Missing
 from haiway.utils.formatting import format_str
 
@@ -190,7 +191,7 @@ class ObservabilityScopeExiting(Protocol):
     ) -> None: ...
 
 
-class Observability:  # avoiding State inheritance to prevent propagation as scope state
+class Observability(Immutable):  # avoiding State inheritance to prevent propagation as scope state
     """
     Container for observability recording functions.
 
@@ -201,107 +202,13 @@ class Observability:  # avoiding State inheritance to prevent propagation as sco
     This class is immutable after initialization.
     """
 
-    __slots__ = (
-        "attributes_recording",
-        "event_recording",
-        "log_recording",
-        "metric_recording",
-        "scope_entering",
-        "scope_exiting",
-        "trace_identifying",
-    )
-
-    def __init__(
-        self,
-        trace_identifying: ObservabilityTraceIdentifying,
-        log_recording: ObservabilityLogRecording,
-        metric_recording: ObservabilityMetricRecording,
-        event_recording: ObservabilityEventRecording,
-        attributes_recording: ObservabilityAttributesRecording,
-        scope_entering: ObservabilityScopeEntering,
-        scope_exiting: ObservabilityScopeExiting,
-    ) -> None:
-        """
-        Initialize an Observability container with recording functions.
-
-        Parameters
-        ----------
-        trace_identifying: ObservabilityTraceIdentifying
-            Function for identifying traces
-        log_recording: ObservabilityLogRecording
-            Function for recording log messages
-        metric_recording: ObservabilityMetricRecording
-            Function for recording metrics
-        event_recording: ObservabilityEventRecording
-            Function for recording events
-        attributes_recording: ObservabilityAttributesRecording
-            Function for recording attributes
-        scope_entering: ObservabilityScopeEntering
-            Function called when a scope is entered
-        scope_exiting: ObservabilityScopeExiting
-            Function called when a scope is exited
-        """
-        self.trace_identifying: ObservabilityTraceIdentifying
-        object.__setattr__(
-            self,
-            "trace_identifying",
-            trace_identifying,
-        )
-        self.log_recording: ObservabilityLogRecording
-        object.__setattr__(
-            self,
-            "log_recording",
-            log_recording,
-        )
-        self.metric_recording: ObservabilityMetricRecording
-        object.__setattr__(
-            self,
-            "metric_recording",
-            metric_recording,
-        )
-        self.event_recording: ObservabilityEventRecording
-        object.__setattr__(
-            self,
-            "event_recording",
-            event_recording,
-        )
-        self.attributes_recording: ObservabilityAttributesRecording
-        object.__setattr__(
-            self,
-            "attributes_recording",
-            attributes_recording,
-        )
-        self.scope_entering: ObservabilityScopeEntering
-        object.__setattr__(
-            self,
-            "scope_entering",
-            scope_entering,
-        )
-        self.scope_exiting: ObservabilityScopeExiting
-        object.__setattr__(
-            self,
-            "scope_exiting",
-            scope_exiting,
-        )
-
-    def __setattr__(
-        self,
-        name: str,
-        value: Any,
-    ) -> Any:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be modified"
-        )
-
-    def __delattr__(
-        self,
-        name: str,
-    ) -> None:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be deleted"
-        )
+    trace_identifying: ObservabilityTraceIdentifying
+    log_recording: ObservabilityLogRecording
+    metric_recording: ObservabilityMetricRecording
+    event_recording: ObservabilityEventRecording
+    attributes_recording: ObservabilityAttributesRecording
+    scope_entering: ObservabilityScopeEntering
+    scope_exiting: ObservabilityScopeExiting
 
 
 def _logger_observability(
@@ -408,7 +315,7 @@ def _logger_observability(
     ) -> None:
         logger.log(
             ObservabilityLevel.DEBUG,
-            f"[{trace_id_hex}] {scope.unique_name} Entering scope: {scope.label}",
+            f"[{trace_id_hex}] {scope.unique_name} Entering scope: {scope.name}",
         )
 
     def scope_exiting(
@@ -419,7 +326,7 @@ def _logger_observability(
     ) -> None:
         logger.log(
             ObservabilityLevel.DEBUG,
-            f"{scope.unique_name} Exiting scope: {scope.label}",
+            f"{scope.unique_name} Exiting scope: {scope.name}",
             exc_info=exception,
         )
 
@@ -434,8 +341,7 @@ def _logger_observability(
     )
 
 
-@final
-class ObservabilityContext:
+class ObservabilityContext(Immutable):
     """
     Context manager for observability within a scope.
 
@@ -446,7 +352,7 @@ class ObservabilityContext:
     This class is immutable after initialization.
     """
 
-    _context = ContextVar[Self]("ObservabilityContext")
+    _context: ClassVar[ContextVar[Self]] = ContextVar[Self]("ObservabilityContext")
 
     @classmethod
     def scope(
@@ -486,7 +392,7 @@ class ObservabilityContext:
                     resolved_observability = observability
 
                 case None:
-                    resolved_observability = _logger_observability(getLogger(scope.label))
+                    resolved_observability = _logger_observability(getLogger(scope.name))
 
                 case Logger() as logger:
                     resolved_observability = _logger_observability(logger)
@@ -534,7 +440,7 @@ class ObservabilityContext:
         Returns
         -------
         str
-            The hexadecimal representation of the trace ID
+            The string representation of the trace ID
 
         Raises
         ------
@@ -542,12 +448,10 @@ class ObservabilityContext:
             If called outside of any scope context
         """
         try:
-            return (
-                cls._context.get()
-                .observability.trace_identifying(
+            return str(
+                cls._context.get().observability.trace_identifying(
                     scope_identifier if scope_identifier is not None else ScopeIdentifier.current()
                 )
-                .hex
             )
 
         except LookupError as exc:
@@ -728,55 +632,31 @@ class ObservabilityContext:
                 exception=exc,
             )
 
-    __slots__ = (
-        "_scope",
-        "_token",
-        "observability",
-    )
+    _scope: ScopeIdentifier
+    observability: Observability
+    _token: Token[Self] | None = None
 
     def __init__(
         self,
         scope: ScopeIdentifier,
         observability: Observability | None,
     ) -> None:
-        self._scope: ScopeIdentifier
         object.__setattr__(
             self,
             "_scope",
             scope,
         )
-        self.observability: Observability
         object.__setattr__(
             self,
             "observability",
             observability,
         )
-        self._token: Token[ObservabilityContext] | None
         object.__setattr__(
             self,
             "_token",
             None,
         )
 
-    def __setattr__(
-        self,
-        name: str,
-        value: Any,
-    ) -> Any:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be modified"
-        )
-
-    def __delattr__(
-        self,
-        name: str,
-    ) -> None:
-        raise AttributeError(
-            f"Can't modify immutable {self.__class__.__qualname__},"
-            f" attribute - '{name}' cannot be deleted"
-        )
-
     def __enter__(self) -> None:
         """
         Enter this observability context.
@@ -822,7 +702,7 @@ class ObservabilityContext:
             If the context is not active
         """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
-        ObservabilityContext._context.reset(self._token)
+        ObservabilityContext._context.reset(self._token)  # pyright: ignore[reportArgumentType]
         object.__setattr__(
             self,
             "_token",