haiway 0.21.4__py3-none-any.whl → 0.22.1__py3-none-any.whl

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/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,37 @@ class ctx:
         else:
             raise RuntimeError("Attempting to cancel context out of asyncio task")
 
+    @staticmethod
+    def check_state[StateType: State](
+        state: type[StateType],
+        /,
+        *,
+        instantiate_defaults: bool = False,
+    ) -> 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
+
+        instantiate_defaults: bool = False
+            Control if default value should be instantiated during check.
+
+        Returns
+        -------
+        bool
+            True if state is available, otherwise False.
+        """
+        return StateContext.check_state(
+            state,
+            instantiate_defaults=instantiate_defaults,
+        )
+
     @staticmethod
     def state[StateType: State](
         state: type[StateType],
@@ -500,18 +573,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/context/disposables.py

@@ -1,11 +1,20 @@
-from asyncio import gather
-from collections.abc import Iterable
+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 StateContext
 from haiway.state import State
+from haiway.utils.mimic import mimic_function
 
 __all__ = (
     "Disposable",
@@ -14,10 +23,37 @@ __all__ = (
 
 type Disposable = AbstractAsyncContextManager[Iterable[State] | State | None]
 """
-A type alias for asynchronous context managers that can be disposed.
+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 propagated to the context.
+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()
 """
 
 
@@ -27,14 +63,60 @@ 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 when the container is entered and exiting all of them when
-    the container is exited. Any states returned by the disposables are collected
-    and returned as a unified collection.
+    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.
 
-    The class is immutable after initialization.
+    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",)
+    __slots__ = (
+        "_disposables",
+        "_loop",
+        "_state_context",
+    )
 
     def __init__(
         self,
@@ -54,6 +136,18 @@ class Disposables:
             "_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,
@@ -85,7 +179,7 @@ class Disposables:
         """
         return len(self._disposables) > 0
 
