haiway 0.24.3__py3-none-any.whl → 0.25.1__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())
 
-        self._state_context.__enter__()
+        # 3. Add explicit disposables state (medium priority)
+        if self._disposables is not None:
+            collected_state.extend(await self._disposables.prepare())
 
-        return self._observability_context.observability.trace_identifying(self._identifier).hex
+        # 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))
+        )
+
+        resolved_state_context.__enter__()
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            resolved_state_context,
+        )
+
+        return str(self._observability_context.observability.trace_identifying(self._identifier))
 
     async def __aexit__(
         self,
@@ -184,13 +224,26 @@ 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__(
                 exc_type=exc_type,
@@ -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,
@@ -217,6 +275,94 @@ class ScopeContext:
         )
 
 
+class DisposablesContext(Immutable):
+    """
+    Immutable async context manager for managing collections of disposables.
+
+    DisposablesContext captures the current contextual state upon initialization
+    and provides an async context manager interface for managing disposable resources.
+    When entered, it prepares the disposables to collect their state, merges it with
+    the captured state, and creates a resolved StateContext. Upon exit, it properly
+    disposes of the disposables and cleans up internal references.
+
+    This class should not be instantiated directly; use the ctx.disposables() factory
+    method to create disposables contexts.
+    """
+
+    _disposables: Disposables
+    _captured_state: Collection[State]
+    _resolved_state_context: StateContext | None
+
+    def __init__(
+        self,
+        disposables: Disposables,
+    ) -> None:
+        # 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,
+        )
+        object.__setattr__(
+            self,
+            "_disposables",
+            disposables,
+        )
+
+    async def __aenter__(self) -> None:
+        assert self._resolved_state_context is None  # nosec: B101
+
+        # Collect all state sources in priority order (lowest to highest priority)
+        collected_state: list[State] = []
+
+        collected_state.extend(self._captured_state)
+
+        collected_state.extend(await self._disposables.prepare())
+
+        # Create resolved state context with all collected state
+        resolved_state_context: StateContext = StateContext(
+            _state=ScopeState(tuple(collected_state))
+        )
+
+        resolved_state_context.__enter__()
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            resolved_state_context,
+        )
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        assert self._resolved_state_context is not None  # nosec: B101
+
+        await self._disposables.dispose(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+
+        self._resolved_state_context.__exit__(
+            exc_type=exc_type,
+            exc_val=exc_val,
+            exc_tb=exc_tb,
+        )
+        object.__setattr__(
+            self,
+            "_resolved_state_context",
+            None,
+        )
+
+
 @final
 class ctx:
     """
@@ -258,9 +404,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 +498,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 +552,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,
@@ -345,7 +584,7 @@ class ctx:
     @staticmethod
     def disposables(
         *disposables: Disposable | None,
-    ) -> Disposables:
+    ) -> DisposablesContext:
         """
         Create a container for managing multiple disposable resources.
 
@@ -362,9 +601,9 @@ class ctx:
 
         Returns
         -------
-        Disposables
+        DisposableContext
             A container that manages the lifecycle of all provided disposables
-            and propagates their state to the context when used with ctx.scope()
+            and propagates their state to the context as when used with ctx.scope()
 
         Examples
         --------
@@ -373,16 +612,19 @@ class ctx:
         >>> from haiway import ctx
         >>> async def main():
         ...
-        ...     async with ctx.scope(
-        ...         "database_work",
-        ...         disposables=(database_connection(),)
+        ...     async with ctx.disposables(
+        ...         database_connection(),
         ...     ):
         ...         # ConnectionState is now available in context
         ...         conn_state = ctx.state(ConnectionState)
         ...         await conn_state.connection.execute("SELECT 1")
         """
 
-        return Disposables(*(disposable for disposable in disposables if disposable is not None))
+        return DisposablesContext(
+            disposables=Disposables(
+                *(disposable for disposable in disposables if disposable is not None)
+            )
+        )
 
     @staticmethod
     def spawn[Result, **Arguments](