engin 0.0.3__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:
-    func._opt = Provide(func)  # type: ignore[union-attr]
+    """
+    A decorator for defining a Provider in a Block.
+    """
+    func._opt = Provide(func)  # type: ignore[attr-defined]
     return func
 
 
 def invoke(func: Func) -> Func:
-    func._opt = Invoke(func)  # type: ignore[union-attr]
+    """
+    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:
@@ -23,7 +55,7 @@ class Block(Iterable[Provide | Invoke]):
         self._name = block_name or f"{type(self).__name__}"
         for _, method in inspect.getmembers(self):
             if opt := getattr(method, "_opt", None):
-                if not isinstance(opt, (Provide, Invoke)):
+                if not isinstance(opt, Provide | Invoke):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
                 opt.set_block_name(self._name)
                 self._options.append(opt)

engin/_dependency.py

@@ -1,14 +1,12 @@
 import inspect
 import typing
 from abc import ABC
+from collections.abc import Awaitable, Callable
 from inspect import Parameter, Signature, isclass, iscoroutinefunction
 from typing import (
     Any,
-    Awaitable,
-    Callable,
     Generic,
     ParamSpec,
-    Type,
     TypeAlias,
     TypeVar,
     cast,
@@ -19,9 +17,7 @@ from engin._type_utils import TypeId, type_id_of
 
 P = ParamSpec("P")
 T = TypeVar("T")
-Func: TypeAlias = (
-    Callable[P, T] | Callable[P, Awaitable[T]] | Callable[[], T] | Callable[[], Awaitable[T]]
-)
+Func: TypeAlias = Callable[P, T]
 _SELF = object()
 
 
@@ -66,11 +62,29 @@ class Dependency(ABC, Generic[P, T]):
         if self._is_async:
             return await cast(Awaitable[T], self._func(*args, **kwargs))
         else:
-            return cast(T, self._func(*args, **kwargs))
+            return self._func(*args, **kwargs)
 
 
 class Invoke(Dependency):
-    def __init__(self, invocation: Func[P, T], block_name: str | None = None):
+    """
+    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)
 
     def __str__(self) -> str:
@@ -78,7 +92,13 @@ class Invoke(Dependency):
 
 
 class Entrypoint(Invoke):
