engin 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

engin/__init__.py

@@ -2,9 +2,11 @@ from engin import ext
 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._engin import Engin
 from engin._exceptions import ProviderError
 from engin._lifecycle import Lifecycle
+from engin._option import Option
+from engin._type_utils import TypeId
 
 __all__ = [
     "Assembler",
@@ -17,6 +19,7 @@ __all__ = [
     "Provide",
     "ProviderError",
     "Supply",
+    "TypeId",
     "ext",
     "invoke",
     "provide",

engin/_assembler.py

@@ -1,14 +1,14 @@
 import asyncio
 import logging
 from collections import defaultdict
-from collections.abc import Collection, Iterable
+from collections.abc import Iterable
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
 from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
 from engin._exceptions import ProviderError
-from engin._type_utils import TypeId, type_id_of
+from engin._type_utils import TypeId
 
 LOG = logging.getLogger("engin")
 
@@ -39,7 +39,7 @@ 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.
+    to `build` will produce the same value.
 
     Examples:
         ```python
@@ -47,15 +47,14 @@ class Assembler:
             return "foo"
 
         a = Assembler([Provide(build_str)])
-        await a.get(str)
+        await a.build(str)
         ```
     """
 
     def __init__(self, providers: Iterable[Provide]) -> None:
         self._providers: dict[TypeId, Provide[Any]] = {}
         self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
-        self._dependencies: dict[TypeId, Any] = {}
-        self._consumed_providers: set[Provide[Any]] = set()
+        self._assembled_outputs: dict[TypeId, Any] = {}
         self._lock = asyncio.Lock()
 
         for provider in providers:
@@ -86,17 +85,15 @@ class Assembler:
                 bound_args=await self._bind_arguments(dependency.signature),
             )
 
-    async def get(self, type_: type[T]) -> T:
+    async def build(self, type_: type[T]) -> T:
         """
-        Return the constructed value for the given type.
+        Build the type from Assembler's factories.
 
-        This method assembles the required Providers and constructs their corresponding
-        values.
-
-        If the
+        If the type has been built previously the value will be cached and will return the
+        same instance.
 
         Args:
-            type_: the type of the desired value.
+            type_: the type of the desired value to build.
 
         Raises:
             LookupError: When no provider is found for the given type.
@@ -106,13 +103,14 @@ class Assembler:
         Returns:
             The constructed value.
         """
-        type_id = type_id_of(type_)
-        if type_id in self._dependencies:
-            return cast(T, self._dependencies[type_id])
+        type_id = TypeId.from_type(type_)
+        if type_id in self._assembled_outputs:
+            return cast("T", self._assembled_outputs[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}'")
+
+            out = []
             for provider in self._multiproviders[type_id]:
                 assembled_dependency = await self.assemble(provider)
                 try:
@@ -123,11 +121,12 @@ class Assembler:
                         error_type=type(err),
                         error_message=str(err),
                     ) from err
-            self._dependencies[type_id] = out
+            self._assembled_outputs[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()
@@ -137,7 +136,7 @@ class Assembler:
                     error_type=type(err),
                     error_message=str(err),
                 ) from err
-            self._dependencies[type_id] = value
+            self._assembled_outputs[type_id] = value
             return value  # type: ignore[return-value]
 
     def has(self, type_: type[T]) -> bool:
@@ -150,7 +149,7 @@ class Assembler:
         Returns:
             True if the Assembler has a provider for type else False.
         """
-        type_id = type_id_of(type_)
+        type_id = TypeId.from_type(type_)
         if type_id.multi:
             return type_id in self._multiproviders
         else:
@@ -160,55 +159,64 @@ class Assembler:
         """
         Add a provider to the Assembler post-initialisation.
 
+        If this replaces an existing provider, this will clear any previously assembled
+        output for the existing Provider.
+
         Args:
             provider: the Provide instance to add.
 
         Returns:
              None
-
-        Raises:
-            ValueError: if a provider for this type already exists.
         """
         type_id = provider.return_type_id
         if provider.is_multiprovider:
-            if type_id in self._multiproviders:
-                self._multiproviders[type_id].append(provider)
-            else:
-                self._multiproviders[type_id] = [provider]
+            if type_id in self._assembled_outputs:
+                del self._assembled_outputs[type_id]
+            self._multiproviders[type_id].append(provider)
         else:
-            if type_id in self._providers:
-                raise ValueError(f"A provider for '{type_id}' already exists")
+            if type_id in self._assembled_outputs:
+                del self._assembled_outputs[type_id]
             self._providers[type_id] = provider
 
-    def _resolve_providers(self, type_id: TypeId) -> Collection[Provide]:
+    def _resolve_providers(self, type_id: TypeId) -> Iterable[Provide]:
+        """
+        Resolves the chain of providers required to satisfy the provider of a given type.
+        Ordering of the return value is very important!
+
+        # TODO: performance optimisation, do not recurse for already satisfied providers?
+        """
         if type_id.multi:
-            providers = self._multiproviders.get(type_id)
+            root_providers = self._multiproviders.get(type_id)
         else:
-            providers = [provider] if (provider := self._providers.get(type_id)) else None
-        if not providers:
+            root_providers = [provider] if (provider := self._providers.get(type_id)) else None
+
+        if not root_providers:
             if type_id.multi:
                 LOG.warning(f"no provider for '{type_id}' defaulting to empty list")
-                providers = [(Supply([], type_hint=list[type_id.type]))]  # type: ignore[name-defined]
+                root_providers = [(Supply([], as_type=list[type_id.type]))]  # type: ignore[name-defined]
                 # store default to prevent the warning appearing multiple times
-                self._multiproviders[type_id] = providers
+                self._multiproviders[type_id] = root_providers
             else:
-                raise LookupError(f"No Provider registered for dependency '{type_id}'")
-
-        required_providers: list[Provide[Any]] = []
-        for provider in providers:
-            required_providers.extend(
-                provider
-                for provider_param in provider.parameter_types
-                for provider in self._resolve_providers(provider_param)
-            )
-
-        return {*required_providers, *providers}
+                available = sorted(str(k) for k in self._providers)
+                msg = f"Missing Provider for type '{type_id}', available: {available}"
+                raise LookupError(msg)
+
+        # providers that must be satisfied to satisfy the root level providers
+        yield from (
+            child_provider
+            for root_provider in root_providers
+            for root_provider_param in root_provider.parameter_types
+            for child_provider in self._resolve_providers(root_provider_param)
+        )
+        yield from root_providers
 
     async def _satisfy(self, target: TypeId) -> None:
         for provider in self._resolve_providers(target):
-            if provider in self._consumed_providers:
+            if (
+                not provider.is_multiprovider
+                and provider.return_type_id in self._assembled_outputs
+            ):
                 continue
-            self._consumed_providers.add(provider)
             type_id = provider.return_type_id
             bound_args = await self._bind_arguments(provider.signature)
             try:
@@ -218,12 +226,12 @@ class Assembler:
                     provider=provider, error_type=type(err), error_message=str(err)
                 ) from err
             if provider.is_multiprovider:
-                if type_id in self._dependencies:
-                    self._dependencies[type_id].extend(value)
+                if type_id in self._assembled_outputs:
+                    self._assembled_outputs[type_id].extend(value)
                 else:
-                    self._dependencies[type_id] = value
+                    self._assembled_outputs[type_id] = value
             else:
-                self._dependencies[type_id] = value
+                self._assembled_outputs[type_id] = value
 
     async def _bind_arguments(self, signature: Signature) -> BoundArguments:
         args = []
@@ -232,11 +240,11 @@ class Assembler:
             if param_name == "self":
                 args.append(object())
                 continue
-            param_key = type_id_of(param.annotation)
-            has_dependency = param_key in self._dependencies
+            param_key = TypeId.from_type(param.annotation)
+            has_dependency = param_key in self._assembled_outputs
             if not has_dependency:
                 await self._satisfy(param_key)
-            val = self._dependencies[param_key]
+            val = self._assembled_outputs[param_key]
             if param.kind == param.POSITIONAL_ONLY:
                 args.append(val)
             else:

engin/_block.py

@@ -1,27 +1,48 @@
 import inspect
-from collections.abc import Iterable, Iterator
-from typing import ClassVar
+from collections.abc import Callable, Iterable, Sequence
+from itertools import chain
+from typing import TYPE_CHECKING, ClassVar
 
-from engin._dependency import Func, Invoke, Provide
+from engin._dependency import Dependency, Func, Invoke, Provide
+from engin._option import Option
 
+if TYPE_CHECKING:
+    from engin._engin import Engin
 
-def provide(func: Func) -> Func:
+
+def provide(
+    func_: Func | None = None, *, override: bool = False
+) -> Func | Callable[[Func], Func]:
     """
     A decorator for defining a Provider in a Block.
     """
-    func._opt = Provide(func)  # type: ignore[attr-defined]
-    return func
 
+    def _inner(func: Func) -> Func:
+        func._opt = Provide(func, override=override)  # type: ignore[attr-defined]
+        return func
+
+    if func_ is None:
+        return _inner
+    else:
+        return _inner(func_)
 
-def invoke(func: Func) -> Func:
+
+def invoke(func_: Func | None = None) -> Func | Callable[[Func], Func]:
     """
     A decorator for defining an Invocation in a Block.
     """
-    func._opt = Invoke(func)  # type: ignore[attr-defined]
-    return func
 
+    def _inner(func: Func) -> Func:
+        func._opt = Invoke(func)  # type: ignore[attr-defined]
+        return func
+
+    if func_ is None:
+        return _inner
+    else:
+        return _inner(func_)
 
-class Block(Iterable[Provide | Invoke]):
+
+class Block(Option):
     """
     A Block is a collection of providers and invocations.
 
@@ -48,23 +69,21 @@ class Block(Iterable[Provide | Invoke]):
         ```
     """
 
-    options: ClassVar[list[Provide | Invoke]] = []
-
-    def __init__(self, /, block_name: str | None = None) -> None:
-        self._options: list[Provide | Invoke] = self.options[:]
-        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):
+    name: ClassVar[str | None] = None
+    options: ClassVar[Sequence[Option]] = []
+
+    @classmethod
+    def apply(cls, engin: "Engin") -> None:
+        block_name = cls.name or f"{cls.__name__}"
+        for option in chain(cls.options, cls._method_options()):
+            if isinstance(option, Dependency):
+                option._block_name = block_name
+            option.apply(engin)
+
+    @classmethod
+    def _method_options(cls) -> Iterable[Provide | Invoke]:
+        for _, method in inspect.getmembers(cls):
+            if option := getattr(method, "_opt", None):
+                if not isinstance(option, Provide | Invoke):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
-                opt.set_block_name(self._name)
-                self._options.append(opt)
-        for opt in self.options:
-            opt.set_block_name(self._name)
-
-    @property
-    def name(self) -> str:
-        return self._name
-
-    def __iter__(self) -> Iterator[Provide | Invoke]:
-        return iter(self._options)
+                yield option

