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

engin/_assembler.py

@@ -1,7 +1,7 @@
 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
@@ -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,7 +47,7 @@ class Assembler:
             return "foo"
 
         a = Assembler([Provide(build_str)])
-        await a.get(str)
+        await a.build(str)
         ```
     """
 
@@ -85,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.
@@ -180,31 +178,37 @@ class Assembler:
                 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:
                 available = sorted(str(k) for k in self._providers)
                 msg = f"Missing Provider for type '{type_id}', available: {available}"
                 raise LookupError(msg)
 
-        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}
+        # 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):

engin/_block.py

@@ -1,5 +1,5 @@
 import inspect
-from collections.abc import Iterable, Sequence
+from collections.abc import Callable, Iterable, Sequence
 from itertools import chain
 from typing import TYPE_CHECKING, ClassVar
 
@@ -10,20 +10,36 @@ 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
 
-def invoke(func: Func) -> Func:
+    if func_ is None:
+        return _inner
+    else:
+        return _inner(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(Option):

engin/_dependency.py

@@ -30,11 +30,11 @@ def _noop(*args: Any, **kwargs: Any) -> None: ...
 
 
 class Dependency(ABC, Option, Generic[P, T]):
-    def __init__(self, func: Func[P, T], block_name: str | None = None) -> None:
+    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._block_name: str | None = None
 
         source_frame = get_first_external_frame()
         self._source_package = cast("str", source_frame.frame.f_globals["__package__"])
@@ -88,9 +88,6 @@ class Dependency(ABC, Option, Generic[P, T]):
     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))
@@ -117,8 +114,8 @@ 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)
@@ -134,9 +131,9 @@ 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]:
@@ -155,8 +152,17 @@ class Entrypoint(Invoke):
 
 
 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
@@ -198,10 +204,28 @@ class Provide(Dependency[Any, T]):
         return self._is_multi
 
     def apply(self, engin: "Engin") -> None:
+        type_id = self.return_type_id
         if self.is_multiprovider:
-            engin._multiproviders[self.return_type_id].append(self)
-        else:
-            engin._providers[self.return_type_id] = self
+            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)
@@ -212,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

@@ -84,7 +84,7 @@ class Engin:
         self._run_task: Task | None = None
 
         self._providers: dict[TypeId, Provide] = {
-            TypeId.from_type(Engin): Supply(self, type_hint=Engin)
+            TypeId.from_type(Engin): Supply(self, as_type=Engin)
         }
         self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
@@ -132,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")

engin/ext/asgi.py

@@ -50,7 +50,7 @@ class ASGIEngin(Engin, ASGIType):
         await self._asgi_app(scope, receive, send)
 
     async def _startup(self) -> None:
-        self._asgi_app = await self._assembler.get(self._asgi_type)
+        self._asgi_app = await self._assembler.build(self._asgi_type)
         await self.start()
 
     def graph(self) -> list[Node]:

engin/ext/fastapi.py

@@ -58,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]
@@ -143,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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.14
+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/

{engin-0.0.14.dist-info → engin-0.0.15.dist-info}/RECORD

@@ -1,8 +1,8 @@
 engin/__init__.py,sha256=rBTteMLAVKg4TJSaMElJUwz72BA_X7nBTREg-I-bWhA,584
-engin/_assembler.py,sha256=AJHrFKSlZiSNCDOpS-0-C16ns9XFYJUXrUX-phdtjKs,9003
-engin/_block.py,sha256=qOM3tSULwPEjNDkIERF0PSMe-1_Ea8Ihtv4Z8f94U0Y,2178
-engin/_dependency.py,sha256=aG-pW0hvW9ERuVQjPJLr0SJ4Ju7kXXS9qUozkHk4q48,7102
-engin/_engin.py,sha256=GwsR9iQGUIuIt0OeTpi2jr6XtWZfyh4PZUM4fz36axk,7186
+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
@@ -14,10 +14,10 @@ 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=cpplCnJSKB3yZb-AL6w70CW0SWsRmrR0S6mxfyJI-w8,3194
-engin/ext/fastapi.py,sha256=Z8pA8hrfcXbVKfDIuSfL94wHzW0E5WLJoYOjEVzuNMk,6328
-engin-0.0.14.dist-info/METADATA,sha256=VDeCZ_auc2cIoRHPuGf7_Cbarqf3r7_eEOjm72HVHpY,2354
-engin-0.0.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.14.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.14.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.14.dist-info/RECORD,,
+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,,