haiway 0.19.4__py3-none-any.whl → 0.20.0__py3-none-any.whl

haiway/__init__.py

@@ -13,6 +13,7 @@ from haiway.context import (
     ObservabilityMetricRecording,
     ObservabilityScopeEntering,
     ObservabilityScopeExiting,
+    ObservabilityTraceIdentifying,
     ScopeContext,
     ScopeIdentifier,
     StateContext,
@@ -22,6 +23,7 @@ from haiway.helpers import (
     LoggerObservability,
     asynchronous,
     cache,
+    process_concurrently,
     retry,
     throttle,
     timeout,
@@ -86,6 +88,7 @@ __all__ = (
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",
+    "ObservabilityTraceIdentifying",
     "ScopeContext",
     "ScopeIdentifier",
     "State",
@@ -112,6 +115,7 @@ __all__ = (
     "mimic_function",
     "noop",
     "not_missing",
+    "process_concurrently",
     "retry",
     "setup_logging",
     "throttle",

haiway/context/__init__.py

@@ -12,6 +12,7 @@ from haiway.context.observability import (
     ObservabilityMetricRecording,
     ObservabilityScopeEntering,
     ObservabilityScopeExiting,
+    ObservabilityTraceIdentifying,
 )
 from haiway.context.state import StateContext
 from haiway.context.types import MissingContext, MissingState
@@ -31,6 +32,7 @@ __all__ = (
     "ObservabilityMetricRecording",
     "ObservabilityScopeEntering",
     "ObservabilityScopeExiting",
+    "ObservabilityTraceIdentifying",
     "ScopeContext",
     "ScopeIdentifier",
     "StateContext",

haiway/context/access.py

@@ -36,6 +36,17 @@ __all__ = ("ctx",)
 
 @final
 class ScopeContext:
+    """
+    Context manager for executing code within a defined scope.
+
+    ScopeContext manages scope-related data and behavior including identity, state,
+    observability, and task coordination. It enforces immutability and provides both
+    synchronous and asynchronous context management interfaces.
+
+    This class should not be instantiated directly; use the ctx.scope() factory method
+    to create scope contexts.
+    """
+
     __slots__ = (
         "_disposables",
         "_identifier",
@@ -118,7 +129,7 @@ class ScopeContext:
         self._observability_context.__enter__()
         self._state_context.__enter__()
 
-        return self._identifier.trace_id
+        return self._observability_context.observability.trace_identifying(self._identifier).hex
 
     def __exit__(
         self,
@@ -167,7 +178,7 @@ class ScopeContext:
 
         self._state_context.__enter__()
 
-        return self._identifier.trace_id
+        return self._observability_context.observability.trace_identifying(self._identifier).hex
 
     async def __aexit__(
         self,
@@ -248,15 +259,44 @@ class ScopeContext:
 
 @final
 class ctx:
+    """
+    Static access to the current scope context.
+
+    Provides static methods for accessing and manipulating the current scope context,
+    including creating scopes, accessing state, logging, and task management.
+
+    This class is not meant to be instantiated; all methods are static.
+    """
+
     __slots__ = ()
 
     @staticmethod
-    def trace_id() -> str:
-        """
-        Get the current context trace identifier.
+    def trace_id(
+        scope_identifier: ScopeIdentifier | None = None,
+    ) -> str:
         """
+        Get the trace identifier for the specified scope or current scope.
 
-        return ScopeIdentifier.current_trace_id()
+        The trace identifier is a unique identifier that can be used to correlate
+        logs, events, and metrics across different components and services.
+
+        Parameters
+        ----------
+        scope_identifier: ScopeIdentifier | None, default=None
+            The scope identifier to get the trace ID for. If None, the current scope's
+            trace ID is returned.
+
+        Returns
+        -------
+        str
+            The hexadecimal representation of the trace ID
+
+        Raises
+        ------
+        RuntimeError
+            If called outside of any scope context
+        """
+        return ObservabilityContext.trace_id(scope_identifier)
 
     @staticmethod
     def scope(
@@ -420,6 +460,14 @@ class ctx:
     def check_cancellation() -> None:
         """
         Check if current asyncio task is cancelled, raises CancelledError if so.
+
+        Allows cooperative cancellation by checking and responding to cancellation
+        requests at appropriate points in the code.
+
+        Raises
+        ------
+        CancelledError
+            If the current task has been cancelled
         """
 
         if (task := current_task()) and task.cancelled():
@@ -428,7 +476,15 @@ class ctx:
     @staticmethod
     def cancel() -> None:
         """
-        Cancel current asyncio task
+        Cancel current asyncio task.
+
+        Cancels the current running asyncio task. This will result in a CancelledError
+        being raised in the task.
+
+        Raises
+        ------
+        RuntimeError
+            If called outside of an asyncio task
         """
 
         if task := current_task():
@@ -605,7 +661,31 @@ class ctx:
         /,
         *,
         attributes: Mapping[str, ObservabilityAttribute],
-    ) -> None: ...
+    ) -> None:
+        """
+        Record observability data within the current scope context.
+
+        This method has three different forms:
+        1. Record standalone attributes
+        2. Record a named event with optional attributes
+        3. Record a metric with a value and optional unit and attributes
+
+        Parameters
+        ----------
+        level: ObservabilityLevel
+            Severity level for the recording (default: DEBUG)
+        attributes: Mapping[str, ObservabilityAttribute]
+            Key-value attributes to record
+        event: str
+            Name of the event to record
+        metric: str
+            Name of the metric to record
+        value: float | int
+            Numeric value of the metric
+        unit: str | None
+            Optional unit for the metric
+        """
+        ...
 
     @overload
     @staticmethod

haiway/context/disposables.py

@@ -13,16 +13,41 @@ __all__ = (
 )
 
 type Disposable = AbstractAsyncContextManager[Iterable[State] | State | None]
+"""
+A type alias for asynchronous context managers that can be disposed.
+
+Represents an asynchronous resource that needs proper cleanup when no longer needed.
+When entered, it may return State instances that will be propagated to the context.
+"""
 
 
 @final
 class Disposables:
+    """
+    A container for multiple Disposable resources that manages their lifecycle.
+
+    This class provides a way to handle multiple disposable resources as a single unit,
+    entering all of them when the container is entered and exiting all of them when
+    the container is exited. Any states returned by the disposables are collected
+    and returned as a unified collection.
+
+    The class is immutable after initialization.
+    """
+
     __slots__ = ("_disposables",)
 
     def __init__(
         self,
         *disposables: Disposable,
     ) -> None:
+        """
+        Initialize a collection of disposable resources.
+
+        Parameters
+        ----------
+        *disposables: Disposable
+            Variable number of disposable resources to be managed together.
+        """
         self._disposables: tuple[Disposable, ...]
         object.__setattr__(
             self,
@@ -50,6 +75,14 @@ class Disposables:
         )
 
     def __bool__(self) -> bool:
+        """
+        Check if this container has any disposables.
+
+        Returns
+        -------
+        bool
+            True if there are disposables, False otherwise.
+        """
         return len(self._disposables) > 0
 
     async def _initialize(
@@ -68,6 +101,16 @@ class Disposables:
                 return multiple
 
     async def __aenter__(self) -> Iterable[State]:
+        """
+        Enter all contained disposables asynchronously.
+
+        Enters all disposables in parallel and collects any State objects they return.
+
+        Returns
+        -------
+        Iterable[State]
+            Collection of State objects from all disposables.
+        """
         return [
             *chain.from_iterable(
                 state
@@ -83,6 +126,26 @@ class Disposables:
         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.
+
+        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
+        """
         results: list[bool | BaseException | None] = await gather(
             *[
                 disposable.__aexit__(

haiway/context/identifier.py

@@ -1,22 +1,31 @@
 from contextvars import ContextVar, Token
 from types import TracebackType
 from typing import Any, Self, final
-from uuid import uuid4
+from uuid import UUID, uuid4
 
 __all__ = ("ScopeIdentifier",)
 
 
 @final
 class ScopeIdentifier:
+    """
+    Identifies and manages scope context identities.
+
+    ScopeIdentifier maintains a context-local scope identity including
+    scope ID, and parent ID. It provides a hierarchical structure for tracking
+    execution scopes, supporting both root scopes and nested child scopes.
+
+    This class is immutable after instantiation.
+    """
+
     _context = ContextVar[Self]("ScopeIdentifier")
 
     @classmethod
-    def current_trace_id(cls) -> str:
-        try:
-            return ScopeIdentifier._context.get().trace_id
-
-        except LookupError as exc:
-            raise RuntimeError("Attempting to access scope identifier outside of scope") from exc
+    def current(
+        cls,
+        /,
+    ) -> Self:
+        return cls._context.get()
 
     @classmethod
     def scope(
@@ -24,27 +33,41 @@ class ScopeIdentifier:
         label: str,
         /,
     ) -> Self:
+        """
+        Create a new scope identifier.
+
+        If called within an existing scope, creates a nested scope with a new ID.
+        If called outside any scope, creates a root scope with new scope ID.
+
+        Parameters
+        ----------
+        label: str
+            The name of the scope
+
+        Returns
+        -------
+        Self
+            A newly created scope identifier
+        """
         current: Self
         try:  # check for current scope
             current = cls._context.get()
 
         except LookupError:
             # create root scope when missing
-            trace_id: str = uuid4().hex
-            scope_id: str = uuid4().hex
+
+            scope_id: UUID = uuid4()
             return cls(
                 label=label,
                 scope_id=scope_id,
                 parent_id=scope_id,  # own id is parent_id for root
-                trace_id=trace_id,
             )
 
         # create nested scope otherwise
         return cls(
             label=label,
-            scope_id=uuid4().hex,
+            scope_id=uuid4(),
             parent_id=current.scope_id,
-            trace_id=current.trace_id,
         )
 
     __slots__ = (
@@ -52,30 +75,22 @@ class ScopeIdentifier:
         "label",
         "parent_id",
         "scope_id",
-        "trace_id",
         "unique_name",
     )
 
     def __init__(
         self,
-        trace_id: str,
-        parent_id: str,
-        scope_id: str,
+        parent_id: UUID,
+        scope_id: UUID,
         label: str,
     ) -> None:
-        self.trace_id: str
-        object.__setattr__(
-            self,
-            "trace_id",
-            trace_id,
-        )
-        self.parent_id: str
+        self.parent_id: UUID
         object.__setattr__(
             self,
             "parent_id",
             parent_id,
         )
-        self.scope_id: str
+        self.scope_id: UUID
         object.__setattr__(
             self,
             "scope_id",
@@ -91,7 +106,7 @@ class ScopeIdentifier:
         object.__setattr__(
             self,
             "unique_name",
-            f"[{trace_id}] [{label}] [{scope_id}]",
+            f"[{label}] [{scope_id.hex}]",
         )
         self._token: Token[ScopeIdentifier] | None
         object.__setattr__(
@@ -121,7 +136,17 @@ class ScopeIdentifier:
 
     @property
     def is_root(self) -> bool:
-        return self.trace_id == self.parent_id
+        """
+        Check if this scope is a root scope.
+
+        A root scope is one that was created outside of any other scope.
+
+        Returns
+        -------
+        bool
+            True if this is a root scope, False if it's a nested scope
+        """
+        return self.scope_id == self.parent_id
 
     def __str__(self) -> str:
         return self.unique_name
@@ -130,12 +155,22 @@ class ScopeIdentifier:
         if not isinstance(other, self.__class__):
             return False
 
-        return self.scope_id == other.scope_id and self.trace_id == other.trace_id
+        return self.scope_id == other.scope_id
 
     def __hash__(self) -> int:
         return hash(self.scope_id)
 
     def __enter__(self) -> None:
+        """
+        Enter this scope identifier's context.
+
+        Sets this identifier as the current scope identifier in the context.
+
+        Raises
+        ------
+        AssertionError
+            If this context is already active
+        """
         assert self._token is None, "Context reentrance is not allowed"  # nosec: B101
         object.__setattr__(
             self,
@@ -149,6 +184,25 @@ class ScopeIdentifier:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        """
+        Exit this scope identifier's context.
+
+        Restores the previous scope identifier in the context.
+
+        Parameters
+        ----------
+        exc_type: type[BaseException] | None
+            Type of exception that caused the exit
+        exc_val: BaseException | None
+            Exception instance that caused the exit
+        exc_tb: TracebackType | None
+            Traceback for the exception
+
+        Raises
+        ------
+        AssertionError
+            If this context is not active
+        """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
         ScopeIdentifier._context.reset(self._token)
         object.__setattr__(