engin/_cli/__init__.py

@@ -0,0 +1,13 @@
+try:
+    import typer
+except ImportError:
+    raise ImportError(
+        "Unable to import typer, to use the engin cli please install the"
+        " `cli` extra, e.g. pip install engin[cli]"
+    ) from None
+
+from engin._cli._graph import cli as graph_cli
+
+app = typer.Typer()
+
+app.add_typer(graph_cli)

engin/{scripts/graph.py → _cli/_graph.py}

@@ -1,63 +1,76 @@
+import contextlib
 import importlib
 import logging
 import socketserver
 import sys
 import threading
-from argparse import ArgumentParser
 from http.server import BaseHTTPRequestHandler
 from time import sleep
-from typing import Any
+from typing import Annotated, Any
+
+import typer
+from rich import print
 
 from engin import Engin, Entrypoint, Invoke
+from engin._cli._utils import print_error
 from engin._dependency import Dependency, Provide, Supply
 from engin.ext.asgi import ASGIEngin
-from engin.ext.fastapi import APIRouteDependency
+
+try:
+    from engin.ext.fastapi import APIRouteDependency
+except ImportError:
+    APIRouteDependency = None  # type: ignore[assignment,misc]
+
+cli = typer.Typer()
+
 
 # mute logging from importing of files + engin's debug logging.
 logging.disable()
 
