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

haiway/context/tasks.py

@@ -9,6 +9,14 @@ __all__ = ("TaskGroupContext",)
 
 @final
 class TaskGroupContext:
+    """
+    Context manager for managing task groups within a scope.
+
+    Provides a way to create and manage asyncio tasks within a context,
+    ensuring proper task lifecycle management and context propagation.
+    This class is immutable after initialization.
+    """
+
     _context = ContextVar[TaskGroup]("TaskGroupContext")
 
     @classmethod
@@ -19,6 +27,26 @@ class TaskGroupContext:
         *args: Arguments.args,
         **kwargs: Arguments.kwargs,
     ) -> Task[Result]:
+        """
+        Run a coroutine function as a task within the current task group.
+
+        If called within a TaskGroupContext, creates a task in that group.
+        If called outside any TaskGroupContext, creates a detached task.
+
+        Parameters
+        ----------
+        function: Callable[Arguments, Coroutine[Any, Any, Result]]
+            The coroutine function to run
+        *args: Arguments.args
+            Positional arguments to pass to the function
+        **kwargs: Arguments.kwargs
+            Keyword arguments to pass to the function
+
+        Returns
+        -------
+        Task[Result]
+            The created task
+        """
         try:
             return cls._context.get().create_task(
                 function(*args, **kwargs),
@@ -40,6 +68,14 @@ class TaskGroupContext:
         self,
         task_group: TaskGroup | None = None,
     ) -> None:
+        """
+        Initialize a task group context.
+
+        Parameters
+        ----------
+        task_group: TaskGroup | None
+            The task group to use, or None to create a new one
+        """
         self._group: TaskGroup
         object.__setattr__(
             self,
@@ -73,6 +109,16 @@ class TaskGroupContext:
         )
 
     async def __aenter__(self) -> None:
