engin 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

engin/__init__.py

@@ -3,12 +3,11 @@ from engin._assembler import Assembler
 from engin._block import Block, invoke, provide
 from engin._dependency import Entrypoint, Invoke, Provide, Supply
 from engin._engin import Engin, Option
-from engin._exceptions import AssemblyError
+from engin._exceptions import ProviderError
 from engin._lifecycle import Lifecycle
 
 __all__ = [
     "Assembler",
-    "AssemblyError",
     "Block",
     "Engin",
     "Entrypoint",
@@ -16,6 +15,7 @@ __all__ = [
     "Lifecycle",
     "Option",
     "Provide",
+    "ProviderError",
     "Supply",
     "ext",
     "invoke",

engin/_assembler.py

@@ -7,7 +7,7 @@ from inspect import BoundArguments, Signature
 from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
-from engin._exceptions import AssemblyError
+from engin._exceptions import ProviderError
 from engin._type_utils import TypeId, type_id_of
 
 LOG = logging.getLogger("engin")
@@ -17,14 +17,40 @@ T = TypeVar("T")
 
 @dataclass(slots=True, kw_only=True, frozen=True)
 class AssembledDependency(Generic[T]):
+    """
+    An AssembledDependency can be called to construct the result.
+    """
+
     dependency: Dependency[Any, T]
     bound_args: BoundArguments
 
     async def __call__(self) -> T:
+        """
+        Construct the dependency.
+
+        Returns:
+            The constructed value.
+        """
         return await self.dependency(*self.bound_args.args, **self.bound_args.kwargs)
 
 
 class Assembler:
+    """
+    A container for Providers that is responsible for building provided types.
+
+    The Assembler acts as a cache for previously built types, meaning repeat calls
+    to `get` will produce the same value.
+
+    Examples:
+        ```python
+        def build_str() -> str:
+            return "foo"
+
+        a = Assembler([Provide(build_str)])
+        await a.get(str)
+        ```
+    """
+
     def __init__(self, providers: Iterable[Provide]) -> None:
         self._providers: dict[TypeId, Provide[Any]] = {}
         self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
@@ -41,6 +67,82 @@ class Assembler:
             else:
                 self._multiproviders[type_id].append(provider)
 
+    async def assemble(self, dependency: Dependency[Any, T]) -> AssembledDependency[T]:
+        """
+        Assemble a dependency.
+
+        Given a Dependency type, such as Invoke, the Assembler constructs the types
+        required by the Dependency's signature from its providers.
+
+        Args:
+            dependency: the Dependency to assemble.
+
+        Returns:
+            An AssembledDependency, which can be awaited to construct the final value.
+        """
+        async with self._lock:
+            return AssembledDependency(
+                dependency=dependency,
+                bound_args=await self._bind_arguments(dependency.signature),
+            )
+
+    async def get(self, type_: type[T]) -> T:
+        """
+        Return the constructed value for the given type.
+
+        This method assembles the required Providers and constructs their corresponding
+        values.
+
+        If the
+
+        Args:
+            type_: the type of the desired value.
+
+        Raises:
+            LookupError: When no provider is found for the given type.
+            ProviderError: When a provider errors when trying to construct the type or
+                any of its dependent types.
+
+        Returns:
+            The constructed value.
+        """
+        type_id = type_id_of(type_)
+        if type_id in self._dependencies:
+            return cast(T, self._dependencies[type_id])
+        if type_id.multi:
+            out = []
+            if type_id not in self._multiproviders:
+                raise LookupError(f"no provider found for target type id '{type_id}'")
+            for provider in self._multiproviders[type_id]:
+                assembled_dependency = await self.assemble(provider)
+                try:
+                    out.extend(await assembled_dependency())
+                except Exception as err:
+                    raise ProviderError(
+                        provider=provider,
+                        error_type=type(err),
+                        error_message=str(err),
+                    ) from err
+            self._dependencies[type_id] = out
+            return out  # type: ignore[return-value]
+        else:
+            if type_id not in self._providers:
+                raise LookupError(f"no provider found for target type id '{type_id}'")
+            assembled_dependency = await self.assemble(self._providers[type_id])
+            try:
+                value = await assembled_dependency()
+            except Exception as err:
+                raise ProviderError(
+                    provider=self._providers[type_id],
+                    error_type=type(err),
+                    error_message=str(err),
+                ) from err
+            self._dependencies[type_id] = value
+            return value  # type: ignore[return-value]
+
+    def has(self, type_: type[T]) -> bool:
+        return type_id_of(type_) in self._providers
+
     def _resolve_providers(self, type_id: TypeId) -> Collection[Provide]:
         if type_id.multi:
             providers = self._multiproviders.get(type_id)
@@ -73,7 +175,7 @@ class Assembler:
             try:
                 value = await provider(*bound_args.args, **bound_args.kwargs)
             except Exception as err:
-                raise AssemblyError(
+                raise ProviderError(
                     provider=provider, error_type=type(err), error_message=str(err)
                 ) from err
             if provider.is_multiprovider:
@@ -102,30 +204,3 @@ class Assembler:
                 kwargs[param.name] = val
 
         return signature.bind(*args, **kwargs)
-
-    async def assemble(self, dependency: Dependency[Any, T]) -> AssembledDependency[T]:
-        async with self._lock:
-            return AssembledDependency(
-                dependency=dependency,
-                bound_args=await self._bind_arguments(dependency.signature),
-            )
-
-    async def get(self, type_: type[T]) -> T:
-        type_id = type_id_of(type_)
-        if type_id in self._dependencies:
-            return cast(T, self._dependencies[type_id])
-        if type_id.multi:
-            out = []
-            for provider in self._multiproviders[type_id]:
-                assembled_dependency = await self.assemble(provider)
-                out.extend(await assembled_dependency())
-            self._dependencies[type_id] = out
-            return out  # type: ignore[return-value]
-        else:
-            assembled_dependency = await self.assemble(self._providers[type_id])
-            value = await assembled_dependency()
-            self._dependencies[type_id] = value
-            return value  # type: ignore[return-value]
-
-    def has(self, type_: type[T]) -> bool:
-        return type_id_of(type_) in self._providers

engin/_block.py

@@ -6,16 +6,48 @@ from engin._dependency import Func, Invoke, Provide
 
 
 def provide(func: Func) -> Func:
+    """
+    A decorator for defining a Provider in a Block.
+    """
     func._opt = Provide(func)  # type: ignore[attr-defined]
     return func
 
 
 def invoke(func: Func) -> Func:
+    """
+    A decorator for defining an Invocation in a Block.
+    """
     func._opt = Invoke(func)  # type: ignore[attr-defined]
     return func
 
 
 class Block(Iterable[Provide | Invoke]):
+    """
+    A Block is a collection of providers and invocations.
+
+    Blocks are useful for grouping a collection of related providers and invocations, and
+    are themselves a valid Option type that can be passed to the Engin.
+
+    Providers are defined as methods decorated with the `provide` decorator, and similarly
+    for Invocations and the `invoke` decorator.
+
+    Examples:
+        Define a simple block.
+
+        ```python3
+        from engin import Block, provide, invoke
+
+        class MyBlock(Block):
+            @provide
+            def some_str(self) -> str:
+                return "foo"
+
+            @invoke
+            def print_str(self, string: str) -> None:
+                print(f"invoked on string '{string}')
+        ```
+    """
+
     options: ClassVar[list[Provide | Invoke]] = []
 
     def __init__(self, /, block_name: str | None = None) -> None:

engin/_dependency.py

@@ -66,6 +66,24 @@ class Dependency(ABC, Generic[P, T]):
 
 
 class Invoke(Dependency):
+    """
+    Marks a function as an Invocation.
+
+    Invocations are functions that are called prior to lifecycle startup. Invocations
+    should not be long running as the application startup will be blocked until all
+    Invocation are completed.
+
+    Invocations can be provided as an Option to the Engin or a Block.
+
+    Examples:
+        ```python3
+        def print_string(a_string: str) -> None:
+            print(f"invoking with value: '{a_string}'")
+
+        invocation = Invoke(print_string)
+        ```
+    """
+
     def __init__(self, invocation: Func[P, T], block_name: str | None = None) -> None:
         super().__init__(func=invocation, block_name=block_name)
 
@@ -74,6 +92,12 @@ class Invoke(Dependency):
 
 
 class Entrypoint(Invoke):
+    """
+    Marks a type as an Entrypoint.
+
+    Entrypoints are a short hand for no-op Invocations that can be used to
+    """
+
     def __init__(self, type_: type[Any], *, block_name: str | None = None) -> None:
         self._type = type_
         super().__init__(invocation=_noop, block_name=block_name)

engin/_engin.py

@@ -26,8 +26,26 @@ _OS_IS_WINDOWS = os.name == "nt"
 
 class Engin:
     """
-    The Engin class runs your application. It assembles the required dependencies, invokes
-    any invocations and manages your application's lifecycle.
+    The Engin is a modular application defined by a collection of options.
+
+    Users should instantiate the Engin with a number of options, where options can be an
+    instance of Provide, Invoke, or a collection of these combined in a Block.
+
+    To create a useful application, users should pass in one or more providers (Provide or
+    Supply) and at least one invocation (Invoke or Entrypoint).
+
+    When instantiated the Engin can be run. This is typically done via the `run` method,
+    but certain use cases, e.g. testing, it can be easier to use the `start` and `stop`
+    methods.
+
+    When ran the Engin takes care of the complete application lifecycle:
+    1. The Engin assembles all Invocations. Only Providers that are required to satisfy
+       the Invoke options parameters are assembled.
+    2. All Invocations are run sequentially in the order they were passed in to the Engin.
+    3. Any Lifecycle Startup defined by a provider that was assembled in order to satisfy
+       the constructors is ran.
+    4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM.
+    5. Any Lifecyce Shutdown task is ran, in the reverse order to the Startup order.
 
     Examples:
         ```python
@@ -54,6 +72,15 @@ class Engin:
     _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
 
     def __init__(self, *options: Option) -> None:
+        """
+        Initialise the class with the provided options.
+
+        Examples:
+            >>> engin = Engin(Provide(construct_a), Invoke(do_b), Supply(C()), MyBlock())
+
+        Args:
+            *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
+        """
         self._providers: dict[TypeId, Provide] = {TypeId.from_type(Engin): Provide(self._self)}
         self._invokables: list[Invoke] = []
 
@@ -72,17 +99,23 @@ class Engin:
 
     async def run(self) -> None:
         """
-        Run the Engin and wait for it to be stopped via an external signal or by calling
-        the `stop` method.
+        Run the engin.
+
+        The engin will run until it is stopped via an external signal (i.e. SIGTERM or
+        SIGINT) or the `stop` method is called on the engin.
         """
         await self.start()
-        self._run_task = asyncio.create_task(_raise_on_stop(self._stop_requested_event))
+        self._run_task = asyncio.create_task(_wait_for_stop_signal(self._stop_requested_event))
         await self._stop_requested_event.wait()
         await self._shutdown()
 
     async def start(self) -> None:
         """
-        Starts the engin, this method waits for the shutdown lifecycle to complete.
+        Start the engin.
+
+        This is an alternative to calling `run`. This method waits for the startup
+        lifecycle to complete and then returns. The caller is then responsible for
+        calling `stop`.
         """
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
@@ -113,7 +146,11 @@ class Engin:
 
     async def stop(self) -> None:
         """
-        Stops the engin, this method waits for the shutdown lifecycle to complete.
+        Stop the engin.
+
+        This method will wait for the shutdown lifecycle to complete before returning.
+        Note this method can be safely called at any point, even before the engin is
+        started.
         """
         self._stop_requested_event.set()
         await self._stop_complete_event.wait()
@@ -162,15 +199,7 @@ class Engin:
         return self
 
 
-class _StopRequested(RuntimeError):
-    pass
-
-
-async def _raise_on_stop(stop_requested_event: Event) -> None:
-    """
-    This method is based off of the Temporal Python SDK's Worker class:
-    https://github.com/temporalio/sdk-python/blob/main/temporalio/worker/_worker.py#L488
-    """
+async def _wait_for_stop_signal(stop_requested_event: Event) -> None:
     try:
         # try to gracefully handle sigint/sigterm
         if not _OS_IS_WINDOWS:
@@ -179,7 +208,6 @@ async def _raise_on_stop(stop_requested_event: Event) -> None:
                 loop.add_signal_handler(signame, stop_requested_event.set)
 
             await stop_requested_event.wait()
-            raise _StopRequested()
         else:
             should_stop = False
 

engin/_exceptions.py

@@ -3,9 +3,16 @@ from typing import Any
 from engin._dependency import Provide
 
 
-class AssemblyError(Exception):
+class ProviderError(Exception):
+    """
+    Raised when a Provider errors during Assembly.
+    """
+
     def __init__(
-        self, provider: Provide[Any], error_type: type[Exception], error_message: str
+        self,
+        provider: Provide[Any],
+        error_type: type[Exception],
+        error_message: str,
     ) -> None:
         self.provider = provider
         self.error_type = error_type

engin/_lifecycle.py

@@ -1,29 +1,83 @@
+import asyncio
 import logging
-from contextlib import AbstractAsyncContextManager
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
 from types import TracebackType
+from typing import TypeAlias, TypeGuard, cast
 
 LOG = logging.getLogger("engin")
 
+_AnyContextManager: TypeAlias = AbstractAsyncContextManager | AbstractContextManager
+
 
 class Lifecycle:
+    """
+    Allows dependencies to define startup and shutdown tasks for the application.
+
+    Lifecycle tasks are defined using Context Managers, these can be async or sync.
+
+    Lifecycle tasks should generally be defined in Providers as they are tied to the
+    construction of a given dependency, but can be used in Invocations. The Lifecycle
+    type is provided as a built-in Dependency by the Engin framework.
+
+    Examples:
+        Using a type that implements context management.
+
+        ```python
+        from httpx import AsyncClient
+
+        def my_provider(lifecycle: Lifecycle) -> AsyncClient:
+            client = AsyncClient()
+
+            # AsyncClient is a context manager
+            lifecycle.append(client)
+        ```
+
+        Defining a custom lifecycle.
+
+        ```python
+        def my_provider(lifecycle: Lifecycle) -> str:
+            @contextmanager
+            def task():
+                print("starting up!")
+                yield
+                print("shutting down!)
+
+            lifecycle.append(task)
+        ```
+    """
+
     def __init__(self) -> None:
         self._context_managers: list[AbstractAsyncContextManager] = []
 
-    def append(self, cm: AbstractAsyncContextManager) -> None:
+    def append(self, cm: _AnyContextManager, /) -> None:
+        """
+        Append a Lifecycle task to the list.
+
+        Args:
+            cm: a task defined as a ContextManager or AsyncContextManager.
+        """
         suppressed_cm = _AExitSuppressingAsyncContextManager(cm)
         self._context_managers.append(suppressed_cm)
 
     def list(self) -> list[AbstractAsyncContextManager]:
+        """
+        List all the defined tasks.
+
+        Returns:
+            A copy of the list of Lifecycle tasks.
+        """
         return self._context_managers[:]
 
 
 class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
-    def __init__(self, cm: AbstractAsyncContextManager) -> None:
+    def __init__(self, cm: _AnyContextManager) -> None:
         self._cm = cm
 
-    async def __aenter__(self) -> AbstractAsyncContextManager:
-        await self._cm.__aenter__()
-        return self._cm
+    async def __aenter__(self) -> None:
+        if self._is_async_cm(self._cm):
+            await self._cm.__aenter__()
+        else:
+            await asyncio.to_thread(cast(AbstractContextManager, self._cm).__enter__)
 
     async def __aexit__(
         self,
@@ -33,6 +87,18 @@ class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
         /,
     ) -> None:
         try:
-            await self._cm.__aexit__(exc_type, exc_value, traceback)
+            if self._is_async_cm(self._cm):
+                await self._cm.__aexit__(exc_type, exc_value, traceback)
+            else:
+                await asyncio.to_thread(
+                    cast(AbstractContextManager, self._cm).__exit__,
+                    exc_type,
+                    exc_value,
+                    traceback,
+                )
         except Exception as err:
             LOG.error("error in lifecycle hook stop, ignoring...", exc_info=err)
+
+    @staticmethod
+    def _is_async_cm(cm: _AnyContextManager) -> TypeGuard[AbstractAsyncContextManager]:
+        return hasattr(cm, "__aenter__")

engin/_type_utils.py

@@ -5,13 +5,26 @@ from typing import Any
 _implict_modules = ["builtins", "typing", "collections.abc"]
 
 
-@dataclass(frozen=True, eq=True)
+@dataclass(frozen=True, eq=True, slots=True)
 class TypeId:
+    """
+    Represents information about a Type in the Dependency Injection framework.
+    """
+
     type: type
     multi: bool
 
     @classmethod
     def from_type(cls, type_: Any) -> "TypeId":
+        """
+        Construct a TypeId from a given type.
+
+        Args:
+            type_: any type.
+
+        Returns:
+            The corresponding TypeId for that type.
+        """
         if is_multi_type(type_):
             inner_obj = typing.get_args(type_)[0]
             return TypeId(type=inner_obj, multi=True)

{engin-0.0.4.dist-info → engin-0.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.4
+Version: 0.0.5
 Summary: An async-first modular application framework
 License-File: LICENSE
 Requires-Python: >=3.10

engin-0.0.5.dist-info/RECORD

@@ -0,0 +1,16 @@
+engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
+engin/_assembler.py,sha256=VCZA_Gq4hnH5LueB_vEVqsKbGXx-nI6KQ65YhzXw-VY,7575
+engin/_block.py,sha256=-5qTp1Hdm3H54nScDGitFpcXRHLIyVHlDYATg_3dnPw,2045
+engin/_dependency.py,sha256=oh1T7oR-c9MGcZ6ZFUgPnvHRf-n6AIvpbm59R97To80,5404
+engin/_engin.py,sha256=kk3U_SZLlGYDbFbPYmErvlRqKE855yPvHBlX6XH2Row,8212
+engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
+engin/_lifecycle.py,sha256=_jQnGFj4RYXsxMpcXPJQagFOwnoTVh7oSN8oUYoYuW0,3246
+engin/_type_utils.py,sha256=C71kX2Dr-gluGSL018K4uihX3zkTe7QNWaHhFU10ZmA,2127
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/asgi.py,sha256=6vuC4zIhsvAdmwRn2I6uuUWPYfqobox1dv7skg2OWwE,1940
+engin/ext/fastapi.py,sha256=CH2Zi7Oh_Va0TJGx05e7_LqAiCsoI1qcu0Z59_rgfRk,899
+engin-0.0.5.dist-info/METADATA,sha256=7qu0kb9zWAZWkp0osgHkCqFKBwKykvYUrH4JcbmBY_M,1806
+engin-0.0.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.5.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.5.dist-info/RECORD,,

engin-0.0.4.dist-info/RECORD

@@ -1,16 +0,0 @@
-engin/__init__.py,sha256=AIE9wnwvfXwS1mwp6Sa9xtatBYyYzhWa36GKfAkEx_M,508
-engin/_assembler.py,sha256=UY97tXdHgvRi_iph_kolXZ8YTrxRjHKoIc4tAhqYOcw,5258
-engin/_block.py,sha256=Sdl9o3ZmmplZgB6pWFCbKjMemWzJXUso63p_bUg6BtM,1152
-engin/_dependency.py,sha256=G0ooXhYVauWiZ2keisot8iQXjGwdAwyvpwMtE1rjQzw,4754
-engin/_engin.py,sha256=tkW-QP-CNwKH9tr3xIZh-uvBKgyn9MrSvXjn3xLp7VU,6833
-engin/_exceptions.py,sha256=nkzTqxrW5nkcNgFDGoZ2TBtnHtO2RLk0qghM5LNAEmU,542
-engin/_lifecycle.py,sha256=LrDTrxEW6Mo0U4Nol9Rq-49Bi0UCa-7pbSCYjuSmG50,1211
-engin/_type_utils.py,sha256=naEk-lknC3Fdsd4jiP4YZAxjX3KXZN0MhFde9EV-Fmo,1835
-engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=6vuC4zIhsvAdmwRn2I6uuUWPYfqobox1dv7skg2OWwE,1940
-engin/ext/fastapi.py,sha256=CH2Zi7Oh_Va0TJGx05e7_LqAiCsoI1qcu0Z59_rgfRk,899
-engin-0.0.4.dist-info/METADATA,sha256=CMTjhIBzTSn-PYAAnV6wAVpr-32GqV_BVUg-uQgsKVY,1806
-engin-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.4.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.4.dist-info/RECORD,,