-args = ArgumentParser(
-    prog="engin-graph",
-    description="Creates a visualisation of your application's dependencies",
-)
-args.add_argument(
-    "app",
-    help=(
-        "the import path of your Engin instance, in the form "
-        "'package:application', e.g. 'app.main:engin'"
-    ),
-)
 
 _APP_ORIGIN = ""
 
-
-def serve_graph() -> None:
+_CLI_HELP = {
+    "app": (
+        "The import path of your Engin instance, in the form 'package:application'"
+        ", e.g. 'app.main:engin'"
+    )
+}
+
+
+@cli.command(name="graph")
+def serve_graph(
+    app: Annotated[
+        str,
+        typer.Argument(help=_CLI_HELP["app"]),
+    ],
+) -> None:
+    """
+    Creates a visualisation of your application's dependencies.
+    """
     # add cwd to path to enable local package imports
     sys.path.insert(0, "")
 
-    parsed = args.parse_args()
-
-    app = parsed.app
-
     try:
         module_name, engin_name = app.split(":", maxsplit=1)
     except ValueError:
-        raise ValueError(
-            "Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'"
-        ) from None
+        print_error("Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'")
 
     global _APP_ORIGIN
     _APP_ORIGIN = module_name.split(".", maxsplit=1)[0]
 
-    module = importlib.import_module(module_name)
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError:
+        print_error(f"unable to find module '{module_name}'")
 
     try:
         instance = getattr(module, engin_name)
-    except LookupError:
-        raise LookupError(f"Module '{module_name}' has no attribute '{engin_name}'") from None
+    except AttributeError:
+        print_error(f"module '{module_name}' has no attribute '{engin_name}'")
 
     if not isinstance(instance, Engin):
-        raise TypeError(f"'{app}' is not an Engin instance")
+        print_error(f"'{app}' is not an Engin instance")
 
     nodes = instance.graph()
 
@@ -96,10 +109,14 @@ def serve_graph() -> None:
     server_thread.daemon = True  # Daemonize the thread so it exits when the main script exits
     server_thread.start()
 
-    try:
-        sleep(10000)
-    except KeyboardInterrupt:
-        print("Exiting the server...")
+    with contextlib.suppress(KeyboardInterrupt):
+        wait_for_interrupt()
+
+    print("Exiting the server...")
+
+
+def wait_for_interrupt() -> None:
+    sleep(10000)
 
 
 _BLOCK_IDX: dict[str, int] = {}

engin/_cli/_utils.py

@@ -0,0 +1,18 @@
+from typing import Never
+
+import typer
+from rich import print
+from rich.panel import Panel
+
+
+def print_error(msg: str) -> Never:
+    print(
+        Panel(
+            title="Error",
+            renderable=msg.capitalize(),
+            title_align="left",
+            border_style="red",
+            highlight=True,
+        )
+    )
+    raise typer.Exit(code=1)

engin/_dependency.py

@@ -3,8 +3,8 @@ import typing
 from abc import ABC
 from collections.abc import Awaitable, Callable
 from inspect import Parameter, Signature, isclass, iscoroutinefunction