+        """
+        Enter this task group context.
+
+        Enters the underlying task group and sets this context as current.
+
+        Raises
+        ------
+        AssertionError
+            If attempting to re-enter an already active context
+        """
         assert self._token is None, "Context reentrance is not allowed"  # nosec: B101
         await self._group.__aenter__()
         object.__setattr__(
@@ -87,6 +133,26 @@ class TaskGroupContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        """
+        Exit this task group context.
+
+        Restores the previous task group context and exits the underlying task group.
+        Silently ignores task group exceptions to avoid masking existing exceptions.
+
+        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 the context is not active
+        """
         assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
         TaskGroupContext._context.reset(self._token)
         object.__setattr__(

haiway/context/types.py

@@ -5,8 +5,24 @@ __all__ = (
 
 
 class MissingContext(Exception):
+    """
+    Exception raised when attempting to access a context that doesn't exist.
+
+    This exception is raised when code attempts to access the context system
+    outside of an active context, such as trying to access state or scope
+    identifiers when no context has been established.
+    """
+
     pass
 
 
 class MissingState(Exception):
+    """
+    Exception raised when attempting to access state that doesn't exist.
+
+    This exception is raised when code attempts to access a specific state type
+    that is not present in the current context and cannot be automatically
+    created (either because no default was provided or instantiation failed).
+    """
+
     pass

haiway/helpers/__init__.py

@@ -1,5 +1,6 @@
 from haiway.helpers.asynchrony import asynchronous, wrap_async
 from haiway.helpers.caching import CacheMakeKey, CacheRead, CacheWrite, cache
+from haiway.helpers.concurrent import process_concurrently
 from haiway.helpers.observability import LoggerObservability
 from haiway.helpers.retries import retry
 from haiway.helpers.throttling import throttle
@@ -13,6 +14,7 @@ __all__ = (
     "LoggerObservability",
     "asynchronous",
     "cache",
+    "process_concurrently",
     "retry",
     "throttle",
     "timeout",

haiway/helpers/asynchrony.py

@@ -17,6 +17,24 @@ def wrap_async[**Args, Result](
     function: Callable[Args, Coroutine[Any, Any, Result]] | Callable[Args, Result],
     /,
 ) -> Callable[Args, Coroutine[Any, Any, Result]]:
+    """
+    Convert a synchronous function to an asynchronous one if it isn't already.
+
+    Takes a function that may be either synchronous or asynchronous and ensures it
+    returns a coroutine. If the input function is already asynchronous, it is returned
+    unchanged. If it's synchronous, it wraps it in an async function that executes
+    the original function and returns its result.
+
+    Parameters
+    ----------
+    function: Callable[Args, Coroutine[Any, Any, Result]] | Callable[Args, Result]
+        The function to ensure is asynchronous, can be either sync or async
+
+    Returns
+    -------
+    Callable[Args, Coroutine[Any, Any, Result]]
+        An asynchronous function that returns a coroutine
+    """
     if iscoroutinefunction(function):
         return function
 
@@ -57,6 +75,7 @@ def asynchronous[**Args, Result](
 def asynchronous[**Args, Result](
     function: Callable[Args, Result] | None = None,
     /,
+    *,
     loop: AbstractEventLoop | None = None,
     executor: Executor | Missing = MISSING,
 ) -> (
@@ -66,26 +85,56 @@ def asynchronous[**Args, Result](
     ]
     | Callable[Args, Coroutine[Any, Any, Result]]
 ):
-    """\
-    Wrapper for a sync function to convert it to an async function. \
-    When specified an executor, it can be used to wrap long running or blocking synchronous \
-    operations within coroutines system.
+    """
+    Convert a synchronous function to an asynchronous one that runs in an executor.
+
+    This decorator transforms synchronous, potentially blocking functions into
+    asynchronous coroutines that execute in an event loop's executor, allowing
+    them to be used with async/await syntax without blocking the event loop.
+
+    Can be used as a simple decorator (@asynchronous) or with configuration
+    parameters (@asynchronous(executor=my_executor)).
 
     Parameters
     ----------
-    function: Callable[Args, Result]
-        function to be wrapped as running in loop executor.
+    function: Callable[Args, Result] | None
+        The synchronous function to be wrapped. When used as a simple decorator,
+        this parameter is provided automatically.
     loop: AbstractEventLoop | None
-        loop used to call the function. When None was provided the loop currently running while \
-        executing the function will be used. Default is None.
+        The event loop to run the function in. When None is provided, the currently
+        running loop while executing the function will be used. Default is None.
     executor: Executor | Missing
-        executor used to run the function. When not provided (Missing) default loop executor\
-         will be used.
+        The executor used to run the function. When not provided, the default loop
+        executor will be used. Useful for CPU-bound tasks or operations that would
+        otherwise block the event loop.
 
     Returns
     -------
-    Callable[_Args, _Result]
-        function wrapped to async using loop executor.
+    Callable
+        When used as @asynchronous: Returns the wrapped function that can be awaited.
+        When used as @asynchronous(...): Returns a decorator that can be applied to a function.
+
+    Notes
+    -----
+    The function preserves the original function's signature, docstring, and other attributes.
+    Context variables from the calling context are preserved when executing in the executor.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> @asynchronous
+    ... def cpu_intensive_task(data):
+    ...     # This runs in the default executor
+    ...     return process_data(data)
+    ...
+    >>> await cpu_intensive_task(my_data)  # Non-blocking
+
+    With custom executor:
+
+    >>> @asynchronous(executor=process_pool)
+    ... def cpu_intensive_task(data):
+    ...     return process_data(data)
     """
 
     def wrap(

haiway/helpers/caching.py

@@ -17,6 +17,17 @@ __all__ = (
 
 
 class CacheMakeKey[**Args, Key](Protocol):
+    """
+    Protocol for generating cache keys from function arguments.
+
+    Implementations of this protocol are responsible for creating a unique key
+    based on the arguments passed to a function, which can then be used for
+    cache lookups.
+
+    The key must be consistent for the same set of arguments, and different
+    for different sets of arguments that should be cached separately.
+    """
+
     def __call__(
         self,
         *args: Args.args,
@@ -25,6 +36,16 @@ class CacheMakeKey[**Args, Key](Protocol):
 
 
 class CacheRead[Key, Value](Protocol):
+    """
+    Protocol for reading values from a cache.
+
+    Implementations of this protocol are responsible for retrieving cached values
+    based on a key. If the key is not present in the cache, None should be returned.
+
+    This is designed as an asynchronous operation to support remote caches where
+    retrieval might involve network operations.
+    """
+
     async def __call__(
         self,
         key: Key,
@@ -32,6 +53,16 @@ class CacheRead[Key, Value](Protocol):
 
 
 class CacheWrite[Key, Value](Protocol):
+    """
+    Protocol for writing values to a cache.
+
+    Implementations of this protocol are responsible for storing values in a cache
+    using the specified key. Any existing value with the same key should be overwritten.
+
+    This is designed as an asynchronous operation to support remote caches where
+    writing might involve network operations.
+    """
+
     async def __call__(
         self,
         key: Key,

haiway/helpers/concurrent.py

@@ -0,0 +1,74 @@
+from asyncio import FIRST_COMPLETED, CancelledError, Task, wait
+from collections.abc import AsyncIterator, Callable, Coroutine
+from concurrent.futures import ALL_COMPLETED
+from typing import Any
+
+from haiway.context import ctx
+
+__all__ = ("process_concurrently",)
+
+
+async def process_concurrently[Element](  # noqa: C901
+    source: AsyncIterator[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, None]],
+    *,
+    concurrent_tasks: int = 2,
+    ignore_exceptions: bool = False,
+) -> None:
+    """Process elements from an async iterator concurrently.
+
+    Parameters
+    ----------
+    source: AsyncIterator[Element]
+        An async iterator providing elements to process.
+
+    handler: Callable[[Element], Coroutine[Any, Any, None]]
+        A coroutine function that processes each element.
+
+    concurrent_tasks: int
+        Maximum number of concurrent tasks (must be > 0), default is 2.
+
+    ignore_exceptions: bool
+        If True, exceptions from tasks will be logged but not propagated,
+         default is False.
+
+    """
+    assert concurrent_tasks > 0  # nosec: B101
+    running: set[Task[None]] = set()
+    try:
+        while element := await anext(source, None):
+            if len(running) < concurrent_tasks:
+                running.add(ctx.spawn(handler, element))
+                continue  # keep spawning tasks
+
+            completed, running = await wait(running, return_when=FIRST_COMPLETED)
+
+            for task in completed:
+                if exc := task.exception():
+                    if not ignore_exceptions:
+                        raise exc
+
+                    ctx.log_error(
+                        f"Concurrent processing error - {type(exc)}: {exc}",
+                        exception=exc,
+                    )
+
+    except CancelledError as exc:
+        # Cancel all running tasks
+        for task in running:
+            task.cancel()
+
+        raise exc
+
+    finally:
+        completed, _ = await wait(running, return_when=ALL_COMPLETED)
+        for task in completed:
+            if exc := task.exception():
+                if not ignore_exceptions:
+                    raise exc
+
+                ctx.log_error(
+                    f"Concurrent processing error - {type(exc)}: {exc}",
+                    exception=exc,
+                )

haiway/helpers/observability.py

@@ -2,6 +2,7 @@ from collections.abc import Mapping
 from logging import Logger, getLogger
 from time import monotonic
 from typing import Any
+from uuid import UUID, uuid4
 
 from haiway.context import Observability, ObservabilityLevel, ScopeIdentifier
 from haiway.context.observability import ObservabilityAttribute
@@ -12,6 +13,13 @@ __all__ = ("LoggerObservability",)
 
 
 class ScopeStore:
+    """
+    Internal class for storing scope information during observability tracking.
+
+    Tracks timing information, nested scopes, and recorded events for a specific scope.
+    Used by LoggerObservability to maintain the hierarchy of scopes and their data.
+    """
+
     __slots__ = (
         "_completed",
         "_exited",
@@ -35,21 +43,44 @@ class ScopeStore:
 
     @property
     def time(self) -> float:
+        """Calculate the elapsed time in seconds since this scope was entered."""
         return (self._completed or monotonic()) - self.entered
 
     @property
     def exited(self) -> bool:
+        """Check if this scope has been exited."""
         return self._exited is not None
 
     def exit(self) -> None:
+        """Mark this scope as exited and record the exit time."""
         assert self._exited is None  # nosec: B101
         self._exited = monotonic()
 
     @property
     def completed(self) -> bool:
+        """
+        Check if this scope and all its nested scopes are completed.
+
+        A scope is considered completed when it has been exited and all its
+        nested scopes have also been completed.
+        """
         return self._completed is not None and all(nested.completed for nested in self.nested)
 
     def try_complete(self) -> bool:
+        """
+        Try to mark this scope as completed.
+
+        A scope can only be completed if:
+        - It has been exited
+        - It has not already been completed
+        - All its nested scopes are completed
+
+        Returns
+        -------
+        bool
+            True if the scope was successfully marked as completed,
+            False if any completion condition was not met
+        """
         if self._exited is None:
             return False  # not elegible for completion yet
 
@@ -69,9 +100,47 @@ def LoggerObservability(  # noqa: C901, PLR0915
     *,
     debug_context: bool = __debug__,
 ) -> Observability:
+    """
+    Create an Observability implementation that uses a standard Python logger.
+
+    This factory function creates an Observability instance that uses a Logger for recording
+    various types of observability data including logs, events, metrics, and attributes.
+    It maintains a hierarchical scope structure that tracks timing information and provides
+    a summary of all recorded data when the root scope exits.
+
+    Parameters
+    ----------
+    logger: Logger | None
+        The logger to use for recording observability data. If None, a logger will be
+        created based on the scope label when the first scope is entered.
+    debug_context: bool
+        Whether to store and display a detailed hierarchical summary when the root scope
+        exits. Defaults to True in debug mode (__debug__) and False otherwise.
+
+    Returns
+    -------
+    Observability
+        An Observability instance that uses the specified logger (or a default one)
+        for recording observability data.
+
+    Notes
+    -----
+    The created Observability instance tracks timing for each scope and records it
+    when the scope exits. When the root scope exits and debug_context is True,
+    it produces a hierarchical summary of all recorded events, metrics, and attributes.
+    """
     root_scope: ScopeIdentifier | None = None
     root_logger: Logger | None = logger
-    scopes: dict[str, ScopeStore] = {}
+    scopes: dict[UUID, ScopeStore] = {}
+
+    trace_id: UUID = uuid4()
+    trace_id_hex: str = trace_id.hex
+
+    def trace_identifying(
+        scope: ScopeIdentifier,
+        /,
+    ) -> UUID:
+        return trace_id
 
     def log_recording(
         scope: ScopeIdentifier,
@@ -87,7 +156,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             level,
-            f"{scope.unique_name} {message}",
+            f"[{trace_id_hex}] {scope.unique_name} {message}",
             *args,
             exc_info=exception,
         )
@@ -110,7 +179,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             level,
-            f"{scope.unique_name} {event_str}",
+            f"[{trace_id_hex}] {scope.unique_name} {event_str}",
         )
 
     def metric_recording(
@@ -129,17 +198,17 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         metric_str: str
         if attributes:
-            metric_str = f"Metric: {metric} = {value}{unit or ''}\n{format_str(attributes)}"
+            metric_str = f"Metric: {metric} = {value} {unit or ''}\n{format_str(attributes)}"
 
         else:
-            metric_str = f"Metric: {metric} = {value}{unit or ''}"
+            metric_str = f"Metric: {metric} = {value} {unit or ''}"
 
         if debug_context:  # store only for summary
             scopes[scope.scope_id].store.append(metric_str)
 
         root_logger.log(
             level,
-            f"{scope.unique_name} {metric_str}",
+            f"[{trace_id_hex}] {scope.unique_name} {metric_str}",
         )
 
     def attributes_recording(
@@ -160,7 +229,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             level,
-            attributes_str,
+            f"[{trace_id_hex}] {scope.unique_name} {attributes_str}",
         )
 
     def scope_entering[Metric: State](
@@ -183,7 +252,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
         assert root_logger is not None  # nosec: B101
         root_logger.log(
             ObservabilityLevel.INFO,
-            f"{scope.unique_name} Entering scope: {scope.label}",
+            f"[{trace_id_hex}] {scope.unique_name} Entering scope: {scope.label}",
         )
 
     def scope_exiting[Metric: State](
@@ -206,7 +275,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             ObservabilityLevel.INFO,
-            f"{scope.unique_name} Exiting scope: {scope.label}",
+            f"[{trace_id_hex}] {scope.unique_name} Exiting scope: {scope.label}",
         )
         metric_str: str = f"Metric - scope_time:{scopes[scope.scope_id].time:.3f}s"
         if debug_context:  # store only for summary
@@ -214,12 +283,12 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             ObservabilityLevel.INFO,
-            f"{scope.unique_name} {metric_str}",
+            f"[{trace_id_hex}] {scope.unique_name} {metric_str}",
         )
 
         # try complete parent scopes
         if scope != root_scope:
-            parent_id: str = scope.parent_id
+            parent_id: UUID = scope.parent_id
             while scopes[parent_id].try_complete():
                 if scopes[parent_id].identifier == root_scope:
                     break
@@ -240,6 +309,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
             scopes = {}
 
     return Observability(
+        trace_identifying=trace_identifying,
         log_recording=log_recording,
         event_recording=event_recording,
         metric_recording=metric_recording,
@@ -250,6 +320,19 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
 
 def _tree_summary(scope_store: ScopeStore) -> str:
+    """
+    Generate a hierarchical text representation of a scope and its nested scopes.
+
+    Parameters
+    ----------
+    scope_store: ScopeStore
+        The scope store to generate a summary for
+
+    Returns
+    -------
+    str
+        A formatted string representation of the scope hierarchy with recorded events
+    """
     elements: list[str] = [
         f"┍━ {scope_store.identifier.label} [{scope_store.identifier.scope_id}]:"
     ]

haiway/helpers/retries.py

@@ -72,32 +72,73 @@ def retry[**Args, Result](
     delay: Callable[[int, Exception], float] | float | None = None,
     catching: set[type[Exception]] | tuple[type[Exception], ...] | type[Exception] = Exception,
 ) -> Callable[[Callable[Args, Result]], Callable[Args, Result]] | Callable[Args, Result]:
-    """\
-    Function wrapper retrying the wrapped function again on fail. \
-    Works for both sync and async functions. \
-    It is not allowed to be used on class methods. \
-    This wrapper is not thread safe.
+    """
+    Automatically retry a function on failure.
+
+    This decorator attempts to execute a function and, if it fails with a specified
+    exception type, retries the execution up to a configurable number of times,
+    with an optional delay between attempts.
+
+    Can be used as a simple decorator (@retry) or with configuration
+    parameters (@retry(limit=3, delay=1.0)).
 
     Parameters
     ----------
-    function: Callable[_Args_T, _Result_T]
-        function to wrap in auto retry, either sync or async.
+    function: Callable[Args, Result] | None
+        The function to wrap with retry logic. When used as a simple decorator,
+        this parameter is provided automatically.
     limit: int
-        limit of retries, default is 1
+        Maximum number of retry attempts. Default is 1, meaning the function
+        will be called at most twice (initial attempt + 1 retry).
     delay: Callable[[int, Exception], float] | float | None
-        retry delay time in seconds, either concrete value or a function producing it, \
-        default is None (no delay)
-    catching: set[type[Exception]] | type[Exception] | None
-        Exception types that are triggering auto retry. Retry will trigger only when \
-        exceptions of matching types (including subclasses) will occur. CancelledError \
-        will be always propagated even if specified explicitly.
-        Default is Exception - all subclasses of Exception will be handled.
+        Delay between retry attempts in seconds. Can be:
+          - None: No delay between retries (default)
+          - float: Fixed delay in seconds
+          - Callable: A function that calculates delay based on attempt number
+            and the caught exception, allowing for backoff strategies
+    catching: set[type[Exception]] | tuple[type[Exception], ...] | type[Exception]
+        Exception types that should trigger retry. Can be a single exception type,
+        a set, or a tuple of exception types. Default is Exception (all exception
+        types except for CancelledError, which is always propagated).
 
     Returns
     -------
-    Callable[[Callable[_Args_T, _Result_T]], Callable[_Args_T, _Result_T]] | \
-    Callable[_Args_T, _Result_T]
-        function wrapper for adding auto retry or a wrapped function
+    Callable
+        When used as @retry: Returns the wrapped function with retry logic.
+        When used as @retry(...): Returns a decorator that can be applied to a function.
+
+    Notes
+    -----
+    - Works with both synchronous and asynchronous functions.
+    - Not thread-safe; concurrent invocations are not coordinated.
+    - Cannot be used on class methods.
+    - Always propagates asyncio.CancelledError regardless of catching parameter.
+    - The function preserves the original function's signature, docstring, and other attributes.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> @retry
+    ... def fetch_data():
+    ...     # Will retry once if any exception occurs
+    ...     return external_api.fetch()
+
+    With configuration:
+
+    >>> @retry(limit=3, delay=2.0, catching=ConnectionError)
+    ... async def connect():
+    ...     # Will retry up to 3 times with 2 second delays on ConnectionError
+    ...     return await establish_connection()
+
+    With exponential backoff:
+
+    >>> def backoff(attempt, exception):
+    ...     return 0.5 * (2 ** attempt)  # 1s, 2s, 4s, ...
+    ...
+    >>> @retry(limit=5, delay=backoff)
+    ... def unreliable_operation():
+    ...     return perform_operation()
     """
 
     def _wrap(