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

haiway/__init__.py

@@ -1,4 +1,5 @@
 from haiway.context import (
+    ContextPresets,
     Disposable,
     Disposables,
     MissingContext,
@@ -26,7 +27,7 @@ from haiway.helpers import (
     timeout,
     traced,
 )
-from haiway.state import AttributePath, AttributeRequirement, State
+from haiway.state import AttributePath, AttributeRequirement, Immutable, State
 from haiway.types import (
     MISSING,
     Default,
@@ -64,12 +65,14 @@ __all__ = (
     "AsyncStream",
     "AttributePath",
     "AttributeRequirement",
+    "ContextPresets",
     "Default",
     "DefaultValue",
     "Disposable",
     "Disposables",
     "File",
     "FileAccess",
+    "Immutable",
     "LoggerObservability",
     "Missing",
     "MissingContext",

haiway/context/__init__.py

@@ -14,12 +14,16 @@ from haiway.context.observability import (
     ObservabilityScopeExiting,
     ObservabilityTraceIdentifying,
 )
+from haiway.context.presets import ContextPresets
 from haiway.context.state import StateContext
 from haiway.context.types import MissingContext, MissingState
+from haiway.state import Immutable
 
 __all__ = (
+    "ContextPresets",
     "Disposable",
     "Disposables",
+    "Immutable",
     "MissingContext",
     "MissingState",
     "Observability",

haiway/context/access.py

@@ -8,6 +8,7 @@ from collections.abc import (
     AsyncGenerator,
     AsyncIterator,
     Callable,
+    Collection,
     Coroutine,
     Iterable,
     Mapping,
@@ -24,16 +25,20 @@ from haiway.context.observability import (
     ObservabilityContext,
     ObservabilityLevel,
 )
+from haiway.context.presets import (
+    ContextPresets,
+    ContextPresetsRegistry,
+    ContextPresetsRegistryContext,
+)
 from haiway.context.state import ScopeState, StateContext
 from haiway.context.tasks import TaskGroupContext
-from haiway.state import State
+from haiway.state import Immutable, State
 from haiway.utils.stream import AsyncStream
 
 __all__ = ("ctx",)
 
 
-@final
-class ScopeContext:
+class ScopeContext(Immutable):
     """
     Context manager for executing code within a defined scope.
 
@@ -45,42 +50,62 @@ class ScopeContext:
     to create scope contexts.
     """
 
-    __slots__ = (
-        "_disposables",
-        "_identifier",
-        "_observability_context",
-        "_state_context",
-        "_task_group_context",
-    )
+    _identifier: ScopeIdentifier
+    _state: Collection[State]
+    _captured_state: Collection[State]
+    _resolved_state_context: StateContext | None
+    _disposables: Disposables | None
+    _presets: ContextPresets | None
+    _presets_disposables: Disposables | None
+    _observability_context: ObservabilityContext
+    _task_group_context: TaskGroupContext | None
 
     def __init__(
         self,
-        label: str,
+        name: str,
         task_group: TaskGroup | None,
         state: tuple[State, ...],
         disposables: Disposables | None,
         observability: Observability | Logger | None,
     ) -> None:
-        self._identifier: ScopeIdentifier
         object.__setattr__(
             self,
             "_identifier",
-            ScopeIdentifier.scope(label),
+            ScopeIdentifier.scope(name),
         )
-        # prepare state context to capture current state
-        self._state_context: StateContext
+        # store explicit state separately for priority control
         object.__setattr__(
             self,
-            "_state_context",
-            StateContext.updated(state),
+            "_state",
+            state,
+        )
+        # capture current contextual state (without new additions)
+        object.__setattr__(
+            self,
+            "_captured_state",
+            StateContext.current_state(),
+        )
+        # placeholder for temporary, resolved state context
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            None,
         )
-        self._disposables: Disposables | None
         object.__setattr__(
             self,
             "_disposables",
             disposables,
         )
-        self._observability_context: ObservabilityContext
+        object.__setattr__(
+            self,
+            "_presets",
+            ContextPresetsRegistryContext.select(name),
+        )
+        object.__setattr__(
+            self,
+            "_presets_disposables",
+            None,
+        )
         object.__setattr__(
             self,
             "_observability_context",
@@ -90,7 +115,6 @@ class ScopeContext:
                 observability=observability,
             ),
         )
-        self._task_group_context: TaskGroupContext | None
         object.__setattr__(
             self,
             "_task_group_context",
@@ -99,35 +123,27 @@ class ScopeContext:
             else 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) -> str:
         assert (  # nosec: B101
             self._task_group_context is None or self._identifier.is_root
         ), "Can't enter synchronous context with task group"
         assert self._disposables is None, "Can't enter synchronous context with disposables"  # nosec: B101
+        assert self._resolved_state_context is None  # nosec: B101
+        assert self._presets is None, "Can't enter synchronous context with presets"  # nosec: B101
         self._identifier.__enter__()
         self._observability_context.__enter__()
-        self._state_context.__enter__()
+        # For sync context, only use explicit state (no presets or disposables allowed)
+        resolved_state_context: StateContext = StateContext(
+            _state=ScopeState((*self._captured_state, *self._state))
+        )
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            resolved_state_context,
+        )
+        resolved_state_context.__enter__()
 
-        return self._observability_context.observability.trace_identifying(self._identifier).hex
+        return str(self._observability_context.observability.trace_identifying(self._identifier))
 
     def __exit__(
         self,
@@ -135,11 +151,17 @@ class ScopeContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        self._state_context.__exit__(
+        assert self._resolved_state_context is not None  # nosec: B101
+        self._resolved_state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            None,
+        )
         self._observability_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
@@ -152,31 +174,49 @@ class ScopeContext:
         )
 
     async def __aenter__(self) -> str:
+        assert self._presets_disposables is None  # nosec: B101
+        assert self._resolved_state_context is None  # nosec: B101
         self._identifier.__enter__()
         self._observability_context.__enter__()
 
         if task_group := self._task_group_context:
             await task_group.__aenter__()
 
-        # lazily initialize state to include disposables results
-        if disposables := self._disposables:
-            assert self._state_context._token is None  # nosec: B101
+        # Collect all state sources in priority order (lowest to highest priority)
+        collected_state: list[State] = []
+
+        # 1. Add contextual state first (lowest priority)
+        collected_state.extend(self._captured_state)
+
+        # 2. Add preset state (low priority, overrides contextual)
+        if self._presets is not None:
+            presets_disposables: Disposables = await self._presets.prepare()
             object.__setattr__(
                 self,
-                "_state_context",
-                StateContext(
-                    state=ScopeState(
-                        (
-                            *self._state_context._state._state.values(),
-                            *await disposables.prepare(),
-                        )
-                    ),
-                ),
+                "_presets_disposables",
+                presets_disposables,
             )
+            collected_state.extend(await presets_disposables.prepare())
+
+        # 3. Add explicit disposables state (medium priority)
+        if self._disposables is not None:
+            collected_state.extend(await self._disposables.prepare())
+
+        # 4. Add explicit state last (highest priority)
+        collected_state.extend(self._state)
+        # Create resolved state context with all collected state
+        resolved_state_context: StateContext = StateContext(
+            _state=ScopeState(tuple(collected_state))
+        )
 
-        self._state_context.__enter__()
+        resolved_state_context.__enter__()
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            resolved_state_context,
+        )
 
-        return self._observability_context.observability.trace_identifying(self._identifier).hex
+        return str(self._observability_context.observability.trace_identifying(self._identifier))
 
     async def __aexit__(
         self,
@@ -184,12 +224,25 @@ class ScopeContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        if disposables := self._disposables:
-            await disposables.dispose(
+        assert self._resolved_state_context is not None  # nosec: B101
+        if self._disposables is not None:
+            await self._disposables.dispose(
+                exc_type=exc_type,
+                exc_val=exc_val,
+                exc_tb=exc_tb,
+            )
+
+        if self._presets_disposables is not None:
+            await self._presets_disposables.dispose(
                 exc_type=exc_type,
                 exc_val=exc_val,
                 exc_tb=exc_tb,
             )
+            object.__setattr__(
+                self,
+                "_presets_disposables",
+                None,
+            )
 
         if task_group := self._task_group_context:
             await task_group.__aexit__(
@@ -198,11 +251,16 @@ class ScopeContext:
                 exc_tb=exc_tb,
             )
 
-        self._state_context.__exit__(
+        self._resolved_state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            None,
+        )
 
         self._observability_context.__exit__(
             exc_type=exc_type,
@@ -258,9 +316,90 @@ class ctx:
         """
         return ObservabilityContext.trace_id(scope_identifier)
 
+    @staticmethod
+    def presets(
+        *presets: ContextPresets,
+    ) -> ContextPresetsRegistryContext:
+        """
+        Create a context manager for a preset registry.
+
+        This method creates a registry of context presets that can be used within
+        nested scopes. Presets allow you to define reusable combinations of state
+        and disposables that can be referenced by name when creating scopes.
+
+        When entering this context manager, the provided presets become available
+        for use with ctx.scope(). The presets are looked up by their name when
+        creating scopes.
+
+        Parameters
+        ----------
+        *presets: ContextPresets
+            Variable number of preset configurations to register. Each preset
+            must have a unique name within the registry.
+
+        Returns
+        -------
+        ContextPresetsRegistryContext
+            A context manager that makes the presets available in nested scopes
+
+        Examples
+        --------
+        Basic preset usage:
+
+        >>> from haiway import ctx, State
+        >>> from haiway.context import ContextPresets
+        >>>
+        >>> class ApiConfig(State):
+        ...     base_url: str
+        ...     timeout: int = 30
+        >>>
+        >>> # Define presets
+        >>> dev_preset = ContextPresets(
+        ...     name="development",
+        ...     _state=[ApiConfig(base_url="https://dev-api.example.com")]
+        ... )
+        >>>
+        >>> prod_preset = ContextPresets(
+        ...     name="production",
+        ...     _state=[ApiConfig(base_url="https://api.example.com", timeout=60)]
+        ... )
+        >>>
+        >>> # Use presets
+        >>> with ctx.presets(dev_preset, prod_preset):
+        ...     async with ctx.scope("development"):
+        ...         config = ctx.state(ApiConfig)
+        ...         assert config.base_url == "https://dev-api.example.com"
+
+        Nested preset registries:
+
+        >>> base_presets = [dev_preset, prod_preset]
+        >>> override_preset = ContextPresets(
+        ...     name="development",
+        ...     _state=[ApiConfig(base_url="https://staging.example.com")]
+        ... )
+        >>>
+        >>> with ctx.presets(*base_presets):
+        ...     # Outer registry has dev and prod presets
+        ...     with ctx.presets(override_preset):
+        ...         # Inner registry overrides dev preset
+        ...         async with ctx.scope("development"):
+        ...             config = ctx.state(ApiConfig)
+        ...             assert config.base_url == "https://staging.example.com"
+
+        See Also
+        --------
+        ContextPresets : For creating individual preset configurations
+        ctx.scope : For creating scopes that can use presets
+        """
+        return ContextPresetsRegistryContext(
+            registry=ContextPresetsRegistry(
+                presets=presets,
+            ),
+        )
+
     @staticmethod
     def scope(
-        label: str,
+        name: str,
         /,
         *state: State | None,
         disposables: Disposables | Iterable[Disposable] | None = None,
@@ -271,10 +410,22 @@ class ctx:
         Prepare scope context with given parameters. When called within an existing context\
          it becomes nested with current context as its parent.
 
+        State Priority System
+        ---------------------
+        State resolution follows a 4-layer priority system (highest to lowest):
+
+        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
+
+        When state types conflict, higher priority sources override lower priority ones.
+        State objects are resolved by type, with the highest priority instance winning.
+
         Parameters
         ----------
-        label: str
-            name of the scope context
+        name: str
+            name of the scope context, can be associated with state presets
 
         *state: State | None
             state propagated within the scope context, will be merged with current state by\
@@ -313,7 +464,7 @@ class ctx:
                 resolved_disposables = Disposables(*iterable)
 
         return ScopeContext(
-            label=label,
+            name=name,
             task_group=task_group,
             state=tuple(element for element in state if element is not None),
             disposables=resolved_disposables,

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)