-from types import FrameType
 from typing import (
+    TYPE_CHECKING,
     Any,
     Generic,
     ParamSpec,
@@ -14,7 +14,12 @@ from typing import (
     get_type_hints,
 )
 
-from engin._type_utils import TypeId, type_id_of
+from engin._introspect import get_first_external_frame
+from engin._option import Option
+from engin._type_utils import TypeId
+
+if TYPE_CHECKING:
+    from engin._engin import Engin
 
 P = ParamSpec("P")
 T = TypeVar("T")
@@ -24,23 +29,16 @@ Func: TypeAlias = Callable[P, T]
 def _noop(*args: Any, **kwargs: Any) -> None: ...
 
 
-def _walk_stack() -> FrameType:
-    stack = inspect.stack()[1]
-    frame = stack.frame
-    while True:
-        if frame.f_globals["__package__"] != "engin" or frame.f_back is None:
-            return frame
-        else:
-            frame = frame.f_back
-
-
-class Dependency(ABC, Generic[P, T]):
-    def __init__(self, func: Func[P, T], block_name: str | None = None) -> None:
+class Dependency(ABC, Option, Generic[P, T]):
+    def __init__(self, func: Func[P, T]) -> None:
         self._func = func
         self._is_async = iscoroutinefunction(func)
         self._signature = inspect.signature(self._func)
-        self._block_name = block_name
-        self._source_frame = _walk_stack()
+        self._block_name: str | None = None
+
+        source_frame = get_first_external_frame()
+        self._source_package = cast("str", source_frame.frame.f_globals["__package__"])
+        self._source_frame = cast("str", source_frame.frame.f_globals["__name__"])
 
     @property
     def source_module(self) -> str:
@@ -50,7 +48,7 @@ class Dependency(ABC, Generic[P, T]):
         Returns:
             A string, e.g. "examples.fastapi.app"
         """
-        return self._source_frame.f_globals["__name__"]  # type: ignore[no-any-return]
+        return self._source_frame
 
     @property
     def source_package(self) -> str:
@@ -60,7 +58,7 @@ class Dependency(ABC, Generic[P, T]):
         Returns:
             A string, e.g. "engin"
         """
-        return self._source_frame.f_globals["__package__"]  # type: ignore[no-any-return]
+        return self._source_package
 
     @property
     def block_name(self) -> str | None:
@@ -84,18 +82,15 @@ class Dependency(ABC, Generic[P, T]):
             return []
         if parameters[0].name == "self":
             parameters.pop(0)
-        return [type_id_of(param.annotation) for param in parameters]
+        return [TypeId.from_type(param.annotation) for param in parameters]
 
     @property
     def signature(self) -> Signature:
         return self._signature
 
-    def set_block_name(self, name: str) -> None:
-        self._block_name = name
-
     async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
         if self._is_async:
-            return await cast(Awaitable[T], self._func(*args, **kwargs))
+            return await cast("Awaitable[T]", self._func(*args, **kwargs))
         else:
             return self._func(*args, **kwargs)
 
@@ -119,8 +114,11 @@ class Invoke(Dependency):
         ```
     """
 
-    def __init__(self, invocation: Func[P, T], block_name: str | None = None) -> None:
-        super().__init__(func=invocation, block_name=block_name)
+    def __init__(self, invocation: Func[P, T]) -> None:
+        super().__init__(func=invocation)
+
+    def apply(self, engin: "Engin") -> None:
+        engin._invocations.append(self)
 
     def __str__(self) -> str:
         return f"Invoke({self.name})"
@@ -133,13 +131,13 @@ class Entrypoint(Invoke):
     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:
+    def __init__(self, type_: type[Any]) -> None:
         self._type = type_
-        super().__init__(invocation=_noop, block_name=block_name)
+        super().__init__(invocation=_noop)
 
     @property
     def parameter_types(self) -> list[TypeId]:
-        return [type_id_of(self._type)]
+        return [TypeId.from_type(self._type)]
 
     @property
     def signature(self) -> Signature:
@@ -150,12 +148,21 @@ class Entrypoint(Invoke):
         )
 
     def __str__(self) -> str:
-        return f"Entrypoint({type_id_of(self._type)})"
+        return f"Entrypoint({TypeId.from_type(self._type)})"
 
 
 class Provide(Dependency[Any, T]):
-    def __init__(self, builder: Func[P, T], block_name: str | None = None) -> None:
-        super().__init__(func=builder, block_name=block_name)
+    def __init__(self, builder: Func[P, T], *, override: bool = False) -> None:
+        """
+        Provide a type via a builder or factory function.
+
+        Args:
+            builder: the builder function that returns the type.
+            override: allow this provider to override existing providers from the same
+                package.
+        """
+        super().__init__(func=builder)
+        self._override = override
         self._is_multi = typing.get_origin(self.return_type) is list
 
         # Validate that the provider does to depend on its own output value, as this will
@@ -190,12 +197,36 @@ class Provide(Dependency[Any, T]):
 
     @property
     def return_type_id(self) -> TypeId:
-        return type_id_of(self.return_type)
+        return TypeId.from_type(self.return_type)
 
     @property
     def is_multiprovider(self) -> bool:
         return self._is_multi
 
+    def apply(self, engin: "Engin") -> None:
+        type_id = self.return_type_id
+        if self.is_multiprovider:
+            engin._multiproviders[type_id].append(self)
+            return
+
+        if type_id not in engin._providers:
+            engin._providers[type_id] = self
+            return
+
+        existing_provider = engin._providers[type_id]
+        is_same_package = existing_provider.source_package == self.source_package
+
+        # overwriting a dependency from the same package must be explicit
+        if is_same_package and not self._override:
+            msg = (
+                f"Provider '{self.name}' is implicitly overriding "
+                f"'{existing_provider.name}', if this is intended specify "
+                "`override=True` for the overriding Provider"
+            )
+            raise RuntimeError(msg)
+
+        engin._providers[type_id] = self
+
     def __hash__(self) -> int:
         return hash(self.return_type_id)
 
@@ -205,13 +236,27 @@ 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
+        self, value: T, *, as_type: type | None = None, override: bool = False
     ) -> None:
+        """
+        Supply a value.
+
+        This is a shorthand which under the hood creates a Provider with a noop factory
+        function.
+
+        Args:
+            value: the value to Supply
+            as_type: allows you to specify the provided type, useful for type erasing,
+              e.g. Supply a concrete value but specify it as an interface or other
+              abstraction.
+            override: allow this provider to override existing providers from the same
+              package.
+        """
         self._value = value
-        self._type_hint = type_hint
+        self._type_hint = as_type
         if self._type_hint is not None:
-            self._get_val.__annotations__["return"] = type_hint
-        super().__init__(builder=self._get_val, block_name=block_name)
+            self._get_val.__annotations__["return"] = as_type
+        super().__init__(builder=self._get_val, override=override)
 
     @property
     def return_type(self) -> type[T]:

engin/_engin.py

@@ -3,26 +3,21 @@ import logging
 import os
 import signal
 from asyncio import Event, Task
-from collections.abc import Iterable
+from collections import defaultdict
 from contextlib import AsyncExitStack
 from itertools import chain
 from types import FrameType
-from typing import ClassVar, TypeAlias
+from typing import ClassVar
 
-from engin import Entrypoint
 from engin._assembler import AssembledDependency, Assembler
-from engin._block import Block
-from engin._dependency import Dependency, Invoke, Provide, Supply
+from engin._dependency import Invoke, Provide, Supply
 from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
+from engin._option import Option
 from engin._type_utils import TypeId
 
-LOG = logging.getLogger("engin")
-
-Option: TypeAlias = Invoke | Provide | Supply | Block
-_Opt: TypeAlias = Invoke | Provide | Supply
-
 _OS_IS_WINDOWS = os.name == "nt"
+LOG = logging.getLogger("engin")
 
 
 class Engin:
@@ -88,12 +83,16 @@ class Engin:
         self._shutdown_task: Task | None = None
         self._run_task: Task | None = None
 
-        # TODO: refactor _destruct_options and related attributes into a dedicated class?
-        self._providers: dict[TypeId, Provide] = {TypeId.from_type(Engin): Provide(self._self)}
-        self._multiproviders: dict[TypeId, list[Provide]] = {}
+        self._providers: dict[TypeId, Provide] = {
+            TypeId.from_type(Engin): Supply(self, as_type=Engin)
+        }
+        self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
+
         # populates the above
-        self._destruct_options(chain(self._LIB_OPTIONS, options))
+        for option in chain(self._LIB_OPTIONS, options):
+            option.apply(self)
+
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]
         self._assembler = Assembler(chain(self._providers.values(), multi_providers))
 
@@ -111,7 +110,6 @@ class 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:
         """
@@ -134,14 +132,18 @@ class Engin:
                 LOG.error(f"invocation '{name}' errored, exiting", exc_info=err)
                 return
 
-        lifecycle = await self._assembler.get(Lifecycle)
+        lifecycle = await self._assembler.build(Lifecycle)
 
         try:
             for hook in lifecycle.list():
-                await self._exit_stack.enter_async_context(hook)
+                await asyncio.wait_for(self._exit_stack.enter_async_context(hook), timeout=15)
         except Exception as err:
-            LOG.error("lifecycle startup error, exiting", exc_info=err)
-            await self._exit_stack.aclose()
+            if isinstance(err, TimeoutError):
+                msg = "lifecycle startup task timed out after 15s, exiting"
+            else:
+                msg = "lifecycle startup task errored, exiting"
+            LOG.error(msg, exc_info=err)
+            await self._shutdown()
             return
 
         LOG.info("startup complete")
@@ -175,46 +177,6 @@ class Engin:
         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 not opt.is_multiprovider:
-                    existing = self._providers.get(opt.return_type_id)
-                    self._log_option(opt, overwrites=existing)
-                    self._providers[opt.return_type_id] = opt
-                else:
-                    self._log_option(opt)
-                    if opt.return_type_id in self._multiproviders:
-                        self._multiproviders[opt.return_type_id].append(opt)
-                    else:
-                        self._multiproviders[opt.return_type_id] = [opt]
-            elif isinstance(opt, Invoke):
-                self._log_option(opt)
-                self._invocations.append(opt)
-
-    @staticmethod
-    def _log_option(opt: Dependency, overwrites: Dependency | None = None) -> None:
-        if overwrites is not None:
-            extra = f"\tOVERWRITES {overwrites.name}"
-            if overwrites.block_name:
-                extra += f" [{overwrites.block_name}]"
-        else:
-            extra = ""
-        if isinstance(opt, Supply):
-            LOG.debug(f"SUPPLY      {opt.return_type_id!s:<35}{extra}")
-        elif isinstance(opt, Provide):
-            LOG.debug(f"PROVIDE     {opt.return_type_id!s:<35} <- {opt.name}() {extra}")
-        elif isinstance(opt, Entrypoint):
-            type_id = opt.parameter_types[0]
-            LOG.debug(f"ENTRYPOINT  {type_id!s:<35}")
-        elif isinstance(opt, Invoke):
-            LOG.debug(f"INVOKE      {opt.name:<35}")
-
-    def _self(self) -> "Engin":
-        return self
-
 
 async def _wait_for_stop_signal(stop_requested_event: Event) -> None:
     try:

engin/_introspect.py

@@ -0,0 +1,34 @@
+import inspect
+from collections.abc import Iterable
+from inspect import FrameInfo
+
+
+def walk_stack() -> Iterable[FrameInfo]:
+    """
+    Fast alternative to `inspect.stack()`
+
+    Compared to `inspect.stack()`:
+     - Does not read source files to load neighboring context
+     - Less accurate filename determination, still correct for most cases
+     - Does not compute 3.11+ code positions (PEP 657)
+    """
+
+    frame = inspect.currentframe()
+
+    while frame := frame and frame.f_back:
+        yield inspect.FrameInfo(
+            frame,
+            inspect.getfile(frame),
+            frame.f_lineno,
+            frame.f_code.co_name,
+            None,
+            None,
+        )
+
+
+def get_first_external_frame() -> FrameInfo:
+    for frame_info in walk_stack():
+        frame = frame_info.frame
+        if frame.f_globals["__package__"] != "engin" or frame.f_back is None:
+            return frame_info
+    raise RuntimeError("Unable to find external frame")

engin/_lifecycle.py

@@ -1,12 +1,15 @@
 import asyncio
 import logging
+from collections.abc import Awaitable, Callable
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from inspect import iscoroutinefunction
 from types import TracebackType
 from typing import TypeAlias, TypeGuard, cast
 
 LOG = logging.getLogger("engin")
 
 _AnyContextManager: TypeAlias = AbstractAsyncContextManager | AbstractContextManager
+_ParameterlessCallable: TypeAlias = Callable[[], None | Awaitable[None]]
 
 
 class Lifecycle:
@@ -44,6 +47,18 @@ class Lifecycle:
 
             lifecycle.append(task)
         ```
+
+        Defining a custom lifecycle using a LifecycleHook.
+
+        ```python
+        def my_provider(lifecycle: Lifecycle) -> str:
+            connection_pool = ConnectionPool()
+
+            lifecycle.hook(
+                on_start=connection_pool.connect,
+                on_stop=connection_pool.close,
+            )
+        ```
     """
 
     def __init__(self) -> None:
@@ -59,6 +74,25 @@ class Lifecycle:
         suppressed_cm = _AExitSuppressingAsyncContextManager(cm)
         self._context_managers.append(suppressed_cm)
 
+    def hook(
+        self,
+        *,
+        on_start: _ParameterlessCallable | None = None,
+        on_stop: _ParameterlessCallable | None = None,
+    ) -> None:
+        """
+        Append a hook to the Lifecycle.
+
+        At least one of `on_start` or `on_stop` must be provided.
+
+        Args:
+            on_start: a callable to be executed on Lifecycle startup.
+            on_stop: a callable to be executed on Lifecycle shutdown.
+        """
+        if on_start is None and on_stop is None:
+            raise ValueError("At least one of on_start or on_stop must be provided")
+        self.append(LifecycleHook(on_start=on_start, on_stop=on_stop))
+
     def list(self) -> list[AbstractAsyncContextManager]:
         """
         List all the defined tasks.
@@ -69,6 +103,38 @@ class Lifecycle:
         return self._context_managers[:]
 
 
+class LifecycleHook(AbstractAsyncContextManager):
+    def __init__(
+        self,
+        on_start: _ParameterlessCallable | None = None,
+        on_stop: _ParameterlessCallable | None = None,
+    ) -> None:
+        self._on_start = on_start
+        self._on_stop = on_stop
+
+    async def __aenter__(self) -> None:
+        if self._on_start is not None:
+            func = self._on_start
+            if iscoroutinefunction(func):
+                await func()
+            else:
+                await asyncio.to_thread(func)
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        if self._on_stop is not None:
+            func = self._on_stop
+            if iscoroutinefunction(func):
+                await func()
+            else:
+                await asyncio.to_thread(func)
+
+
 class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
     def __init__(self, cm: _AnyContextManager) -> None:
         self._cm = cm
@@ -77,7 +143,7 @@ class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
         if self._is_async_cm(self._cm):
             await self._cm.__aenter__()
         else:
-            await asyncio.to_thread(cast(AbstractContextManager, self._cm).__enter__)
+            await asyncio.to_thread(cast("AbstractContextManager", self._cm).__enter__)
 
     async def __aexit__(
         self,
@@ -91,7 +157,7 @@ class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
                 await self._cm.__aexit__(exc_type, exc_value, traceback)
             else:
                 await asyncio.to_thread(
-                    cast(AbstractContextManager, self._cm).__exit__,
+                    cast("AbstractContextManager", self._cm).__exit__,
                     exc_type,
                     exc_value,
                     traceback,

engin/_option.py

@@ -0,0 +1,10 @@
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from engin._engin import Engin
+
+
+class Option(Protocol):
+    @abstractmethod
+    def apply(self, engin: "Engin") -> None: ...

engin/_type_utils.py

@@ -6,7 +6,7 @@ from typing import Any
 _implict_modules = ["builtins", "typing", "collections.abc", "types"]
 
 
-@dataclass(frozen=True, eq=True, slots=True)
+@dataclass(frozen=True, slots=True)
 class TypeId:
     """
     Represents information about a Type in the Dependency Injection framework.
@@ -26,7 +26,7 @@ class TypeId:
         Returns:
             The corresponding TypeId for that type.
         """
-        if is_multi_type(type_):
+        if _is_multi_type(type_):
             inner_obj = typing.get_args(type_)[0]
             return TypeId(type=inner_obj, multi=True)
         else:
@@ -40,6 +40,11 @@ class TypeId:
             out += "[]"
         return out
 
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, TypeId):
+            return False
+        return self.type == other.type and self.multi == other.multi
+
 
 def _args_to_str(type_: Any) -> str:
     args = typing.get_args(type_)
@@ -65,14 +70,7 @@ def _args_to_str(type_: Any) -> str:
     return arg_str
 
 
-def type_id_of(type_: Any) -> TypeId:
-    """
-    Generates a string TypeId for any type.
-    """
-    return TypeId.from_type(type_)
-
-
-def is_multi_type(type_: Any) -> bool:
+def _is_multi_type(type_: Any) -> bool:
     """
     Discriminates a type to determine whether it is the return type of a multiprovider.
     """

engin/ext/asgi.py

@@ -42,6 +42,7 @@ class ASGIEngin(Engin, ASGIType):
                 except Exception as err:
                     exc = "".join(traceback.format_exception(err))
                     await send({"type": "lifespan.startup.failed", "message": exc})
+                    raise
 
             elif message["type"] == "lifespan.shutdown":
                 await self.stop()
@@ -49,8 +50,8 @@ class ASGIEngin(Engin, ASGIType):
         await self._asgi_app(scope, receive, send)
 
     async def _startup(self) -> None:
+        self._asgi_app = await self._assembler.build(self._asgi_type)
         await self.start()
-        self._asgi_app = await self._assembler.get(self._asgi_type)
 
     def graph(self) -> list[Node]:
         grapher = DependencyGrapher({**self._providers, **self._multiproviders})

engin/ext/fastapi.py

@@ -9,7 +9,7 @@ from fastapi.routing import APIRoute
 from engin import Assembler, Engin, Entrypoint, Invoke, Option
 from engin._dependency import Dependency, Supply, _noop
 from engin._graph import DependencyGrapher, Node
-from engin._type_utils import TypeId, type_id_of
+from engin._type_utils import TypeId
 from engin.ext.asgi import ASGIEngin
 
 try:
@@ -33,7 +33,10 @@ def _attach_assembler(app: FastAPI, engin: Engin) -> None:
 
 
 class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_assembler)]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [
+        *ASGIEngin._LIB_OPTIONS,
+        Invoke(_attach_assembler),
+    ]
     _asgi_type = FastAPI
 
     def graph(self) -> list[Node]:
