haiway 0.24.2__py3-none-any.whl → 0.25.0__py3-none-any.whl

haiway/context/presets.py

@@ -0,0 +1,337 @@
+from collections.abc import Collection, Iterable, Mapping
+from contextvars import ContextVar, Token
+from types import TracebackType
+from typing import ClassVar, Protocol, Self, cast
+
+from haiway.context.disposables import Disposable, Disposables
+from haiway.state import Immutable, State
+from haiway.types.default import Default
+
+__all__ = (
+    "ContextPresets",
+    "ContextPresetsRegistry",
+    "ContextPresetsRegistryContext",
+)
+
+
+class ContextPresetsStatePreparing(Protocol):
+    async def __call__(self) -> Iterable[State] | State: ...
+
+
+class ContextPresetsDisposablesPreparing(Protocol):
+    async def __call__(self) -> Iterable[Disposable] | Disposable: ...
+
+
+class ContextPresets(Immutable):
+    """
+    A configuration preset for context scopes.
+
+    ContextPresets allow you to define reusable combinations of state and disposables
+    that can be applied to scopes by name. This provides a convenient way to manage
+    complex application configurations and resource setups.
+
+    State Priority
+    --------------
+    When used with ctx.scope(), preset state has lower priority than explicit state:
+    1. Explicit state (passed to ctx.scope()) - **highest priority**
+    2. Explicit disposables (passed to ctx.scope()) - medium priority
+    3. Preset state (from presets) - low priority
+    4. Contextual state (from parent contexts) - **lowest priority**
+
+    Examples
+    --------
+    Basic preset with static state:
+
+    >>> from haiway import State
+    >>> from haiway.context import ContextPresets
+    >>>
+    >>> class DatabaseConfig(State):
+    ...     connection_string: str
+    ...     pool_size: int = 10
+    >>>
+    >>> db_preset = ContextPresets(
+    ...     name="database",
+    ...     _state=[DatabaseConfig(connection_string="postgresql://localhost/app")]
+    ... )
+
+    Preset with dynamic state factory:
+
+    >>> async def load_config() -> DatabaseConfig:
+    ...     # Load configuration from environment or config file
+    ...     return DatabaseConfig(connection_string=os.getenv("DB_URL"))
+    >>>
+    >>> dynamic_preset = ContextPresets(
+    ...     name="dynamic_db",
+    ...     _state=[load_config]
+    ... )
+
+    Preset with disposables:
+
+    >>> from contextlib import asynccontextmanager
+    >>>
+    >>> @asynccontextmanager
+    >>> async def database_connection():
+    ...     conn = await create_connection()
+    ...     try:
+    ...         yield ConnectionState(connection=conn)
+    ...     finally:
+    ...         await conn.close()
+    >>>
+    >>> async def connection_factory():
+    ...     return database_connection()
+    >>>
+    >>> db_preset = ContextPresets(
+    ...     name="database",
+    ...     _state=[DatabaseConfig(connection_string="...")],
+    ...     _disposables=[connection_factory]
+    ... )
+
+    Using presets:
+
+    >>> from haiway import ctx
+    >>>
+    >>> with ctx.presets(db_preset):
+    ...     async with ctx.scope("database"):
+    ...         config = ctx.state(DatabaseConfig)
+    ...         # Use the preset configuration
+    """
+
+    name: str
+    _state: Collection[ContextPresetsStatePreparing | State] = Default(())
+    _disposables: Collection[ContextPresetsDisposablesPreparing] = Default(())
+
+    def extended(
+        self,
+        other: Self,
+    ) -> Self:
+        """
+        Create a new preset by extending this preset with another.
+
+        Combines the state and disposables from both presets, keeping the name
+        of the current preset. The other preset's state and disposables are
+        appended to this preset's collections.
+
+        Parameters
+        ----------
+        other : Self
+            Another ContextPresets instance to merge with this one.
+
+        Returns
+        -------
+        Self
+            A new ContextPresets instance with combined state and disposables.
+        """
+        return self.__class__(
+            name=self.name,
+            _state=(*self._state, *other._state),
+            _disposables=(*self._disposables, *other._disposables),
+        )
+
+    def with_state(
+        self,
+        *state: ContextPresetsStatePreparing | State,
+    ) -> Self:
+        """
+        Create a new preset with additional state.
+
+        Returns a new ContextPresets instance with the provided state objects
+        or state factories added to the existing state collection.
+
+        Parameters
+        ----------
+        *state : ContextPresetsStatePreparing | State
+            Additional state objects or state factory functions to include.
+
+        Returns
+        -------
+        Self
+            A new ContextPresets instance with the additional state, or the
+            same instance if no state was provided.
+        """
+        if not state:
+            return self
+
+        return self.__class__(
+            name=self.name,
+            _state=(*self._state, *state),
+            _disposables=self._disposables,
+        )
+
+    def with_disposable(
+        self,
+        *disposable: ContextPresetsDisposablesPreparing,
+    ) -> Self:
+        """
+        Create a new preset with additional disposables.
+
+        Returns a new ContextPresets instance with the provided disposable
+        factory functions added to the existing disposables collection.
+
+        Parameters
+        ----------
+        *disposable : ContextPresetsDisposablesPreparing
+            Additional disposable factory functions to include.
+
+        Returns
+        -------
+        Self
+            A new ContextPresets instance with the additional disposables, or the
+            same instance if no disposables were provided.
+        """
+        if not disposable:
+            return self
+
+        return self.__class__(
+            name=self.name,
+            _state=self._state,
+            _disposables=(*self._disposables, *disposable),
+        )
+
+    async def prepare(self) -> Disposables:
+        """
+        Prepare the preset for use by resolving all state and disposables.
+
+        This method evaluates all state factories and disposable factories to create
+        concrete instances. State objects are wrapped in a DisposableState to unify
+        the handling of state and disposable resources.
+
+        The method ensures concurrent safety by creating fresh instances each time
+        it's called, making it safe to use the same preset across multiple concurrent
+        scopes.
+
+        Returns
+        -------
+        Disposables
+            A Disposables container holding all resolved state (wrapped in DisposableState)
+            and disposable resources from this preset.
+
+        Note
+        ----
+        This method is called automatically when using presets with ctx.scope(),
+        so you typically don't need to call it directly.
+        """
+        # Collect states directly
+        collected_states: list[State] = []
+        for state in self._state:
+            if isinstance(state, State):
+                collected_states.append(state)
+            else:
+                resolved_state: Iterable[State] | State = await state()
+                if isinstance(resolved_state, State):
+                    collected_states.append(resolved_state)
+
+                else:
+                    collected_states.extend(resolved_state)
+
+        collected_disposables: list[Disposable]
+        if collected_states:
+            collected_disposables = [DisposableState(_state=collected_states)]
+
+        else:
+            collected_disposables = []
+
+        for disposable in self._disposables:
+            resolved_disposable: Iterable[Disposable] | Disposable = await disposable()
+            if hasattr(resolved_disposable, "__aenter__") and hasattr(
+                resolved_disposable, "__aexit__"
+            ):
+                collected_disposables.append(cast(Disposable, resolved_disposable))
+
+            else:
+                collected_disposables.extend(cast(Iterable[Disposable], resolved_disposable))
+
+        return Disposables(*collected_disposables)
+
+
+class DisposableState(Immutable):
+    _state: Iterable[State]
+
+    async def __aenter__(self) -> Iterable[State]:
+        return self._state
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        pass
+
+
+class ContextPresetsRegistry(Immutable):
+    _presets: Mapping[str, ContextPresets]
+
+    def __init__(
+        self,
+        presets: Collection[ContextPresets],
+    ) -> None:
+        object.__setattr__(
+            self,
+            "_presets",
+            {preset.name: preset for preset in presets},
+        )
+
+    def select(
+        self,
+        name: str,
+        /,
+    ) -> ContextPresets | None:
+        return self._presets.get(name)
+
+
+class ContextPresetsRegistryContext(Immutable):
+    _context: ClassVar[ContextVar[ContextPresetsRegistry]] = ContextVar[ContextPresetsRegistry](
+        "ContextPresetsRegistryContext"
+    )
+
+    @classmethod
+    def select(
+        cls,
+        name: str,
+        /,
+    ) -> ContextPresets | None:
+        try:
+            return cls._context.get().select(name)
+
+        except LookupError:
+            return None  # no presets
+
+    _registry: ContextPresetsRegistry
+    _token: Token[ContextPresetsRegistry] | None = None
+
+    def __init__(
+        self,
+        registry: ContextPresetsRegistry,
+    ) -> None:
+        object.__setattr__(
+            self,
+            "_registry",
+            registry,
+        )
+        object.__setattr__(
+            self,
+            "_token",
+            None,
+        )
+
+    def __enter__(self) -> None:
+        assert self._token is None, "Context reentrance is not allowed"  # nosec: B101
+        object.__setattr__(
+            self,
+            "_token",
+            ContextPresetsRegistryContext._context.set(self._registry),
+        )
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        assert self._token is not None, "Unbalanced context enter/exit"  # nosec: B101
+        ContextPresetsRegistryContext._context.reset(self._token)
+        object.__setattr__(
+            self,
+            "_token",
+            None,
+        )

