haiway 0.1.0__tar.gz → 0.3.0__tar.gz

{haiway-0.1.0/src/haiway.egg-info → haiway-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: haiway
-Version: 0.1.0
+Version: 0.3.0
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Maintainer-email: Kacper Kaliński <kacper.kalinski@miquido.com>
 License: MIT License

{haiway-0.1.0 → haiway-0.3.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "haiway"
 description = "Framework for dependency injection and state management within structured concurrency model."
-version = "0.1.0"
+version = "0.3.0"
 readme = "README.md"
 maintainers = [
   { name = "Kacper Kaliński", email = "kacper.kalinski@miquido.com" },

{haiway-0.1.0 → haiway-0.3.0}/src/haiway/__init__.py

@@ -1,20 +1,13 @@
 from haiway.context import (
-    Dependencies,
-    Dependency,
+    Disposable,
+    Disposables,
     MissingContext,
-    MissingDependency,
     MissingState,
     ScopeMetrics,
     ctx,
 )
-from haiway.helpers import (
-    asynchronous,
-    auto_retry,
-    cached,
-    throttle,
-    with_timeout,
-)
-from haiway.state import Structure
+from haiway.helpers import asynchronous, cache, retry, throttle, timeout
+from haiway.state import State
 from haiway.types import (
     MISSING,
     Missing,
@@ -45,11 +38,10 @@ __all__ = [
     "async_noop",
     "asynchronous",
     "AsyncQueue",
-    "auto_retry",
-    "cached",
+    "cache",
     "ctx",
-    "Dependencies",
-    "Dependency",
+    "Disposable",
+    "Disposables",
     "freeze",
     "frozenlist",
     "getenv_bool",
@@ -62,14 +54,14 @@ __all__ = [
     "Missing",
     "MISSING",
     "MissingContext",
-    "MissingDependency",
     "MissingState",
     "noop",
     "not_missing",
+    "retry",
     "ScopeMetrics",
     "setup_logging",
-    "Structure",
+    "State",
     "throttle",
+    "timeout",
     "when_missing",
-    "with_timeout",
 ]

haiway-0.3.0/src/haiway/context/__init__.py

@@ -0,0 +1,13 @@
+from haiway.context.access import ctx
+from haiway.context.disposables import Disposable, Disposables
+from haiway.context.metrics import ScopeMetrics
+from haiway.context.types import MissingContext, MissingState
+
+__all__ = [
+    "ctx",
+    "Disposable",
+    "Disposables",
+    "MissingContext",
+    "MissingState",
+    "ScopeMetrics",
+]

{haiway-0.1.0 → haiway-0.3.0}/src/haiway/context/access.py

@@ -5,16 +5,17 @@ from asyncio import (
 from collections.abc import (
     Callable,
     Coroutine,
+    Iterable,
 )
 from logging import Logger
 from types import TracebackType
 from typing import Any, final
 
-from haiway.context.dependencies import Dependencies, Dependency
+from haiway.context.disposables import Disposable, Disposables
 from haiway.context.metrics import MetricsContext, ScopeMetrics
 from haiway.context.state import StateContext
 from haiway.context.tasks import TaskGroupContext
-from haiway.state import Structure
+from haiway.state import State
 from haiway.utils import freeze
 
 __all__ = [
@@ -24,25 +25,41 @@ __all__ = [
 
 @final
 class ScopeContext:
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
+        trace_id: str | None,
+        name: str,
+        logger: Logger | None,
+        state: tuple[State, ...],
+        disposables: Disposables | None,
         task_group: TaskGroupContext,
-        state: StateContext,
-        metrics: MetricsContext,
         completion: Callable[[ScopeMetrics], Coroutine[None, None, None]] | None,
     ) -> None:
         self._task_group: TaskGroupContext = task_group
-        self._state: StateContext = state
-        self._metrics: MetricsContext = metrics
+        self._logger: Logger | None = logger
+        self._trace_id: str | None = trace_id
+        self._name: str = name
+        self._state_context: StateContext
+        self._state: tuple[State, ...] = state
+        self._disposables: Disposables | None = disposables
+        self._metrics_context: MetricsContext
         self._completion: Callable[[ScopeMetrics], Coroutine[None, None, None]] | None = completion
 
         freeze(self)
 
     def __enter__(self) -> None:
         assert self._completion is None, "Can't enter synchronous context with completion"  # nosec: B101
+        assert self._disposables is None, "Can't enter synchronous context with disposables"  # nosec: B101
+
+        self._state_context = StateContext.updated(self._state)
+        self._metrics_context = MetricsContext.scope(
+            self._name,
+            logger=self._logger,
+            trace_id=self._trace_id,
+        )
 
-        self._state.__enter__()
-        self._metrics.__enter__()
+        self._state_context.__enter__()
+        self._metrics_context.__enter__()
 
     def __exit__(
         self,
@@ -50,49 +67,71 @@ class ScopeContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        self._metrics.__exit__(
+        self._metrics_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
-        self._state.__exit__(
+        self._state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
     async def __aenter__(self) -> None:
-        self._state.__enter__()
-        self._metrics.__enter__()
         await self._task_group.__aenter__()
 
+        if self._disposables:
+            self._state_context = StateContext.updated(
+                (*self._state, *await self._disposables.__aenter__())
+            )
+
+        else:
+            self._state_context = StateContext.updated(self._state)
+
+        self._metrics_context = MetricsContext.scope(
+            self._name,
+            logger=self._logger,
+            trace_id=self._trace_id,
+        )
+
+        self._state_context.__enter__()
+        self._metrics_context.__enter__()
+
     async def __aexit__(
         self,
         exc_type: type[BaseException] | None,
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
+        if self._disposables:
+            await self._disposables.__aexit__(
+                exc_type=exc_type,
+                exc_val=exc_val,
+                exc_tb=exc_tb,
+            )
+
         await self._task_group.__aexit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
-        self._metrics.__exit__(
+        self._metrics_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
-        self._state.__exit__(
+        self._state_context.__exit__(
             exc_type=exc_type,
             exc_val=exc_val,
             exc_tb=exc_tb,
         )
 
         if completion := self._completion:
-            await completion(self._metrics._metrics)  # pyright: ignore[reportPrivateUsage]
+            await completion(self._metrics_context._metrics)  # pyright: ignore[reportPrivateUsage]
 
 
 @final
@@ -101,7 +140,8 @@ class ctx:
     def scope(
         name: str,
         /,
-        *state: Structure,
+        *state: State,
+        disposables: Disposables | Iterable[Disposable] | None = None,
         logger: Logger | None = None,
         trace_id: str | None = None,
         completion: Callable[[ScopeMetrics], Coroutine[None, None, None]] | None = None,
@@ -115,9 +155,14 @@ class ctx:
         name: Value
             name of the scope context
 
-        *state: Structure
-            state propagated within the scope context, will be merged with current if any\
-             by replacing current with provided on conflict
+        *state: State | Disposable
+            state propagated within the scope context, will be merged with current state by\
+             replacing current with provided on conflict.
+
+        disposables: Disposables | list[Disposable] | None
+            disposables consumed within the context when entered. Produced state will automatically\
+             be added to the scope state. Using asynchronous context is required if any disposables\
+             were provided.
 
         logger: Logger | None
             logger used within the scope context, when not provided current logger will be used\
@@ -139,20 +184,30 @@ class ctx:
             context object intended to enter context manager with it
         """
 
+        resolved_disposables: Disposables | None
+        match disposables:
+            case None:
+                resolved_disposables = None
+
+            case Disposables() as disposables:
+                resolved_disposables = disposables
+
+            case iterable:
+                resolved_disposables = Disposables(*iterable)
+
         return ScopeContext(
+            trace_id=trace_id,
+            name=name,
+            logger=logger,
+            state=state,
+            disposables=resolved_disposables,
             task_group=TaskGroupContext(),
-            metrics=MetricsContext.scope(
-                name,
-                logger=logger,
-                trace_id=trace_id,
-            ),
-            state=StateContext.updated(state),
             completion=completion,
         )
 
     @staticmethod
     def updated(
-        *state: Structure,
+        *state: State,
     ) -> StateContext:
         """
         Update scope context with given state. When called within an existing context\
@@ -160,7 +215,7 @@ class ctx:
 
         Parameters
         ----------
-        *state: Structure
+        *state: State
             state propagated within the updated scope context, will be merged with current if any\
              by replacing current with provided on conflict
 
@@ -215,28 +270,7 @@ class ctx:
             raise RuntimeError("Attempting to cancel context out of asyncio task")
 
     @staticmethod
-    async def dependency[DependencyType: Dependency](
-        dependency: type[DependencyType],
-        /,
-    ) -> DependencyType:
-        """
-        Access current dependency by its type.
-
-        Parameters
-        ----------
-        dependency: type[DependencyType]
-            type of requested dependency
-
-        Returns
-        -------
-        DependencyType
-            resolved dependency instance
-        """
-
-        return await Dependencies.dependency(dependency)
-
-    @staticmethod
-    def state[StateType: Structure](
+    def state[StateType: State](
         state: type[StateType],
         /,
         default: StateType | None = None,
@@ -261,7 +295,7 @@ class ctx:
         )
 
     @staticmethod
-    def record[Metric: Structure](
+    def record[Metric: State](
         metric: Metric,
         /,
         merge: Callable[[Metric, Metric], Metric] = lambda lhs, rhs: rhs,

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

@@ -0,0 +1,68 @@
+from asyncio import gather, shield
+from collections.abc import Iterable
+from types import TracebackType
+from typing import Protocol, final, runtime_checkable
+
+from haiway.state import State
+
+__all__ = [
+    "Disposable",
+    "Disposables",
+]
+
+
+@runtime_checkable
+class Disposable(Protocol):
+    async def initialize(self) -> State | None: ...
+    async def dispose(self) -> None: ...
+
+
+@final
+class Disposables:
+    def __init__(
+        self,
+        *disposables: Disposable,
+    ) -> None:
+        self._disposables: tuple[Disposable, ...] = disposables
+
+    async def initialize(self) -> Iterable[State]:
+        return [
+            state
+            for state in await gather(
+                *[disposable.initialize() for disposable in self._disposables],
+            )
+            if state is not None
+        ]
+
+    async def dispose(self) -> None:
+        results: list[BaseException | None] = await shield(
+            gather(
+                *[disposable.dispose() for disposable in self._disposables],
+                return_exceptions=True,
+            ),
+        )
+
+        self._disposables = ()
+        exceptions: list[BaseException] = [
+            exception for exception in results if exception is not None
+        ]
+
+        if len(exceptions) > 1:
+            raise BaseExceptionGroup("Disposing errors", exceptions)
+
+        elif exceptions:
+            raise exceptions[0]
+
+    def __bool__(self) -> bool:
+        return len(self._disposables) > 0
+
+    async def __aenter__(self) -> Iterable[State]:
+        return await self.initialize()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.dispose()

{haiway-0.1.0 → haiway-0.3.0}/src/haiway/context/metrics.py

@@ -9,7 +9,7 @@ from types import TracebackType
 from typing import Any, Self, cast, final, overload
 from uuid import uuid4
 
-from haiway.state import Structure
+from haiway.state import State
 from haiway.utils import freeze
 
 __all__ = [
@@ -30,7 +30,7 @@ class ScopeMetrics:
         self.trace_id: str = trace_id or uuid4().hex
         self._label: str = f"{self.trace_id}|{scope}" if scope else self.trace_id
         self._logger: Logger = logger or getLogger(name=scope)
-        self._metrics: dict[type[Structure], Structure] = {}
+        self._metrics: dict[type[State], State] = {}
         self._nested: list[ScopeMetrics] = []
         self._timestamp: float = monotonic()
         self._completed: Future[float] = get_event_loop().create_future()
@@ -46,11 +46,11 @@ class ScopeMetrics:
     def metrics(
         self,
         *,
-        merge: Callable[[Structure, Structure], Structure] = lambda lhs, rhs: lhs,
-    ) -> list[Structure]:
-        metrics: dict[type[Structure], Structure] = copy(self._metrics)
+        merge: Callable[[State, State], State] = lambda lhs, rhs: lhs,
+    ) -> list[State]:
+        metrics: dict[type[State], State] = copy(self._metrics)
         for metric in chain.from_iterable(nested.metrics(merge=merge) for nested in self._nested):
-            metric_type: type[Structure] = type(metric)
+            metric_type: type[State] = type(metric)
             if current := metrics.get(metric_type):
                 metrics[metric_type] = merge(current, metric)
 
@@ -60,21 +60,21 @@ class ScopeMetrics:
         return list(metrics.values())
 
     @overload
-    def read[Metric: Structure](
+    def read[Metric: State](
         self,
         metric: type[Metric],
         /,
     ) -> Metric | None: ...
 
     @overload
-    def read[Metric: Structure](
+    def read[Metric: State](
         self,
         metric: type[Metric],
         /,
         default: Metric,
     ) -> Metric: ...
 
-    def read[Metric: Structure](
+    def read[Metric: State](
         self,
         metric: type[Metric],
         /,
@@ -82,7 +82,7 @@ class ScopeMetrics:
     ) -> Metric | None:
         return cast(Metric | None, self._metrics.get(metric, default))
 
-    def record[Metric: Structure](
+    def record[Metric: State](
         self,
         metric: Metric,
         /,
@@ -187,7 +187,7 @@ class MetricsContext:
             )
 
     @classmethod
-    def record[Metric: Structure](
+    def record[Metric: State](
         cls,
         metric: Metric,
         /,

{haiway-0.1.0 → haiway-0.3.0}/src/haiway/context/state.py

@@ -4,7 +4,7 @@ from types import TracebackType
 from typing import Self, cast, final
 
 from haiway.context.types import MissingContext, MissingState
-from haiway.state import Structure
+from haiway.state import State
 from haiway.utils import freeze
 
 __all__ = [
@@ -17,28 +17,26 @@ __all__ = [
 class ScopeState:
     def __init__(
         self,
-        state: Iterable[Structure],
+        state: Iterable[State],
     ) -> None:
-        self._state: dict[type[Structure], Structure] = {
-            type(element): element for element in state
-        }
+        self._state: dict[type[State], State] = {type(element): element for element in state}
         freeze(self)
 
-    def state[State: Structure](
+    def state[StateType: State](
         self,
-        state: type[State],
+        state: type[StateType],
         /,
-        default: State | None = None,
-    ) -> State:
+        default: StateType | None = None,
+    ) -> StateType:
         if state in self._state:
-            return cast(State, self._state[state])
+            return cast(StateType, self._state[state])
 
         elif default is not None:
             return default
 
         else:
             try:
-                initialized: State = state()
+                initialized: StateType = state()
                 self._state[state] = initialized
                 return initialized
 
@@ -50,7 +48,7 @@ class ScopeState:
 
     def updated(
         self,
-        state: Iterable[Structure],
+        state: Iterable[State],
     ) -> Self:
         if state:
             return self.__class__(
@@ -69,12 +67,12 @@ class StateContext:
     _context = ContextVar[ScopeState]("StateContext")
 
     @classmethod
-    def current[State: Structure](
+    def current[StateType: State](
         cls,
-        state: type[State],
+        state: type[StateType],
         /,
-        default: State | None = None,
-    ) -> State:
+        default: StateType | None = None,
+    ) -> StateType:
         try:
             return cls._context.get().state(state, default=default)
 
@@ -84,7 +82,7 @@ class StateContext:
     @classmethod
     def updated(
         cls,
-        state: Iterable[Structure],
+        state: Iterable[State],
         /,
     ) -> Self:
         try:

{haiway-0.1.0 → haiway-0.3.0}/src/haiway/context/types.py

@@ -1,6 +1,5 @@
 __all__ = [
     "MissingContext",
-    "MissingDependency",
     "MissingState",
 ]
 
@@ -9,9 +8,5 @@ class MissingContext(Exception):
     pass
 
 
-class MissingDependency(Exception):
-    pass
-
-
 class MissingState(Exception):
     pass

haiway-0.3.0/src/haiway/helpers/__init__.py

@@ -0,0 +1,13 @@
+from haiway.helpers.asynchronous import asynchronous
+from haiway.helpers.cached import cache
+from haiway.helpers.retries import retry
+from haiway.helpers.throttling import throttle
+from haiway.helpers.timeouted import timeout
+
+__all__ = [
+    "asynchronous",
+    "cache",
+    "retry",
+    "throttle",
+    "timeout",
+]

haiway-0.1.0/src/haiway/helpers/cache.py → haiway-0.3.0/src/haiway/helpers/cached.py

@@ -9,26 +9,26 @@ from weakref import ref
 from haiway.utils.mimic import mimic_function
 
 __all__ = [
-    "cached",
+    "cache",
 ]
 
 
 @overload
-def cached[**Args, Result](
+def cache[**Args, Result](
     function: Callable[Args, Result],
     /,
 ) -> Callable[Args, Result]: ...
 
 
 @overload
-def cached[**Args, Result](
+def cache[**Args, Result](
     *,
     limit: int = 1,
     expiration: float | None = None,
 ) -> Callable[[Callable[Args, Result]], Callable[Args, Result]]: ...
 
 
-def cached[**Args, Result](
+def cache[**Args, Result](
     function: Callable[Args, Result] | None = None,
     *,
     limit: int = 1,