@@ -55,7 +58,7 @@ def Inject(interface: type[T]) -> Depends:
             assembler: Assembler = conn.app.state.assembler
         except AttributeError:
             raise RuntimeError("Assembler is not attached to Application state") from None
-        return await assembler.get(interface)
+        return await assembler.build(interface)
 
     dep = Depends(inner)
     dep.__engin__ = True  # type: ignore[attr-defined]
@@ -140,7 +143,8 @@ class APIRouteDependency(Dependency):
         """
         Warning: this should never be constructed in application code.
         """
-        super().__init__(_noop, wraps.block_name)
+        super().__init__(_noop)
+        self._block_name = wraps.block_name
         self._wrapped = wraps
         self._route = route
         self._signature = inspect.signature(route.endpoint)
@@ -165,7 +169,7 @@ class APIRouteDependency(Dependency):
         if parameters[0].name == "self":
             parameters.pop(0)
         return [
-            type_id_of(typing.get_args(param.annotation)[0])
+            TypeId.from_type(typing.get_args(param.annotation)[0])
             for param in parameters
             if self._is_injected_param(param)
         ]
@@ -183,3 +187,6 @@ class APIRouteDependency(Dependency):
     def name(self) -> str:
         methods = ",".join(self._route.methods)
         return f"{methods} {self._route.path}"