-    def __init__(self, type_: Type[Any], *, block_name: str | None = None) -> None:
+    """
+    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)
 
@@ -99,7 +119,7 @@ class Entrypoint(Invoke):
 
 
 class Provide(Dependency[Any, T]):
-    def __init__(self, builder: Func[P, T], block_name: str | None = None):
+    def __init__(self, builder: Func[P, T], block_name: str | None = None) -> None:
         super().__init__(func=builder, block_name=block_name)
         self._is_multi = typing.get_origin(self.return_type) is list
 
@@ -111,14 +131,16 @@ class Provide(Dependency[Any, T]):
                 )
 
     @property
-    def return_type(self) -> Type[T]:
+    def return_type(self) -> type[T]:
         if isclass(self._func):
             return_type = self._func  # __init__ returns self
         else:
             try:
                 return_type = get_type_hints(self._func)["return"]
-            except KeyError:
-                raise RuntimeError(f"Dependency '{self.name}' requires a return typehint")
+            except KeyError as err:
+                raise RuntimeError(
+                    f"Dependency '{self.name}' requires a return typehint"
+                ) from err
 
         return return_type
 
@@ -140,7 +162,7 @@ class Provide(Dependency[Any, T]):
 class Supply(Provide, Generic[T]):
     def __init__(
         self, value: T, *, type_hint: type | None = None, block_name: str | None = None
-    ):
+    ) -> None:
         self._value = value
         self._type_hint = type_hint
         if self._type_hint is not None:
@@ -148,7 +170,7 @@ class Supply(Provide, Generic[T]):
         super().__init__(builder=self._get_val, block_name=block_name)
 
     @property
-    def return_type(self) -> Type[T]:
+    def return_type(self) -> type[T]:
         if self._type_hint is not None:
             return self._type_hint
         if isinstance(self._value, list):

engin/_engin.py

@@ -1,7 +1,12 @@
+import asyncio
 import logging
-from asyncio import Event
+import os
+import signal
+from asyncio import Event, Task
 from collections.abc import Iterable
+from contextlib import AsyncExitStack
 from itertools import chain
+from types import FrameType
 from typing import ClassVar, TypeAlias
 
 from engin import Entrypoint
@@ -16,14 +21,74 @@ LOG = logging.getLogger("engin")
 Option: TypeAlias = Invoke | Provide | Supply | Block
 _Opt: TypeAlias = Invoke | Provide | Supply
 
+_OS_IS_WINDOWS = os.name == "nt"
+
 
 class Engin:
+    """
+    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
+        import asyncio
+
+        from httpx import AsyncClient
+
+        from engin import Engin, Invoke, Provide
+
+
+        def httpx_client() -> AsyncClient:
+            return AsyncClient()
+
+
+        async def main(http_client: AsyncClient) -> None:
+            print(await http_client.get("https://httpbin.org/get"))
+
+        engin = Engin(Provide(httpx_client), Invoke(main))
+
+        asyncio.run(engin.run())
+        ```
+    """
+
     _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] = []
-        self._stop_event = Event()
+
+        self._stop_requested_event = Event()
+        self._stop_complete_event = Event()
+        self._exit_stack: AsyncExitStack = AsyncExitStack()
+        self._shutdown_task: Task | None = None
+        self._run_task: Task | None = None
 
         self._destruct_options(chain(self._LIB_OPTIONS, options))
         self._assembler = Assembler(self._providers.values())
@@ -33,36 +98,78 @@ class Engin:
         return self._assembler
 
     async def run(self) -> None:
-        await self.start()
-
-        # wait till stop signal recieved
-        await self._stop_event.wait()
+        """
+        Run the engin.
 
-        await self.stop()
+        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(_wait_for_stop_signal(self._stop_requested_event))
+        await self._stop_requested_event.wait()
+        await self._shutdown()
 
     async def start(self) -> None:
+        """
+        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] = [
             await self._assembler.assemble(invocation) for invocation in self._invokables
         ]
+
         for invocation in assembled_invocations:
-            await invocation()
+            try:
+                await invocation()
+            except Exception as err:
+                name = invocation.dependency.name
+                LOG.error(f"invocation '{name}' errored, exiting", exc_info=err)
+                return
 
         lifecycle = await self._assembler.get(Lifecycle)
-        await lifecycle.startup()
-        self._stop_event = Event()
+
+        try:
+            for hook in lifecycle.list():
+                await self._exit_stack.enter_async_context(hook)
+        except Exception as err:
+            LOG.error("lifecycle startup error, exiting", exc_info=err)
+            await self._exit_stack.aclose()
+            return
+
         LOG.info("startup complete")
 
+        self._shutdown_task = asyncio.create_task(self._shutdown_when_stopped())
+
     async def stop(self) -> None:
-        self._stop_event.set()
-        lifecycle = await self._assembler.get(Lifecycle)
-        await lifecycle.shutdown()
+        """
+        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()
+
+    async def _shutdown(self) -> None:
+        LOG.info("stopping engin")
+        await self._exit_stack.aclose()
+        self._stop_complete_event.set()
+        LOG.info("shutdown complete")
+
+    async def _shutdown_when_stopped(self) -> None:
+        await self._stop_requested_event.wait()
+        await self._shutdown()
 
     def _destruct_options(self, options: Iterable[Option]) -> None:
         for opt in options:
             if isinstance(opt, Block):
                 self._destruct_options(opt)
-            if isinstance(opt, (Provide, Supply)):
+            if isinstance(opt, Provide | Supply):
                 existing = self._providers.get(opt.return_type_id)
                 self._log_option(opt, overwrites=existing)
                 self._providers[opt.return_type_id] = opt
@@ -90,3 +197,35 @@ class Engin:
 
     def _self(self) -> "Engin":
         return self
+
+
+async def _wait_for_stop_signal(stop_requested_event: Event) -> None:
+    try:
+        # try to gracefully handle sigint/sigterm
+        if not _OS_IS_WINDOWS:
+            loop = asyncio.get_running_loop()
+            for signame in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(signame, stop_requested_event.set)
+
+            await stop_requested_event.wait()
+        else:
+            should_stop = False
+
+            # windows does not support signal_handlers, so this is the workaround
+            def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
+                nonlocal should_stop
+                if should_stop:
+                    raise KeyboardInterrupt("Forced keyboard interrupt")
+                should_stop = True
+
+            signal.signal(signal.SIGINT, ctrlc_handler)
+
+            while not should_stop:
+                # In case engin is stopped via external `stop` call.
+                if stop_requested_event.is_set():
+                    return
+                await asyncio.sleep(0.1)
+
+            stop_requested_event.set()
+    except asyncio.CancelledError:
+        pass

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,21 +1,104 @@
-from collections.abc import Callable
-from contextlib import AbstractAsyncContextManager, AsyncExitStack
+import asyncio
+import logging
+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._on_startup: list[Callable[..., None]] = []
-        self._on_shutdown: list[Callable[..., None]] = []
         self._context_managers: list[AbstractAsyncContextManager] = []
-        self._stack: AsyncExitStack = AsyncExitStack()
 
-    def register_context(self, cm: AbstractAsyncContextManager) -> None:
-        self._context_managers.append(cm)
+    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: _AnyContextManager) -> None:
+        self._cm = 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 startup(self) -> None:
-        self._stack = AsyncExitStack()
-        for cm in self._context_managers:
-            await self._stack.enter_async_context(cm)
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        try:
+            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)
 
-    async def shutdown(self) -> None:
-        await self._stack.aclose()
+    @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/ext/fastapi.py

@@ -1,4 +1,3 @@
-import typing
 from typing import ClassVar, TypeVar
 
 from engin import Engin, Invoke, Option
@@ -8,13 +7,10 @@ try:
     from fastapi import FastAPI
     from fastapi.params import Depends
     from starlette.requests import HTTPConnection
-except ImportError:
-    raise ImportError("fastapi must be installed to use the corresponding extension")
-
-
-if typing.TYPE_CHECKING:
-    from fastapi import FastAPI
-    from fastapi.params import Depends
+except ImportError as err:
+    raise ImportError(
+        "fastapi package must be installed to use the fastapi extension"
+    ) from err
 
 __all__ = ["FastAPIEngin", "Inject"]
 
@@ -27,7 +23,7 @@ def _attach_engin(
 
 
 class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]  # type: ignore[arg-type]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
     _asgi_type = FastAPI
 
 

engin-0.0.5.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.0.5
+Summary: An async-first modular application framework
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Engin 🏎️
+
+Engin is a zero-dependency application framework for modern Python.
+
+**Documentation**: https://engin.readthedocs.io/
+
+## Features ✨
+
+- **Dependency Injection** - Engin includes a fully-featured Dependency Injection system,
+  powered by type hints.
+- **Lifecycle Management** - Engin provides a simple & portable approach for attaching
+  startup and shutdown tasks to the application's lifecycle.
+- **Code Reuse** - Engin's modular components, called Blocks, work great as distributed
+  packages allowing zero boiler-plate code reuse across multiple applications. Perfect for
+  maintaining many services across your organisation.
+- **Ecosystem Compatability** - Engin ships with integrations for popular frameworks that
+  provide their own Dependency Injection, for example FastAPI, allowing you to integrate
+  Engin into existing code bases incrementally.
+- **Async Native**: Engin is an async framework, meaning first class support for async
+  dependencies. However Engin will happily run synchronous code as well.
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- **pip**:`pip install engin`
+- **poetry**: `poetry add engin`
+- **uv**: `uv add engin`
+
+## Getting Started
+
+A minimal example:
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+
+from engin import Engin, Invoke, Provide
+
+
+def httpx_client() -> AsyncClient:
+    return AsyncClient()
+
+
+async def main(http_client: AsyncClient) -> None:
+    print(await http_client.get("https://httpbin.org/get"))
+
+engin = Engin(Provide(httpx_client), Invoke(main))
+
+asyncio.run(engin.run())
+```
+

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.3.dist-info/METADATA

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: engin
-Version: 0.0.3
-Summary: An async-first modular application framework
-License-File: LICENSE
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# Engin 🏎️
-
-Engin is a zero-dependency application framework for modern Python.
-
-## Features ✨
-
-- **Lightweight**: Engin has no dependencies.
-- **Async First**: Engin provides first-class support for applications. 
-- **Dependency Injection**: Engin promotes a modular decoupled architecture in your application.
-- **Lifecycle Management**: Engin provides an simple, portable approach for implememting
-  startup and shutdown tasks.
-- **Ecosystem Compatability**: seamlessly integrate with frameworks such as FastAPI without
-  having to migrate your dependencies.
-- **Code Reuse**: Engin's modular components work great as packages and distributions. Allowing
-  low boiler-plate code reuse within your Organisation.
-
-## Installation
-
-Engin is available on PyPI, install using your favourite dependency manager:
-
-- **pip**:`pip install engin`
-- **poetry**: `poetry add engin`
-- **uv**: `uv add engin`
-
-## Getting Started
-
-A minimal example:
-
-```python
-import asyncio
-
-from httpx import AsyncClient
-
-from engin import Engin, Invoke, Provide
-
-
-def httpx_client() -> AsyncClient:
-    return AsyncClient()
-
-
-async def main(http_client: AsyncClient) -> None:
-    print(await http_client.get("https://httpbin.org/get"))
-
-engin = Engin(Provide(httpx_client), Invoke(main))
-
-asyncio.run(engin.run())
-```
-

engin-0.0.3.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=N_rSakTKM5mEW9qUfNio6WRaW6hByu8-HHBSy9UuN8Y,1149
-engin/_dependency.py,sha256=d1G3P6vYTFLJTFOh4DLu_EK5XW3rDX0ejBHGkE7JJbs,4759
-engin/_engin.py,sha256=feqRxk7fXx5VeTcRVJLPn49E5a7TqZ1ZnxUDFRxGznQ,3244
-engin/_exceptions.py,sha256=nkzTqxrW5nkcNgFDGoZ2TBtnHtO2RLk0qghM5LNAEmU,542
-engin/_lifecycle.py,sha256=zW9W7wU78JaGpOI1RqAyH6MiK0mwRZtFLBZDLB-NhX8,759
-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=vf7eB5no6eVuZyYdJZdvDYZmjJAmoKbrKhskgiSWg5g,1005
-engin-0.0.3.dist-info/METADATA,sha256=ANtqVNefuIRfbjAJNXNWAMwMHzc4GbLRvOT_2zpYI3Y,1491
-engin-0.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.3.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.3.dist-info/RECORD,,