haiway 0.21.4__tar.gz → 0.22.0__tar.gz

{haiway-0.21.4 → haiway-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.21.4
+Version: 0.22.0
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git
@@ -40,7 +40,7 @@ Requires-Dist: pyright~=1.1; extra == 'dev'
 Requires-Dist: pytest-asyncio~=0.26; extra == 'dev'
 Requires-Dist: pytest-cov~=6.1; extra == 'dev'
 Requires-Dist: pytest~=8.3; extra == 'dev'
-Requires-Dist: ruff~=0.11; extra == 'dev'
+Requires-Dist: ruff~=0.12; extra == 'dev'
 Provides-Extra: opentelemetry
 Requires-Dist: opentelemetry-api~=1.33; extra == 'opentelemetry'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc~=1.33; extra == 'opentelemetry'

haiway-0.22.0/junit/test-results.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><testsuites name="pytest tests"><testsuite name="pytest" errors="0" failures="0" skipped="0" tests="151" time="1.947" timestamp="2025-06-18T09:04:02.496497+00:00" hostname="pkrvmxyh4eaekms"><testcase classname="tests.test_async_queue" name="test_fails_when_stream_fails" time="0.001" /><testcase classname="tests.test_async_queue" name="test_cancels_when_iteration_cancels" time="0.001" /><testcase classname="tests.test_async_queue" name="test_ends_when_stream_ends" time="0.001" /><testcase classname="tests.test_async_queue" name="test_buffers_values_when_not_reading" time="0.001" /><testcase classname="tests.test_async_queue" name="test_delivers_buffer_when_streaming_fails" time="0.001" /><testcase classname="tests.test_async_queue" name="test_delivers_updates_when_sending" time="0.001" /><testcase classname="tests.test_async_queue" name="test_fails_when_sending_to_finished" time="0.001" /><testcase classname="tests.test_async_queue" name="test_ignores_when_finishing_when_finished" time="0.001" /><testcase classname="tests.test_async_stream" name="test_fails_when_stream_fails" time="0.001" /><testcase classname="tests.test_async_stream" name="test_cancels_when_iteration_cancels" time="0.001" /><testcase classname="tests.test_async_stream" name="test_ends_when_stream_ends" time="0.001" /><testcase classname="tests.test_async_stream" name="test_finishes_without_buffer" time="0.001" /><testcase classname="tests.test_async_stream" name="test_fails_without_buffer" time="0.001" /><testcase classname="tests.test_async_stream" name="test_delivers_updates_when_sending" time="0.001" /><testcase classname="tests.test_async_stream" name="test_ignores_when_sending_to_finished" time="0.001" /><testcase classname="tests.test_async_stream" name="test_ignores_when_sending_to_failed" time="0.001" /><testcase classname="tests.test_async_stream" name="test_ignores_when_finishing_when_finished" time="0.001" /><testcase classname="tests.test_async_stream" name="test_delivers_all_when_sending_async" time="0.001" /><testcase classname="tests.test_attribute_path" name="test_id_path_points_to_self" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_attribute_path_points_to_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_nested_attribute_path_points_to_nested_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_recursive_attribute_path_points_to_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_list_item_path_points_to_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_tuple_item_path_points_to_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_mixed_tuple_item_path_points_to_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_dict_item_path_points_to_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_id_path_set_updates_self" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_attribute_path_set_updates_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_nested_attribute_path_set_updates_nested_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_recursive_attribute_set_updates_attribute" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_list_item_path_set_updates_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_tuple_item_path_set_updates_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_mixed_tuple_item_set_updates_item" time="0.000" /><testcase classname="tests.test_attribute_path" name="test_dict_item_path_set_updates_item" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_equal_requirement" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_not_equal_requirement" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_contains_requirement" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_contains_any_requirement" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_contained_in_requirement" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_logical_and_or_requirements" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_filter" time="0.000" /><testcase classname="tests.test_attribute_requirement" name="test_immutability" time="0.000" /><testcase classname="tests.test_auto_retry" name="test_returns_value_without_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_retries_with_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_logs_issue_with_errors" time="0.002" /><testcase classname="tests.test_auto_retry" name="test_fails_with_exceeding_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_fails_with_cancellation" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_retries_with_selected_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_fails_with_not_selected_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_returns_value_without_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_retries_with_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_fails_with_exceeding_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_fails_with_cancellation" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_fails_when_cancelled" time="0.021" /><testcase classname="tests.test_auto_retry" name="test_async_uses_delay_with_errors" time="0.102" /><testcase classname="tests.test_auto_retry" name="test_async_uses_computed_delay_with_errors" time="0.107" /><testcase classname="tests.test_auto_retry" name="test_async_logs_issue_with_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_retries_with_selected_errors" time="0.001" /><testcase classname="tests.test_auto_retry" name="test_async_fails_with_not_selected_errors" time="0.001" /><testcase classname="tests.test_cache" name="test_returns_cache_value_with_same_argument" time="0.000" /><testcase classname="tests.test_cache" name="test_returns_fresh_value_with_different_argument" time="0.000" /><testcase classname="tests.test_cache" name="test_returns_fresh_value_with_limit_exceed" time="0.000" /><testcase classname="tests.test_cache" name="test_returns_same_value_with_repeating_argument" time="0.000" /><testcase classname="tests.test_cache" name="test_fails_with_error" time="0.000" /><testcase classname="tests.test_cache" name="test_returns_fresh_value_with_expiration_time_exceed" time="0.021" /><testcase classname="tests.test_cache" name="test_async_returns_cache_value_with_same_argument" time="0.001" /><testcase classname="tests.test_cache" name="test_async_returns_fresh_value_with_different_argument" time="0.001" /><testcase classname="tests.test_cache" name="test_async_returns_fresh_value_with_limit_exceed" time="0.001" /><testcase classname="tests.test_cache" name="test_async_returns_same_value_with_repeating_argument" time="0.001" /><testcase classname="tests.test_cache" name="test_async_returns_fresh_value_with_expiration_time_exceed" time="0.021" /><testcase classname="tests.test_cache" name="test_async_cancel_waiting_does_not_cancel_task" time="0.502" /><testcase classname="tests.test_cache" name="test_async_expiration_does_not_cancel_task" time="0.021" /><testcase classname="tests.test_cache" name="test_async_fails_with_error" time="0.001" /><testcase classname="tests.test_context" name="test_state_is_available_according_to_context" time="0.001" /><testcase classname="tests.test_context" name="test_state_update_updates_local_context" time="0.001" /><testcase classname="tests.test_context" name="test_exceptions_are_propagated" time="0.001" /><testcase classname="tests.test_disposables" name="test_empty_initialization" time="0.000" /><testcase classname="tests.test_disposables" name="test_single_disposable_initialization" time="0.000" /><testcase classname="tests.test_disposables" name="test_multiple_disposables_initialization" time="0.000" /><testcase classname="tests.test_disposables" name="test_cannot_set_attributes" time="0.001" /><testcase classname="tests.test_disposables" name="test_cannot_delete_attributes" time="0.000" /><testcase classname="tests.test_disposables" name="test_empty_disposables_is_falsy" time="0.000" /><testcase classname="tests.test_disposables" name="test_non_empty_disposables_is_truthy" time="0.000" /><testcase classname="tests.test_disposables" name="test_setup_with_no_disposables" time="0.001" /><testcase classname="tests.test_disposables" name="test_setup_with_disposable_returning_none" time="0.001" /><testcase classname="tests.test_disposables" name="test_setup_with_disposable_returning_single_state" time="0.001" /><testcase classname="tests.test_disposables" name="test_setup_with_disposable_returning_multiple_states" time="0.001" /><testcase classname="tests.test_disposables" name="test_setup_with_multiple_disposables_mixed_returns" time="0.001" /><testcase classname="tests.test_disposables" name="test_setup_sets_loop_correctly" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_with_no_disposables" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_with_successful_cleanup" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_with_exception_context" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_with_multiple_exceptions_creates_group" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_with_single_exception_is_risen" time="0.001" /><testcase classname="tests.test_disposables" name="test_dispose_resets_loop_even_on_exception" time="0.001" /><testcase classname="tests.test_disposables" name="test_same_loop_cleanup" time="0.001" /><testcase classname="tests.test_disposables" name="test_with_real_async_context_managers" time="0.001" /><testcase classname="tests.test_disposables" name="test_nested_disposables_usage" time="0.001" /><testcase classname="tests.test_disposables" name="test_exception_during_setup_phase" time="0.001" /><testcase classname="tests.test_disposables" name="test_assertion_on_doubleprepare" time="0.001" /><testcase classname="tests.test_disposables" name="test_assertion_on_dispose_withoutprepare" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_processes_all_elements" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_processes_elements_concurrently" time="0.302" /><testcase classname="tests.test_process_concurrently" name="test_handles_empty_source" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_propagates_handler_exceptions" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_ignores_handler_exceptions_when_configured" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_handles_source_exception" time="0.001" /><testcase classname="tests.test_process_concurrently" name="test_cancels_running_tasks_on_cancellation" time="0.101" /><testcase classname="tests.test_process_concurrently" name="test_respects_concurrency_limit" time="0.202" /><testcase classname="tests.test_process_concurrently" name="test_processes_elements_from_queue" time="0.052" /><testcase classname="tests.test_state" name="test_basic_initializes_with_arguments" time="0.001" /><testcase classname="tests.test_state" name="test_basic_initializes_with_defaults" time="0.001" /><testcase classname="tests.test_state" name="test_basic_equals_checks_properties" time="0.000" /><testcase classname="tests.test_state" name="test_basic_initializes_with_arguments_and_defaults" time="0.000" /><testcase classname="tests.test_state" name="test_parametrized_initializes_with_proper_parameters" time="0.000" /><testcase classname="tests.test_state" name="test_nested_initializes_with_proper_arguments" time="0.001" /><testcase classname="tests.test_state" name="test_dict_skips_missing_properties" time="0.000" /><testcase classname="tests.test_state" name="test_initialization_allows_missing_properties" time="0.001" /><testcase classname="tests.test_state" name="test_generic_subtypes_validation" time="0.001" /><testcase classname="tests.test_state" name="test_copying_leaves_same_object" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_basic_types" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validator_none_type" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validator_missing_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_literal_type" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validator_enum_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_sequence_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_set_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_mapping_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_tuple_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_union_type" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validator_callable_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_typed_dict" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_state_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_complex_types" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validator_recursive_state" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_generic_state" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validation_error_messages" time="0.001" /><testcase classname="tests.test_state_validation" name="test_validation_any_type" time="0.000" /><testcase classname="tests.test_state_validation" name="test_validator_with_defaults" time="0.000" /><testcase classname="tests.test_state_validation" name="test_attribute_validator_direct_usage" time="0.000" /><testcase classname="tests.test_state_validation" name="test_unsupported_type_annotation" time="0.000" /><testcase classname="tests.test_streaming" name="test_fails_when_generator_fails" time="0.001" /><testcase classname="tests.test_streaming" name="test_cancels_when_iteration_cancels" time="0.001" /><testcase classname="tests.test_streaming" name="test_ends_when_generator_ends" time="0.001" /><testcase classname="tests.test_streaming" name="test_delivers_updates_when_generating" time="0.001" /><testcase classname="tests.test_streaming" name="test_streaming_context_variables_access_is_preserved" time="0.001" /><testcase classname="tests.test_streaming" name="test_nested_streaming_streams_correctly" time="0.001" /><testcase classname="tests.test_timeout" name="test_returns_result_when_returning_value" time="0.001" /><testcase classname="tests.test_timeout" name="test_raises_with_error" time="0.001" /><testcase classname="tests.test_timeout" name="test_raises_with_cancel" time="0.012" /><testcase classname="tests.test_timeout" name="test_raises_with_timeout" time="0.011" /></testsuite></testsuites>

{haiway-0.21.4 → haiway-0.22.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "haiway"
 description = "Framework for dependency injection and state management within structured concurrency model."
-version = "0.21.4"
+version = "0.22.0"
 readme = "README.md"
 maintainers = [
   { name = "Kacper Kaliński", email = "kacper.kalinski@miquido.com" },
@@ -38,7 +38,7 @@ dev = [
   "pytest~=8.3",
   "pytest-asyncio~=0.26",
   "pytest-cov~=6.1",
-  "ruff~=0.11",
+  "ruff~=0.12",
 ]
 
 [tool.ruff]

{haiway-0.21.4 → haiway-0.22.0}/src/haiway/__init__.py

@@ -13,6 +13,8 @@ from haiway.context import (
     ctx,
 )
 from haiway.helpers import (
+    File,
+    FileAccess,
     LoggerObservability,
     asynchronous,
     cache,
@@ -63,6 +65,8 @@ __all__ = (
     "DefaultValue",
     "Disposable",
     "Disposables",
+    "File",
+    "FileAccess",
     "LoggerObservability",
     "Missing",
     "MissingContext",

{haiway-0.21.4 → haiway-0.22.0}/src/haiway/context/access.py

@@ -169,8 +169,8 @@ class ScopeContext:
                 StateContext(
                     state=ScopeState(
                         (
-                            *await disposables.__aenter__(),
                             *self._state_context._state._state.values(),
+                            *await disposables.prepare(),
                         )
                     ),
                 ),
@@ -187,7 +187,7 @@ class ScopeContext:
         exc_tb: TracebackType | None,
     ) -> None:
         if disposables := self._disposables:
-            await disposables.__aexit__(
+            await disposables.dispose(
                 exc_type=exc_type,
                 exc_val=exc_val,
                 exc_tb=exc_tb,
@@ -382,6 +382,48 @@ class ctx:
 
         return StateContext.updated(element for element in state if element is not None)
 
+    @staticmethod
+    def disposables(
+        *disposables: Disposable | None,
+    ) -> Disposables:
+        """
+        Create a container for managing multiple disposable resources.
+
+        Disposables are async context managers that can provide state objects and
+        require proper cleanup. This method creates a Disposables container that
+        manages multiple disposable resources as a single unit, handling their
+        lifecycle and state propagation.
+
+        Parameters
+        ----------
+        *disposables: Disposable | None
+            Variable number of disposable resources to be managed together.
+            None values are filtered out automatically.
+
+        Returns
+        -------
+        Disposables
+            A container that manages the lifecycle of all provided disposables
+            and propagates their state to the context when used with ctx.scope()
+
+        Examples
+        --------
+        Using disposables with database connections:
+
+        >>> from haiway import ctx
+        >>> async def main():
+        ...
+        ...     async with ctx.scope(
+        ...         "database_work",
+        ...         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))
+
     @staticmethod
     def spawn[Result, **Arguments](
         function: Callable[Arguments, Coroutine[Any, Any, Result]],
@@ -493,6 +535,29 @@ class ctx:
         else:
             raise RuntimeError("Attempting to cancel context out of asyncio task")
 
+    @staticmethod
+    def check_state[StateType: State](
+        state: type[StateType],
+        /,
+    ) -> bool:
+        """
+        Check if state object is available in the current context.
+
+        Verifies if state object of the specified type is available the current context.
+        Instantiates requested state if needed and possible.
+
+        Parameters
+        ----------
+        state: type[StateType]
+            The type of state to check
+
+        Returns
+        -------
+        bool
+            True if state is available, otherwise False.
+        """
+        return StateContext.check_state(state)
+
     @staticmethod
     def state[StateType: State](
         state: type[StateType],
@@ -500,18 +565,60 @@ class ctx:
         default: StateType | None = None,
     ) -> StateType:
         """
-        Access current scope context state by its type. If there is no matching state defined\
-         default value will be created if able, an exception will raise otherwise.
+        Access state from the current scope context by its type.
+
+        Retrieves state objects that have been propagated within the current execution context.
+        State objects are automatically made available through context scopes and disposables.
+        If no matching state is found, creates a default instance if possible.
 
         Parameters
         ----------
         state: type[StateType]
-            type of requested state
+            The State class type to retrieve from the current context
+        default: StateType | None, default=None
+            Optional default instance to return if state is not found in context.
+            If None and no state is found, a new instance will be created if possible.
 
         Returns
         -------
         StateType
-            resolved state instance
+            The state instance from the current context or a default/new instance
+
+        Raises
+        ------
+        RuntimeError
+            If called outside of any scope context
+        TypeError
+            If no state is found and no default can be created
+
+        Examples
+        --------
+        Accessing configuration state:
+
+        >>> from haiway import ctx, State
+        >>>
+        >>> class ApiConfig(State):
+        ...     base_url: str = "https://api.example.com"
+        ...     timeout: int = 30
+        >>>
+        >>> async def fetch_data():
+        ...     config = ctx.state(ApiConfig)
+        ...     # Use config.base_url and config.timeout
+        >>>
+        >>> async with ctx.scope("api", ApiConfig(base_url="https://custom.api.com")):
+        ...     await fetch_data()  # Uses custom config
+
+        Accessing state with default:
+
+        >>> cache_config = ctx.state(CacheConfig, default=CacheConfig(ttl=3600))
+
+        Within service classes:
+
+        >>> class UserService(State):
+        ...     @classmethod
+        ...     async def get_user(cls, user_id: str) -> User:
+        ...         config = ctx.state(DatabaseConfig)
+        ...         # Use config to connect to database
         """
         return StateContext.state(
             state,

haiway-0.22.0/src/haiway/context/disposables.py

@@ -0,0 +1,357 @@
+from asyncio import (
+    AbstractEventLoop,
+    gather,
+    get_running_loop,
+    iscoroutinefunction,
+    run_coroutine_threadsafe,
+    wrap_future,
+)
+from collections.abc import Callable, Coroutine, Iterable
+from contextlib import AbstractAsyncContextManager
+from itertools import chain
+from types import TracebackType
+from typing import Any, final
+
+from haiway.context.state import ScopeState, StateContext
+from haiway.state import State
+from haiway.utils.mimic import mimic_function
+
+__all__ = (
+    "Disposable",
+    "Disposables",
+)
+
+type Disposable = AbstractAsyncContextManager[Iterable[State] | State | None]
+"""
+A type alias for asynchronous context managers that provide disposable resources.
+
+Represents an asynchronous resource that needs proper cleanup when no longer needed.
+When entered, it may return State instances that will be automatically propagated
+to the current context. The resource is guaranteed to be properly disposed of
+when the context exits, even if exceptions occur.
+
+Type Details
+------------
+- Must be an async context manager (implements __aenter__ and __aexit__)
+- Can return None, a single State instance, or multiple State instances
+- State instances are automatically added to the context scope
+- Cleanup is handled automatically when the context exits
+
+Examples
+--------
+Creating a disposable database connection:
+
+>>> import contextlib
+>>> from haiway import State
+>>>
+>>> class DatabaseState(State):
+...     connection: DatabaseConnection
+...
+>>> @contextlib.asynccontextmanager
+>>> async def database_disposable():
+...     connection = await create_database_connection()
+...     try:
+...         yield DatabaseState(connection=connection)
+...     finally:
+...         await connection.close()
+"""
+
+
+@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 in parallel when the container is entered and exiting all of
+    them when the container is exited. Any states returned by the disposables are
+    collected and automatically propagated to the context.
+
+    Key Features
+    ------------
+    - Parallel setup and cleanup of all contained disposables
+    - Automatic state collection and context propagation
+    - Thread-safe cross-event-loop disposal
+    - Exception handling with BaseExceptionGroup for multiple failures
+    - Immutable after initialization
+
+    The class is designed to work seamlessly with ctx.scope() and ensures proper
+    resource cleanup even when exceptions occur during setup or teardown.
+
+    Examples
+    --------
+    Creating and using multiple disposables:
+
+    >>> from haiway import ctx
+    >>> async def main():
+    ...     disposables = Disposables(
+    ...         database_disposable(),
+    ...         cache_disposable()
+    ...     )
+    ...
+    ...     async with ctx.scope("app", disposables=disposables):
+    ...         # Both DatabaseState and CacheState are available
+    ...         db = ctx.state(DatabaseState)
+    ...         cache = ctx.state(CacheState)
+
+    Direct context manager usage:
+
+    >>> async def process_data():
+    ...     disposables = Disposables(
+    ...         create_temp_file_disposable(),
+    ...         create_network_connection_disposable()
+    ...     )
+    ...
+    ...     async with disposables:
+    ...         # Resources are set up in parallel
+    ...         temp_file = ctx.state(TempFileState)
+    ...         network = ctx.state(NetworkState)
+    ...
+    ...         # Process data using both resources
+    ...
+    ...     # All resources cleaned up automatically
+    """
+
+    __slots__ = (
+        "_disposables",
+        "_loop",
+        "_state_context",
+    )
+
+    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,
+            "_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.
+
+        Returns
+        -------
+        bool
+            True if there are disposables, False otherwise.
+        """
+        return len(self._disposables) > 0
+
+    async def _setup(
+        self,
+        disposable: Disposable,
+        /,
+    ) -> Iterable[State]:
+        match await disposable.__aenter__():
+            case None:
+                return ()
+
+            case State() as single:
+                return (single,)
+
+            case multiple:
+                return multiple
+
+    async def prepare(self) -> Iterable[State]:
+        assert self._loop is None  # nosec: B101
+        object.__setattr__(
+            self,
+            "_loop",
+            get_running_loop(),
+        )
+        return [
+            *chain.from_iterable(
+                await gather(
+                    *[self._setup(disposable) for disposable in self._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(state=ScopeState(await self.prepare()))
+        state_context.__enter__()
+        object.__setattr__(
+            self,
+            "_state_context",
+            state_context,
+        )
+
+    async def _cleanup(
+        self,
+        /,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> list[bool | BaseException | None]:
+        return await gather(
+            *[
+                disposable.__aexit__(
+                    exc_type,
+                    exc_val,
+                    exc_tb,
+                )
+                for disposable in self._disposables
+            ],
+            return_exceptions=True,
+        )
+
+    async def dispose(
+        self,
+        /,
+        exc_type: type[BaseException] | None = None,
+        exc_val: BaseException | None = None,
+        exc_tb: TracebackType | None = None,
+    ) -> None:
+        assert self._loop is not None  # nosec: B101
+        results: list[bool | BaseException | None]
+
+        try:
+            current_loop: AbstractEventLoop = get_running_loop()
+            if self._loop != current_loop:
+                results = await wrap_future(
+                    run_coroutine_threadsafe(
+                        self._cleanup(
+                            exc_type,
+                            exc_val,
+                            exc_tb,
+                        ),
+                        loop=self._loop,
+                    )
+                )
+
+            else:
+                results = await self._cleanup(
+                    exc_type,
+                    exc_val,
+                    exc_tb,
+                )
+
+        finally:
+            object.__setattr__(
+                self,
+                "_loop",
+                None,
+            )
+
+        exceptions: list[BaseException] = [exc for exc in results if isinstance(exc, BaseException)]
+
+        match len(exceptions):
+            case 0:
+                return
+
+            case 1:
+                raise exceptions[0]
+
+            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.
+
+        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)