-    async def _initialize(
+    async def _setup(
         self,
         disposable: Disposable,
         /,
@@ -100,31 +194,69 @@ class Disposables:
             case multiple:
                 return multiple
 
-    async def __aenter__(self) -> Iterable[State]:
+    async def prepare(self) -> Iterable[State]:
         """
         Enter all contained disposables asynchronously.
 
         Enters all disposables in parallel and collects any State objects they return.
-
-        Returns
-        -------
-        Iterable[State]
-            Collection of State objects from all disposables.
         """
-        return [
-            *chain.from_iterable(
-                state
-                for state in await gather(
-                    *[self._initialize(disposable) for disposable in self._disposables],
+        assert self._loop is None  # nosec: B101
+        object.__setattr__(
+            self,
+            "_loop",
+            get_running_loop(),
+        )
+
+        return tuple(
+            chain.from_iterable(
+                await gather(
+                    *[self._setup(disposable) for disposable in self._disposables],
                 )
             )
-        ]
+        )
 
-    async def __aexit__(
+    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,
+        /,
         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:
         """
         Exit all contained disposables asynchronously.
@@ -146,19 +278,107 @@ class Disposables:
         BaseExceptionGroup
             If multiple disposables raise exceptions during exit
         """
-        results: list[bool | BaseException | None] = await gather(
-            *[
-                disposable.__aexit__(
+        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,
                 )
-                for disposable in self._disposables
-            ],
-            return_exceptions=True,
-        )
+
+        finally:
+            object.__setattr__(
+                self,
+                "_loop",
+                None,
+            )
 
         exceptions: list[BaseException] = [exc for exc in results if isinstance(exc, BaseException)]
 
-        if len(exceptions) > 1:
-            raise BaseExceptionGroup("Disposing errors", exceptions)
+        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.
+        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)

haiway/context/state.py

@@ -1,6 +1,7 @@
 from asyncio import iscoroutinefunction
 from collections.abc import Callable, Coroutine, Iterable, MutableMapping
 from contextvars import ContextVar, Token
+from threading import Lock
 from types import TracebackType
 from typing import Any, Self, cast, final, overload
 
@@ -24,7 +25,7 @@ class ScopeState:
     This class is immutable after initialization.
     """
 
-    __slots__ = ("_state",)
+    __slots__ = ("_lock", "_state")
 
     def __init__(
         self,
@@ -36,6 +37,12 @@ class ScopeState:
             "_state",
             {type(element): element for element in state},
         )
+        self._lock: Lock
+        object.__setattr__(
+            self,
+            "_lock",
+            Lock(),
+        )
 
     def __setattr__(
         self,
@@ -56,6 +63,51 @@ class ScopeState:
             f" attribute - '{name}' cannot be deleted"
         )
 
+    def check_state[StateType: State](
+        self,
+        state: type[StateType],
+        /,
+        *,
+        instantiate_defaults: bool = False,
+    ) -> bool:
+        """
+        Check state object availability by its type.
+
+        If the state type is not found, attempts to instantiate a new instance of\
+         the type if possible.
+
+        Parameters
+        ----------
+        state: type[StateType]
+            The type of state to check
+
+        instantiate_defaults: bool = False
+            Control if default value should be instantiated during check.
+
+        Returns
+        -------
+        bool
+            True if state is available, otherwise False.
+        """
+        if state in self._state:
+            return True
+
+        elif instantiate_defaults:
+            with self._lock:
+                if state in self._state:
+                    return True
+
+                try:
+                    initialized: StateType = state()
+                    self._state[state] = initialized
+                    return True
+
+                except BaseException:
+                    return False  # unavailable, we don't care the exception
+
+        else:
+            return False
+
     def state[StateType: State](
         self,
         state: type[StateType],
@@ -93,17 +145,20 @@ class ScopeState:
             return default
 
         else:
-            try:
-                initialized: StateType = state()
-                # we would need a locking here in multithreaded environment
-                self._state[state] = initialized
-                return initialized
-
-            except Exception as exc:
-                raise MissingState(
-                    f"{state.__qualname__} is not defined in current scope"
-                    " and failed to provide a default value"
-                ) from exc
+            with self._lock:
+                if state in self._state:
+                    return cast(StateType, self._state[state])
+
+                try:
+                    initialized: StateType = state()
+                    self._state[state] = initialized
+                    return initialized
+
+                except Exception as exc:
+                    raise MissingState(
+                        f"{state.__qualname__} is not defined in current scope"
+                        " and failed to provide a default value"
+                    ) from exc
 
     def updated(
         self,
@@ -149,6 +204,40 @@ class StateContext:
 
     _context = ContextVar[ScopeState]("StateContext")
 
+    @classmethod
+    def check_state[StateType: State](
+        cls,
+        state: type[StateType],
+        /,
+        instantiate_defaults: bool = False,
+    ) -> bool:
+        """
+        Check if state object is available in the current context.
+
+        Verifies if state object of the specified type is available the current context.
+
+        Parameters
+        ----------
+        state: type[StateType]
+            The type of state to check
+
+        instantiate_defaults: bool = False
+            Control if default value should be instantiated during check.
+
+        Returns
+        -------
+        bool
+            True if state is available, otherwise False.
+        """
+        try:
+            return cls._context.get().check_state(
+                state,
+                instantiate_defaults=instantiate_defaults,
+            )
+
+        except LookupError:
+            return False  # no context no state
+
     @classmethod
     def state[StateType: State](
         cls,

haiway/helpers/__init__.py

@@ -1,16 +1,19 @@
 from haiway.helpers.asynchrony import asynchronous
 from haiway.helpers.caching import CacheMakeKey, CacheRead, CacheWrite, cache
 from haiway.helpers.concurrent import process_concurrently
+from haiway.helpers.files import File, FileAccess
 from haiway.helpers.observability import LoggerObservability
 from haiway.helpers.retries import retry
 from haiway.helpers.throttling import throttle
-from haiway.helpers.timeouted import timeout
+from haiway.helpers.timeouting import timeout
 from haiway.helpers.tracing import traced
 
 __all__ = (
     "CacheMakeKey",
     "CacheRead",
     "CacheWrite",
+    "File",
+    "FileAccess",
     "LoggerObservability",
     "asynchronous",
     "cache",

haiway/helpers/asynchrony.py

@@ -11,12 +11,10 @@ __all__ = ("asynchronous",)
 
 
 @overload
-def asynchronous[**Args, Result]() -> (
-    Callable[
-        [Callable[Args, Result]],
-        Callable[Args, Coroutine[Any, Any, Result]],
-    ]
-): ...
+def asynchronous[**Args, Result]() -> Callable[
+    [Callable[Args, Result]],
+    Callable[Args, Coroutine[Any, Any, Result]],
+]: ...
 
 
 @overload

haiway/helpers/files.py

@@ -0,0 +1,421 @@
+try:
+    import fcntl
+
+except ModuleNotFoundError:  # Windows does not supprt fcntl
+    fcntl = None
+
+import os
+from asyncio import Lock
+from pathlib import Path
+from types import TracebackType
+from typing import Protocol, runtime_checkable
+
+from haiway.context import ctx
+from haiway.helpers.asynchrony import asynchronous
+from haiway.state import State
+
+__all__ = (
+    "File",
+    "FileAccess",
+    "FileAccessing",
+    "FileContext",
+    "FileException",
+    "FileReading",
+    "FileWriting",
+)
+
+
+class FileException(Exception):
+    """
+    Exception raised for file operation errors.
+
+    Raised when file operations fail, such as attempting to access
+    a non-existent file without the create flag, or when file I/O
+    operations encounter errors.
+    """
+
+
+@runtime_checkable
+class FileReading(Protocol):
+    """
+    Protocol for asynchronous file reading operations.
+
+    Implementations read the entire file contents and return them as bytes.
+    The file position is managed internally and reading always returns the
+    complete file contents from the beginning.
+    """
+
+    async def __call__(
+        self,
+    ) -> bytes: ...
+
+
+@runtime_checkable
+class FileWriting(Protocol):
+    """
+    Protocol for asynchronous file writing operations.
+
+    Implementations write the provided content to the file, completely
+    replacing any existing content. The write operation is atomic and
+    includes proper synchronization to ensure data is written to disk.
+    """
+
+    async def __call__(
+        self,
+        content: bytes,
+    ) -> None: ...
+
+
+class File(State):
+    """
+    State container for file operations within a context scope.
+
+    Provides access to file operations after a file has been opened using
+    FileAccess within a context scope. Follows Haiway's pattern of accessing
+    functionality through class methods that retrieve state from the current context.
+
+    The file operations are provided through the reading and writing protocol
+    implementations, which are injected when the file is opened.
+    """
+
+    @classmethod
+    async def read(
+        cls,
+    ) -> bytes:
+        """
+        Read the complete contents of the file.
+
+        Returns
+        -------
+        bytes
+            The complete file contents as bytes
+
+        Raises
+        ------
+        FileException
+            If no file is currently open in the context
+        """
+        return await ctx.state(cls).reading()
+
+    @classmethod
+    async def write(
+        cls,
+        content: bytes,
+        /,
+    ) -> None:
+        """
+        Write content to the file, replacing existing content.
+
+        Parameters
+        ----------
+        content : bytes
+            The bytes content to write to the file
+
+        Raises
+        ------
+        FileException
+            If no file is currently open in the context
+        """
+        await ctx.state(cls).writing(content)
+
+    reading: FileReading
+    writing: FileWriting
+
+
+@runtime_checkable
+class FileContext(Protocol):
+    """
+    Protocol for file context managers.
+
+    Defines the interface for file context managers that handle the opening,
+    access, and cleanup of file resources. Implementations ensure proper
+    resource management and make file operations available through the File
+    state class.
+
+    The context manager pattern ensures that file handles are properly closed
+    and locks are released even if exceptions occur during file operations.
+    """
+
+    async def __aenter__(self) -> File:
+        """
+        Enter the file context and return file operations.
+
+        Returns
+        -------
+        File
+            A File state instance configured for the opened file
+
+        Raises
+        ------
+        FileException
+            If the file cannot be opened
+        """
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None:
+        """
+        Exit the file context and clean up resources.
+
+        Parameters
+        ----------
+        exc_type : type[BaseException] | None
+            The exception type if an exception occurred
+        exc_val : BaseException | None
+            The exception value if an exception occurred
+        exc_tb : TracebackType | None
+            The exception traceback if an exception occurred
+
+        Returns
+        -------
+        bool | None
+            None to allow exceptions to propagate
+        """
+        ...
+
+
+@runtime_checkable
+class FileAccessing(Protocol):
+    """
+    Protocol for file access implementations.
+
+    Defines the interface for creating file context managers with specific
+    access patterns. Implementations handle the details of file opening,
+    locking, and resource management.
+    """
+
+    async def __call__(
+        self,
+        path: Path | str,
+        create: bool,
+        exclusive: bool,
+    ) -> FileContext: ...
+
+
+@asynchronous
+def _open_file_handle(
+    path: Path,
+    *,
+    create: bool,
+    exclusive: bool,
+) -> int:
+    file_handle: int
+    if path.exists():
+        file_handle = os.open(path, os.O_RDWR)
+
+    elif create:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        file_handle = os.open(path, os.O_RDWR | os.O_CREAT)
+
+    else:
+        raise FileException(f"File does not exist: {path}")
+
+    if exclusive and fcntl is not None:
+        fcntl.flock(file_handle, fcntl.LOCK_EX)  # pyright: ignore[reportAttributeAccessIssue] # windows
+
+    return file_handle
+
+
+@asynchronous
+def _read_file_contents(
+    file_handle: int,
+    *,
+    path: Path,
+) -> bytes:
+    os.lseek(file_handle, 0, os.SEEK_SET)
+    bytes_remaining: int = path.stat().st_size
+
+    # Read all bytes, handling partial reads
+    chunks: list[bytes] = []
+    while bytes_remaining > 0:
+        chunk: bytes = os.read(file_handle, bytes_remaining)
+        if not chunk:
+            raise FileException("Unexpected end of file during read")
+
+        bytes_remaining -= len(chunk)
+        chunks.append(chunk)
+
+    return b"".join(chunks)
+
+
+@asynchronous
+def _write_file_contents(
+    file_handle: int,
+    *,
+    content: bytes,
+) -> None:
+    os.lseek(file_handle, 0, os.SEEK_SET)
+
+    # Write all bytes, handling partial writes
+    offset: int = 0
+    while offset < len(content):
+        bytes_written: int = os.write(file_handle, content[offset:])
+        if bytes_written == 0:
+            raise FileException("Failed to write file content")
+
+        offset += bytes_written
+
+    os.ftruncate(file_handle, len(content))
+    os.fsync(file_handle)
+
+
+@asynchronous
+def _close_file_handle(
+    file_handle: int,
+    *,
+    exclusive: bool,
+) -> None:
+    if exclusive and fcntl is not None:
+        fcntl.flock(file_handle, fcntl.LOCK_UN)  # pyright: ignore[reportAttributeAccessIssue] # windows
+
+    os.close(file_handle)
+
+
+async def _file_access_context(
+    path: Path | str,
+    create: bool,
+    exclusive: bool,
+) -> FileContext:
+    file_path: Path = Path(path)
+
+    class FileAccessContext:
+        __slots__ = (
+            "_file_handle",
+            "_file_path",
+            "_lock",
+        )
+
+        def __init__(
+            self,
+            path: Path | str,
+        ) -> None:
+            self._file_handle: int | None = None
+            self._file_path: Path = Path(path)
+            self._lock: Lock = Lock()
+
+        async def __aenter__(self) -> File:
+            assert self._file_handle is None  # nosec: B101
+
+            self._file_handle = await _open_file_handle(
+                file_path,
+                create=create,
+                exclusive=exclusive,
+            )
+
+            async def read_file() -> bytes:
+                assert self._file_handle is not None  # nosec: B101
+                async with self._lock:
+                    return await _read_file_contents(
+                        self._file_handle,
+                        path=file_path,
+                    )
+
+            async def write_file(content: bytes) -> None:
+                assert self._file_handle is not None  # nosec: B101
+                async with self._lock:
+                    await _write_file_contents(
+                        self._file_handle,
+                        content=content,
+                    )
+
+            return File(
+                reading=read_file,
+                writing=write_file,
+            )
+
+        async def __aexit__(
+            self,
+            exc_type: type[BaseException] | None,
+            exc_val: BaseException | None,
+            exc_tb: TracebackType | None,
+        ) -> bool | None:
+            assert self._file_handle is not None  # nosec: B101
+            await _close_file_handle(
+                self._file_handle,
+                exclusive=exclusive,
+            )
+
+    return FileAccessContext(path=path)
+
+
+class FileAccess(State):
+    """
+    State container for file access configuration within a context scope.
+
+    Provides the entry point for file operations within Haiway's context system.
+    Follows the framework's pattern of using state classes to configure behavior
+    that can be injected and replaced for testing.
+
+    File access is scoped to the context, meaning only one file can be open
+    at a time within a given context scope. This design ensures predictable
+    resource usage and simplifies error handling.
+
+    The default implementation provides standard filesystem access with
+    optional file creation and exclusive locking. Custom implementations
+    can be injected by replacing the accessing function.
+
+    Examples
+    --------
+    Basic file operations:
+
+    >>> async with ctx.scope("app", disposables=(FileAccess.open("config.json", create=True),)):
+    ...     data = await File.read()
+    ...     await File.write(b'{"setting": "value"}')
+
+    Exclusive file access for critical operations:
+
+    >>> async with ctx.scope("app", disposables=(FileAccess.open("config.json", exclusive=True),)):
+    ...     content = await File.read()
+    ...     processed = process_data(content)
+    ...     await File.write(processed)
+    """
+
+    @classmethod
+    async def open(
+        cls,
+        path: Path | str,
+        create: bool = False,
+        exclusive: bool = False,
+    ) -> FileContext:
+        """
+        Open a file for reading and writing.
+
+        Opens a file using the configured file access implementation. The file
+        is opened with read and write permissions, and the entire file content
+        is available through the File.read() and File.write() methods.
+
+        Parameters
+        ----------
+        path : Path | str
+            The file path to open, as a Path object or string
+        create : bool, optional
+            If True, create the file and parent directories if they don't exist.
+            If False, raise FileException for missing files. Default is False
+        exclusive : bool, optional
+            If True, acquire an exclusive lock on the file for the duration of
+            the context. This prevents other processes from accessing the file
+            concurrently. Default is False
+
+        Returns
+        -------
+        FileContext
+            A FileContext that manages the file lifecycle and provides access
+            to file operations through the File state class
+
+        Raises
+        ------
+        FileException
+            If the file cannot be opened with the specified parameters, or if
+            a file is already open in the current context scope
+        """
+        return await ctx.state(cls).accessing(
+            path,
+            create=create,
+            exclusive=exclusive,
+        )
+
+    accessing: FileAccessing = _file_access_context

haiway/state/structure.py

@@ -728,6 +728,24 @@ class State(metaclass=StateMeta):
             for key in self.__ATTRIBUTES__.keys()
         )
 
+    def __hash__(self) -> int:
+        hash_values: list[int] = []
+        for key in self.__ATTRIBUTES__.keys():
+            value: Any = getattr(self, key, MISSING)
+
+            # Skip MISSING values to ensure consistent hashing
+            if value is MISSING:
+                continue
+
+            # Convert to hashable representation
+            try:
+                hash_values.append(hash(value))
+
+            except TypeError:
+                continue  # skip unhashable
+
+        return hash((self.__class__, tuple(hash_values)))
+
     def __setattr__(
         self,
         name: str,

haiway/types/missing.py

@@ -47,6 +47,9 @@ class Missing(metaclass=MissingType):
     def __bool__(self) -> bool:
         return False
 
+    def __hash__(self) -> int:
+        return hash(self.__class__)
+
     def __eq__(
         self,
         value: object,

haiway/utils/__init__.py

@@ -9,7 +9,6 @@ from haiway.utils.env import (
     load_env,
 )
 from haiway.utils.formatting import format_str
-from haiway.utils.freezing import freeze
 from haiway.utils.logs import setup_logging
 from haiway.utils.mimic import mimic_function
 from haiway.utils.noop import async_noop, noop
@@ -27,7 +26,6 @@ __all__ = (
     "async_always",
     "async_noop",
     "format_str",
-    "freeze",
     "getenv_base64",
     "getenv_bool",
     "getenv_float",

{haiway-0.21.4.dist-info → haiway-0.22.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.21.4
+Version: 0.22.1
 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.21.4.dist-info → haiway-0.22.1.dist-info}/RECORD

@@ -1,21 +1,22 @@
-haiway/__init__.py,sha256=keuz9FN8VqLamqrzvjK2IAjkdyyFcnboDrB9xkFPgXk,1861
+haiway/__init__.py,sha256=FiOAMHHawyGk9FfZU-1UflT8nmwu9J0CrG2QwrJGccw,1917
 haiway/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 haiway/context/__init__.py,sha256=1N_SvdPkTfIZDZybm3y0rY2dGrDLWTm0ryzUz2XD4f8,1174
-haiway/context/access.py,sha256=60guObLq5lYjBxSnT9iaEZI5x35Xen_doxY4oCrbn9Q,21758
-haiway/context/disposables.py,sha256=0vf6kOZ80o6oa8IuU4xQttqtzMT4ODh33XuDh4SGOnc,4742
+haiway/context/access.py,sha256=QCabyZtqqJjGTgAod1ZC3Fz3IfPsyurLo_i68RnCm4Q,25736
+haiway/context/disposables.py,sha256=AP9eZ0BPHJZfjrrfrjSzr4jONMKkR6YmhjOfnBp37so,11504
 haiway/context/identifier.py,sha256=dCCwLneXJzH__ZWFlGRUHvoCmbT4lM0QVbyokYIbUHg,5255
 haiway/context/observability.py,sha256=gLKbMPNvt5ozrfyc4TGahN8A_dFFtyCjUIMZu9_wZHA,23722
-haiway/context/state.py,sha256=tRJRvd07XObhdayz-1OcNxABqcHQRD_k_yUGsn72wDU,9541
+haiway/context/state.py,sha256=DuCtI0rMLWYbnBGXxpkbQgrX4aAftGkuK8XSd1JtdVc,11912
 haiway/context/tasks.py,sha256=pScFgeiyrXSJRDFZiYbBLi3k_DHkSlhB8rgAnYtgyrU,4925
 haiway/context/types.py,sha256=VDWXJySihfvSSPzY09PaGk6j5S9HgmAUboBGCZ8o_4k,766
-haiway/helpers/__init__.py,sha256=WzQFUHAX0NtpbdKycHywTyxfMGmid91y0vfmdIHX-NE,640
-haiway/helpers/asynchrony.py,sha256=kcGBTF7Dc2a0THH8usIq2OenspXx3KvuNrL8j7xyh80,5382
+haiway/helpers/__init__.py,sha256=PTWpavAveEB2V9Au1QuaRZwh3Rkb1bQSNvo_mxuGqlE,721
+haiway/helpers/asynchrony.py,sha256=Ddj8UdXhVczAbAC-rLpyhWa4RJ_W2Eolo45Veorq7_4,5362
 haiway/helpers/caching.py,sha256=BqgcUGQSAmXsuLi5V8EwlZzuGyutHOn1V4k7BHsGKeg,14347
 haiway/helpers/concurrent.py,sha256=xGMcan_tiETAHQs1YFmgYpA4YMFo6rIbFKvNeMlRFG8,2551
+haiway/helpers/files.py,sha256=L6vXd8gdgWx5jPL8azloU8IGoFq2xnxjMc4ufz-gdl4,11650
 haiway/helpers/observability.py,sha256=3G0eRE1WYTGRujS0mxzYbLR4MlKnoYllE8cu2Eb_23w,11073
 haiway/helpers/retries.py,sha256=52LA85HejTiSmCmTMAA9c8oUqD_VnhbTn1b3kwlU52c,9032
 haiway/helpers/throttling.py,sha256=KBWUSHdKVMC5_nRMmmoPNwfp-3AcerQ6OczJa9gNLM0,5796
-haiway/helpers/timeouted.py,sha256=GQ8-btb36f0Jq7TnorAPYXyKScNmf0nxHXCYxqGl-o8,3949
+haiway/helpers/timeouting.py,sha256=GQ8-btb36f0Jq7TnorAPYXyKScNmf0nxHXCYxqGl-o8,3949
 haiway/helpers/tracing.py,sha256=NHipA5UlngwFcAaKhXg1jTuJ-ti6AqSNxE7u7-92vWo,5409
 haiway/opentelemetry/__init__.py,sha256=TV-1C14mDAtcHhFZ29ActFQdrGH6x5KuGV9w-JlKYJg,91
 haiway/opentelemetry/observability.py,sha256=5fsHsFgjcxUcA0hIOM18lVvVdYSRO91ER52PticyzyU,25734
@@ -23,23 +24,22 @@ haiway/state/__init__.py,sha256=AaMqlMhO4zKS_XNevy3A7BHh5PxmguA-Sk_FnaNDY1Q,355
 haiway/state/attributes.py,sha256=sububiFP23aBB8RGk6OvTUp7BEY6S0kER_uHC09yins,26733
 haiway/state/path.py,sha256=bv5MI3HmUyku78k0Sz5lc7Q_Bay53iom1l3AL5KZs-4,32143
 haiway/state/requirement.py,sha256=zNTx7s8FiMZKu9EV3T6f1SOJpR4SC9X5hhL--PVWPCY,15641
-haiway/state/structure.py,sha256=KKIId-mrHAzGjYKKlvnlscMijVZVM8nDLnAwCFn1sTc,23259
+haiway/state/structure.py,sha256=CTf1l0TyKA7vkVDqA9RMdxaOVNSHwQduN2jb6H015hg,23798
 haiway/state/validation.py,sha256=eDOZKRrfd-dmdbqoHcLacdCVKmVCEpwt239EG6ljNF8,23557
 haiway/types/__init__.py,sha256=jFr5kf36SvVGdgngvik6_HzG8YNa3NVsdDDSqxVuGm4,281
 haiway/types/default.py,sha256=59chcOaoGqI2to08RamCCLluimfYbJp5xbYl3fWaLrM,4153
-haiway/types/missing.py,sha256=bVlOJN0Z04gALKj01Ah6_sWbC94mwRatdEcW7neLAsY,4188
-haiway/utils/__init__.py,sha256=HOylRgBEa0uNxEuPBupaJ28l4wEQiy98cGJi2Gtirr4,972
+haiway/types/missing.py,sha256=OfiyYUnzTk3arKWu8S6ORCEYGvcRu_mdL4j1ExdSvgI,4256
+haiway/utils/__init__.py,sha256=Zs4mJnoRL_4ssGSZqvCFuhllxMDww_8-McsI2xB0mug,917
 haiway/utils/always.py,sha256=dd6jDQ1j4DpJjTKO1J2Tv5xS8X1LnMC4kQ0D7DtKUvw,1230
 haiway/utils/collections.py,sha256=gF5tC1EaEzBfPpXrHqR0mZh8e4pRwEPSVactvfN-30M,4737
 haiway/utils/env.py,sha256=Z0uHJDFegvgzy-gM-f0uPMha9_1ldUglrD5SKNJsvYE,9445
 haiway/utils/formatting.py,sha256=jgSIGalGUBZVo2ziiNC5Y7vBYbAEwPugOiwEOrNFTcI,4039
-haiway/utils/freezing.py,sha256=HJH0SOgPCreb9o0wPeaMPMxhS9JDuzzey6UsKhuvUJU,1292
 haiway/utils/logs.py,sha256=NuwoqKQnMNi1FMIA91cVFnAPefUFeg3UIT50IOl3sJk,1571
 haiway/utils/mimic.py,sha256=xaZiUKp096QFfdSw7cNIKEWt2UIS7vf880KF54gny38,1831
 haiway/utils/noop.py,sha256=U8ocfoCgt-pY0owJDPtrRrj53cabeIXH9qCKWMQnoRk,1336
 haiway/utils/queue.py,sha256=6v2u3pA6A44IuCCTOjmCt3yLyOcm7PCRnrIGo25j-1o,6402
 haiway/utils/stream.py,sha256=lXaeveTY0-AYG5xVzcQYaiC6SUD5fUtHoMXiQcrQAAM,5723
-haiway-0.21.4.dist-info/METADATA,sha256=nxks1ZdXY-7iFAZLDZub4tH8eSgJeuF75wMtWL0rTYc,4919
-haiway-0.21.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.21.4.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
-haiway-0.21.4.dist-info/RECORD,,
+haiway-0.22.1.dist-info/METADATA,sha256=5M6G9KRMDiidXN6qWibXcpns40x11JTHCHNx5WOdD2U,4919
+haiway-0.22.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.22.1.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.22.1.dist-info/RECORD,,

haiway/utils/freezing.py

@@ -1,46 +0,0 @@
-from typing import Any
-
-__all__ = ("freeze",)
-
-
-def freeze(
-    instance: object,
-    /,
-) -> None:
-    """
-    Make an object instance immutable by preventing attribute modification.
-
-    This function modifies the given object to prevent further changes to its attributes.
-    It replaces the object's __setattr__ and __delattr__ methods with ones that raise
-    exceptions, effectively making the object immutable after this function is called.
-
-    Parameters
-    ----------
-    instance : object
-        The object instance to make immutable
-
-    Returns
-    -------
-    None
-        The object is modified in-place
-
-    Notes
-    -----
-    - This only affects direct attribute assignments and deletions
-    - Mutable objects contained within the instance can still be modified internally
-    - The object's class remains unchanged, only the specific instance is affected
-    """
-
-    def frozen_set(
-        __name: str,
-        __value: Any,
-    ) -> None:
-        raise RuntimeError(f"{instance.__class__.__qualname__} is frozen and can't be modified")
-
-    def frozen_del(
-        __name: str,
-    ) -> None:
-        raise RuntimeError(f"{instance.__class__.__qualname__} is frozen and can't be modified")
-
-    instance.__delattr__ = frozen_del
-    instance.__setattr__ = frozen_set