+
+    def apply(self, engin: Engin) -> None:
+        raise NotImplementedError("APIRouteDependency is not a real dependency")

{engin-0.0.13.dist-info → engin-0.0.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.13
+Version: 0.0.15
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
@@ -10,6 +10,8 @@ License-Expression: MIT
 License-File: LICENSE
 Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
+Provides-Extra: cli
+Requires-Dist: typer>=0.15; extra == 'cli'
 Description-Content-Type: text/markdown
 
 [![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)

engin-0.0.15.dist-info/RECORD

@@ -0,0 +1,23 @@
+engin/__init__.py,sha256=rBTteMLAVKg4TJSaMElJUwz72BA_X7nBTREg-I-bWhA,584
+engin/_assembler.py,sha256=GpTLW9AmGChnwWWK3SUq5AsxJJ8ukH7yWpemBiH87pw,9294
+engin/_block.py,sha256=Ypl6ffU52dgrHHgCcPokzfRD2-Lbu9b2wYMCgAZIx4g,2578
+engin/_dependency.py,sha256=w-MxF6Ju1Rc2umc7pk3bXTlc65NVIs1VEBj8825WEcg,8328
+engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
+engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
+engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
+engin/_introspect.py,sha256=VdREX6Lhhga5SnEP9G7mjHkgJR4mpqk_SMnmL2zTcqY,966
+engin/_lifecycle.py,sha256=cSWe3euZkmpxmUPFvph2lsTtvuZbxttEfBL-RnOI7lo,5325
+engin/_option.py,sha256=nZcdrehp1QwgxMUoIpsM0PJuu1q1pbXzhcVsetbsHpc,223
+engin/_type_utils.py,sha256=Pmm4m1_WdevT5KTe8tzY_BseNxPyhu_nKsLGgyNcPpo,2247
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/_cli/__init__.py,sha256=lp1KiBpcgk_dZU5V9DjgLPwmp0ja444fwLH2CYCscNc,302
+engin/_cli/_graph.py,sha256=1Kj09BnKh5BTmuM4tqaGICS4KVDGNWT4oGFIrUa9xdU,6230
+engin/_cli/_utils.py,sha256=AQFtLO8qjYRCTQc9A8Z1HVf7eZr8iGWogxbYzsgIkS4,360
+engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/asgi.py,sha256=6V5Aad37MyGzkCtU5TlDrm0o5C04Un_LLvcomxnAmHY,3196
+engin/ext/fastapi.py,sha256=e8UV521Mq9Iqr55CT7_jtd51iaIZjWlAacoqFBXsh-k,6356
+engin-0.0.15.dist-info/METADATA,sha256=qYhQHzJ_YrJEaZ_p4ddZL4OZDOtzWHkQFLimPH_XNDE,2354
+engin-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.15.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.0.15.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.15.dist-info/RECORD,,

engin-0.0.15.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+engin = engin._cli:app

engin-0.0.13.dist-info/RECORD

@@ -1,20 +0,0 @@
-engin/__init__.py,sha256=yTc8k0HDGMIrxDdEEA90qGD_dExQjVIbXCyaOFRrnMg,508
-engin/_assembler.py,sha256=1ODW3HenDlIQLetg0LNEPPbsI6HkFnPU_AHzkR9Zxmc,8844
-engin/_block.py,sha256=0QJtqyP5uTFjXsdVGr4ZONLI2LhfzUKmQGnNQWouB3o,2121
-engin/_dependency.py,sha256=RWOyGpMFp_5aLq5TP2wLKz0HT5f6CRoLvFyWvVif9jY,6825
-engin/_engin.py,sha256=MTE4MkLrK45h0Nv7p5H92Kv5URa1nX246B9Pp1JkM3A,9134
-engin/_exceptions.py,sha256=fsc4pTOIGHUh0x7oZhEXPJUTE268sIhswLoiqXaudiw,635
-engin/_graph.py,sha256=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
-engin/_lifecycle.py,sha256=_jQnGFj4RYXsxMpcXPJQagFOwnoTVh7oSN8oUYoYuW0,3246
-engin/_type_utils.py,sha256=EGyKZWuE2ZwuMlSgDhM1znF8giaEET1vcVoQcdGxFGQ,2210
-engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=RUxkG03VTlvI6EG19c1nEJY8FnQw6MQwolfJSFnhUFE,3168
-engin/ext/fastapi.py,sha256=GO3AIZNQ69MtzbWuACffx_6Pp34wC5a5Fi_fIAaQvTg,6186
-engin/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/scripts/graph.py,sha256=por62FkzcWx72V2Ha9sIoki-o99fe2Ifm1w-mdoHZIQ,5922
-engin-0.0.13.dist-info/METADATA,sha256=dLFQgnZcD2c_xfKK-Z-Mx_f6_Q0kCta-XqNgqrEqRmo,2291
-engin-0.0.13.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.13.dist-info/entry_points.txt,sha256=Dehk4j5nK6zyuQtgOSRAoLE609V6eLzEp32bjqhO62Q,64
-engin-0.0.13.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.13.dist-info/RECORD,,

engin-0.0.13.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-engin-graph = engin.scripts.graph:serve_graph