haiway/context/state.py

@@ -1,12 +1,12 @@
 from asyncio import iscoroutinefunction
-from collections.abc import Callable, Coroutine, Iterable, MutableMapping
+from collections.abc import Callable, Collection, Coroutine, Iterable, MutableMapping
 from contextvars import ContextVar, Token
 from threading import Lock
 from types import TracebackType
-from typing import Any, Self, cast, final, overload
+from typing import Any, ClassVar, Self, cast, overload
 
 from haiway.context.types import MissingContext, MissingState
-from haiway.state import State
+from haiway.state import Immutable, State
 from haiway.utils.mimic import mimic_function
 
 __all__ = (
@@ -15,8 +15,7 @@ __all__ = (
 )
 
 
-@final
-class ScopeState:
+class ScopeState(Immutable):
     """
     Container for state objects within a scope.
 
@@ -25,47 +24,24 @@ class ScopeState:
     This class is immutable after initialization.
     """
 
-    __slots__ = (
-        "_lock",
-        "_state",
-    )
+    _state: MutableMapping[type[State], State]
+    _lock: Lock
 
     def __init__(
         self,
         state: Iterable[State],
     ) -> None:
-        self._state: MutableMapping[type[State], State]
         object.__setattr__(
             self,
             "_state",
             {type(element): element for element in state},
         )
-        self._lock: Lock
         object.__setattr__(
             self,
             "_lock",
             Lock(),
         )
 
-    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 check_state[StateType: State](
         self,
         state: type[StateType],
@@ -183,20 +159,17 @@ class ScopeState:
         Self
             A new ScopeState with the combined state
         """
-        if state:
-            return self.__class__(
-                [
-                    *self._state.values(),
-                    *state,
-                ]
-            )
-
-        else:
+        # Fast path: if no new state, return self
+        state_list = list(state)
+        if not state_list:
             return self
 
+        # Optimize: pre-allocate with known size and use dict comprehension
+        combined_state = {**self._state, **{type(s): s for s in state_list}}
+        return self.__class__(combined_state.values())
+
 
-@final
-class StateContext:
+class StateContext(Immutable):
     """
     Context manager for state within a scope.
 
@@ -205,7 +178,26 @@ class StateContext:
     This class is immutable after initialization.
     """
 
-    _context = ContextVar[ScopeState]("StateContext")
+    _context: ClassVar[ContextVar[ScopeState]] = ContextVar[ScopeState]("StateContext")
+
+    @classmethod
+    def current_state(cls) -> Collection[State]:
+        """
+        Return an immutable snapshot of the current state.
+
+        Returns
+        -------
+        Collection[State]
+            State objects present in the current context,
+            or an empty tuple if no context is active.
+        """
+        try:
+            scope_state: ScopeState = cls._context.get()
+            with scope_state._lock:
+                return tuple(scope_state._state.values())
+
+        except LookupError:
+            return ()  # return empty as default
 
     @classmethod
     def check_state[StateType: State](
@@ -306,51 +298,13 @@ class StateContext:
         """
         try:
             # update current scope context
-            return cls(state=cls._context.get().updated(state=state))
+            return cls(_state=cls._context.get().updated(state=state))
 
         except LookupError:  # create root scope when missing
-            return cls(state=ScopeState(state))
+            return cls(_state=ScopeState(state))
 
-    __slots__ = (
-        "_state",
-        "_token",
-    )
-
-    def __init__(
-        self,
-        state: ScopeState,
-    ) -> None:
-        self._state: ScopeState
-        object.__setattr__(
-            self,
-            "_state",
-            state,
-        )
-        self._token: Token[ScopeState] | 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"
-        )
+    _state: ScopeState
+    _token: Token[ScopeState] | None = None
 
     def __enter__(self) -> None:
         """

haiway/context/tasks.py

@@ -2,13 +2,14 @@ from asyncio import Task, TaskGroup, get_event_loop
 from collections.abc import Callable, Coroutine
 from contextvars import ContextVar, Token, copy_context
 from types import TracebackType
-from typing import Any, final
+from typing import Any, ClassVar
+
+from haiway.state import Immutable
 
 __all__ = ("TaskGroupContext",)
 
 
-@final
-class TaskGroupContext:
+class TaskGroupContext(Immutable):
     """
     Context manager for managing task groups within a scope.
 
@@ -17,7 +18,7 @@ class TaskGroupContext:
     This class is immutable after initialization.
     """
 
-    _context = ContextVar[TaskGroup]("TaskGroupContext")
+    _context: ClassVar[ContextVar[TaskGroup]] = ContextVar[TaskGroup]("TaskGroupContext")
 
     @classmethod
     def run[Result, **Arguments](
@@ -59,10 +60,8 @@ class TaskGroupContext:
                 context=copy_context(),
             )
 
-    __slots__ = (
-        "_group",
-        "_token",
-    )
+    _group: TaskGroup
+    _token: Token[TaskGroup] | None = None
 
     def __init__(
         self,
@@ -76,13 +75,11 @@ class TaskGroupContext:
         task_group: TaskGroup | None
             The task group to use, or None to create a new one
         """
-        self._group: TaskGroup
         object.__setattr__(
             self,
             "_group",
             task_group if task_group is not None else TaskGroup(),
         )
-        self._token: Token[TaskGroup] | None
         object.__setattr__(
             self,
             "_token",

haiway/helpers/concurrent.py

@@ -130,9 +130,9 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
 
 @overload
 async def execute_concurrently[Element, Result](
-    source: Collection[Element],
-    /,
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    /,
+    elements: Collection[Element],
     *,
     concurrent_tasks: int = 2,
 ) -> Sequence[Result]: ...
@@ -140,9 +140,9 @@ async def execute_concurrently[Element, Result](
 
 @overload
 async def execute_concurrently[Element, Result](
-    source: Collection[Element],
-    /,
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    /,
+    elements: Collection[Element],
     *,
     concurrent_tasks: int = 2,
     return_exceptions: Literal[True],
@@ -150,9 +150,9 @@ async def execute_concurrently[Element, Result](
 
 
 async def execute_concurrently[Element, Result](  # noqa: C901
-    source: Collection[Element],
-    /,
     handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    /,
+    elements: Collection[Element],
     *,
     concurrent_tasks: int = 2,
     return_exceptions: bool = False,
@@ -173,11 +173,11 @@ async def execute_concurrently[Element, Result](  # noqa: C901
 
     Parameters
     ----------
-    source : Collection[Element]
-        A collection of elements to process. The collection size determines
-        the result sequence length.
     handler : Callable[[Element], Coroutine[Any, Any, Result]]
         A coroutine function that processes each element and returns a result.
+    elements : Collection[Element]
+        A collection of elements to process. The collection size determines
+        the result sequence length.
     concurrent_tasks : int, default=2
         Maximum number of concurrent tasks. Must be greater than 0. Higher
         values allow more parallelism but consume more resources.
@@ -206,16 +206,16 @@ async def execute_concurrently[Element, Result](  # noqa: C901
     ...
     >>> urls = ["http://api.example.com/1", "http://api.example.com/2"]
     >>> results = await execute_concurrently(
-    ...     urls,
     ...     fetch_data,
+    ...     urls,
     ...     concurrent_tasks=10
     ... )
     >>> # results[0] corresponds to urls[0], results[1] to urls[1], etc.
 
     >>> # With exception handling
     >>> results = await execute_concurrently(
-    ...     urls,
     ...     fetch_data,
+    ...     urls,
     ...     concurrent_tasks=10,
     ...     return_exceptions=True
     ... )
@@ -230,7 +230,7 @@ async def execute_concurrently[Element, Result](  # noqa: C901
     running: set[Task[Result]] = set()
     results: MutableSequence[Task[Result]] = []
     try:
-        for element in source:
+        for element in elements:
             task: Task[Result] = ctx.spawn(handler, element)
             results.append(task)
             running.add(task)

haiway/helpers/observability.py

@@ -243,7 +243,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
         nonlocal root_logger
         if root_scope is None:
             root_scope = scope
-            root_logger = logger or getLogger(scope.label)
+            root_logger = logger or getLogger(scope.name)
 
         else:
             scopes[scope.parent_id].nested.append(scope_store)
@@ -251,7 +251,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
         assert root_logger is not None  # nosec: B101
         root_logger.log(
             ObservabilityLevel.INFO,
-            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(
@@ -274,7 +274,7 @@ def LoggerObservability(  # noqa: C901, PLR0915
 
         root_logger.log(
             ObservabilityLevel.INFO,
-            f"[{trace_id_hex}] {scope.unique_name} Exiting scope: {scope.label}",
+            f"[{trace_id_hex}] {scope.unique_name} Exiting scope: {scope.name}",
         )
         metric_str: str = f"Metric - scope_time:{scopes[scope.scope_id].time:.3f}s"
         if debug_context:  # store only for summary
@@ -332,9 +332,7 @@ def _tree_summary(scope_store: ScopeStore) -> str:
     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}]:"
-    ]
+    elements: list[str] = [f"┍━ {scope_store.identifier.name} [{scope_store.identifier.scope_id}]:"]
     for element in scope_store.store:
         if not element:
             continue  # skip empty