engin 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

engin/__init__.py

@@ -1,9 +1,7 @@
-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
-from engin._exceptions import ProviderError
 from engin._lifecycle import Lifecycle
 from engin._option import Option
 from engin._type_utils import TypeId
@@ -17,10 +15,8 @@ __all__ = [
     "Lifecycle",
     "Option",
     "Provide",
-    "ProviderError",
     "Supply",
     "TypeId",
-    "ext",
     "invoke",
     "provide",
 ]

engin/_assembler.py

@@ -9,8 +9,8 @@ from types import TracebackType
 from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
-from engin._exceptions import NotInScopeError, ProviderError
 from engin._type_utils import TypeId
+from engin.exceptions import NotInScopeError, ProviderError
 
 LOG = logging.getLogger("engin")
 
@@ -65,6 +65,7 @@ class Assembler:
         self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
         self._assembled_outputs: dict[TypeId, Any] = {}
         self._lock = asyncio.Lock()
+        self._graph_cache: dict[TypeId, set[Provide]] = defaultdict(set)
 
         for provider in providers:
             type_id = provider.return_type_id
@@ -179,8 +180,8 @@ 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.
+        If this replaces an existing provider, this will clear all previously assembled
+        output. Note: multiproviders cannot be replaced, they are always appended.
 
         Args:
             provider: the Provide instance to add.
@@ -190,14 +191,13 @@ class Assembler:
         """
         type_id = provider.return_type_id
         if provider.is_multiprovider:
-            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._assembled_outputs:
-                del self._assembled_outputs[type_id]
             self._providers[type_id] = provider
 
+        self._assembled_outputs.clear()
+        self._graph_cache.clear()
+
     def scope(self, scope: str) -> "_ScopeContextManager":
         return _ScopeContextManager(scope=scope, assembler=self)
 
@@ -206,13 +206,14 @@ class Assembler:
             if provider.scope == scope:
                 self._assembled_outputs.pop(type_id, None)
 
-    def _resolve_providers(self, type_id: TypeId) -> Iterable[Provide]:
+    def _resolve_providers(self, type_id: TypeId, resolved: set[TypeId]) -> set[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 in self._graph_cache:
+            return self._graph_cache[type_id]
+
         if type_id.multi:
             root_providers = self._multiproviders.get(type_id)
         else:
@@ -230,22 +231,28 @@ class Assembler:
                 raise LookupError(msg)
 
         # providers that must be satisfied to satisfy the root level providers
-        yield from (
+        resolved_providers = {
             child_provider
             for root_provider in root_providers
             for root_provider_param in root_provider.parameter_type_ids
-            for child_provider in self._resolve_providers(root_provider_param)
-        )
-        yield from root_providers
+            for child_provider in self._resolve_providers(root_provider_param, resolved)
+            if root_provider_param not in resolved
+        } | set(root_providers)
+
+        resolved.add(type_id)
+        self._graph_cache[type_id] = resolved_providers
+
+        return resolved_providers
 
     async def _satisfy(self, target: TypeId) -> None:
-        for provider in self._resolve_providers(target):
+        for provider in self._resolve_providers(target, set()):
             if (
                 not provider.is_multiprovider
                 and provider.return_type_id in self._assembled_outputs
             ):
                 continue
             type_id = provider.return_type_id
+
             bound_args = await self._bind_arguments(provider.signature)
             try:
                 value = await provider(*bound_args.args, **bound_args.kwargs)
@@ -253,6 +260,7 @@ class Assembler:
                 raise ProviderError(
                     provider=provider, error_type=type(err), error_message=str(err)
                 ) from err
+
             if provider.is_multiprovider:
                 if type_id in self._assembled_outputs:
                     self._assembled_outputs[type_id].extend(value)
@@ -269,8 +277,7 @@ class Assembler:
                 args.append(object())
                 continue
             param_key = TypeId.from_type(param.annotation)
-            has_dependency = param_key in self._assembled_outputs
-            if not has_dependency:
+            if param_key not in self._assembled_outputs:
                 await self._satisfy(param_key)
             val = self._assembled_outputs[param_key]
             if param.kind == param.POSITIONAL_ONLY:

engin/_block.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, ClassVar
 
 from engin._dependency import Dependency, Func, Invoke, Provide
 from engin._option import Option
+from engin.exceptions import InvalidBlockError
 
 if TYPE_CHECKING:
     from engin._engin import Engin
@@ -42,7 +43,7 @@ def invoke(func_: Func | None = None) -> Func | Callable[[Func], Func]:
         return _inner(func_)
 
 
-class Block(Option):
+class Block:
     """
     A Block is a collection of providers and invocations.
 
@@ -74,7 +75,7 @@ class Block(Option):
 
     @classmethod
     def apply(cls, engin: "Engin") -> None:
-        block_name = cls.name or f"{cls.__name__}"
+        block_name = cls.name or cls.__name__
         for option in chain(cls.options, cls._method_options()):
             if isinstance(option, Dependency):
                 option._block_name = block_name
@@ -82,8 +83,19 @@ class Block(Option):
 
     @classmethod
     def _method_options(cls) -> Iterable[Provide | Invoke]:
-        for _, method in inspect.getmembers(cls):
+        for name, method in inspect.getmembers(cls, inspect.isfunction):
             if option := getattr(method, "_opt", None):
                 if not isinstance(option, Provide | Invoke):
-                    raise RuntimeError("Block option is not an instance of Provide or Invoke")
+                    raise InvalidBlockError(
+                        block=cls,
+                        reason="Block option is not an instance of Provide or Invoke",
+                    )
                 yield option
+            else:
+                raise InvalidBlockError(
+                    block=cls,
+                    reason=(
+                        f"Method '{name}' is not a Provider or Invocation, did you "
+                        "forget to decorate it?"
+                    ),
+                )

engin/_cli/_graph.py

@@ -12,10 +12,10 @@ from rich import print
 from engin import Entrypoint, Invoke, TypeId
 from engin._cli._common import COMMON_HELP, get_engin_instance
 from engin._dependency import Dependency, Provide, Supply
-from engin.ext.asgi import ASGIEngin
+from engin.extensions.asgi import ASGIEngin
 
 try:
-    from engin.ext.fastapi import APIRouteDependency
+    from engin.extensions.fastapi import APIRouteDependency
 except ImportError:
     APIRouteDependency = None  # type: ignore[assignment,misc]
 

engin/_dependency.py

@@ -33,7 +33,7 @@ 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._signature = inspect.signature(self._func, eval_str=True)
         self._block_name: str | None = None
 
         source_frame = get_first_external_frame()
@@ -154,68 +154,58 @@ class Entrypoint(Invoke):
 class Provide(Dependency[Any, T]):
     def __init__(
         self,
-        builder: Func[P, T],
+        factory: Func[P, T],
         *,
         scope: str | None = None,
         as_type: type | None = None,
         override: bool = False,
     ) -> None:
         """
-        Provide a type via a builder or factory function.
+        Provide a type via a factory function.
 
         Args:
-            builder: the builder function that returns the type.
+            factory: the factory function that returns the type.
             scope: (optional) associate this provider with a specific scope.
             as_type: (optional) allows you to explicitly specify the provided type, e.g.
                 to type erase a concrete type, or to provide a mock implementation.
             override: (optional) allow this provider to override other providers for the
                 same type from the same package.
         """
-        super().__init__(func=builder)
+        super().__init__(func=factory)
         self._scope = scope
         self._override = override
         self._explicit_type = as_type
+        self._return_type = self._resolve_return_type()
+        self._return_type_id = TypeId.from_type(self._return_type)
 
         if self._explicit_type is not None:
             self._signature = self._signature.replace(return_annotation=self._explicit_type)
 
-        self._is_multi = typing.get_origin(self.return_type) is list
+        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
         # cause a recursion error and is undefined behaviour wise.
         if any(
-            self.return_type == param.annotation
+            self._return_type == param.annotation
             for param in self._signature.parameters.values()
         ):
             raise ValueError("A provider cannot depend on its own return type")
 
         # Validate that multiproviders only return a list of one type.
         if self._is_multi:
-            args = typing.get_args(self.return_type)
+            args = typing.get_args(self._return_type)
             if len(args) != 1:
                 raise ValueError(
-                    f"A multiprovider must be of the form list[X], not '{self.return_type}'"
+                    f"A multiprovider must be of the form list[X], not '{self._return_type}'"
                 )
 
     @property
     def return_type(self) -> type[T]:
-        if self._explicit_type is not None:
-            return self._explicit_type
-        if isclass(self._func):
-            return_type = self._func  # __init__ returns self
-        else:
-            try:
-                return_type = get_type_hints(self._func, include_extras=True)["return"]
-            except KeyError as err:
-                raise RuntimeError(
-                    f"Dependency '{self.name}' requires a return typehint"
-                ) from err
-
-        return return_type
+        return self._return_type
 
     @property
     def return_type_id(self) -> TypeId:
-        return TypeId.from_type(self.return_type)
+        return self._return_type_id
 
     @property
     def is_multiprovider(self) -> bool:
@@ -241,9 +231,9 @@ class Provide(Dependency[Any, T]):
         # 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"
+                f"{self} from '{self._source_frame}' is implicitly overriding "
+                f"{existing_provider} from '{existing_provider.source_module}', if this "
+                "is intentional specify `override=True` for the overriding Provider"
             )
             raise RuntimeError(msg)
 
@@ -253,7 +243,22 @@ class Provide(Dependency[Any, T]):
         return hash(self.return_type_id)
 
     def __str__(self) -> str:
-        return f"Provide({self.return_type_id})"
+        return f"Provide(factory={self.func_name}, type={self._return_type_id})"
+
+    def _resolve_return_type(self) -> type[T]:
+        if self._explicit_type is not None:
+            return self._explicit_type
+        if isclass(self._func):
+            return_type = self._func  # __init__ returns self
+        else:
+            try:
+                return_type = get_type_hints(self._func, include_extras=True)["return"]
+            except KeyError as err:
+                raise RuntimeError(
+                    f"Dependency '{self.name}' requires a return typehint"
+                ) from err
+
+        return return_type
 
 
 class Supply(Provide, Generic[T]):
@@ -274,10 +279,16 @@ class Supply(Provide, Generic[T]):
               same type from the same package.
         """
         self._value = value
-        super().__init__(builder=self._get_val, as_type=as_type, override=override)
+        super().__init__(factory=self._get_val, as_type=as_type, override=override)
 
     @property
-    def return_type(self) -> type[T]:
+    def name(self) -> str:
+        if self._block_name:
+            return f"{self._block_name}.supply"
+        else:
+            return f"{self._source_frame}.supply"
+
+    def _resolve_return_type(self) -> type[T]:
         if self._explicit_type is not None:
             return self._explicit_type
         if isinstance(self._value, list):
@@ -288,4 +299,4 @@ class Supply(Provide, Generic[T]):
         return self._value
 
     def __str__(self) -> str:
-        return f"Supply({self.return_type_id})"
+        return f"Supply(value={self._value}, type={self.return_type_id})"

engin/_type_utils.py

@@ -33,8 +33,8 @@ class TypeId:
             return TypeId(type=type_, multi=False)
 
     def __str__(self) -> str:
-        module = self.type.__module__
-        out = f"{module}." if module not in _implict_modules else ""
+        module = getattr(self.type, "__module__", None)
+        out = f"{module}." if module and module not in _implict_modules else ""
         out += _args_to_str(self.type)
         if self.multi:
             out += "[]"

engin/{_exceptions.py → exceptions.py}

@@ -1,7 +1,10 @@
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from engin._dependency import Provide
 
+if TYPE_CHECKING:
+    from engin._block import Block
+
 
 class EnginError(Exception):
     """
@@ -15,6 +18,20 @@ class AssemblerError(EnginError):
     """
 
 
+class InvalidBlockError(EnginError):
+    """
+    Raised when an invalid block is instantiated.
+    """
+
+    def __init__(self, block: "type[Block]", reason: str) -> None:
+        self.block = block
+        self.block_name = block.name or block.__name__
+        self.message = f"block '{self.block_name}' is invalid, reason: '{reason}'"
+
+    def __str__(self) -> str:
+        return self.message
+
+
 class ProviderError(AssemblerError):
     """
     Raised when a Provider errors during Assembly.
@@ -52,3 +69,12 @@ class NotInScopeError(AssemblerError):
 
     def __str__(self) -> str:
         return self.message
+
+
+__all__ = [
+    "AssemblerError",
+    "EnginError",
+    "InvalidBlockError",
+    "NotInScopeError",
+    "ProviderError",
+]

engin/{ext → extensions}/fastapi.py

@@ -10,7 +10,7 @@ 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
-from engin.ext.asgi import ASGIEngin
+from engin.extensions.asgi import ASGIEngin
 
 try:
     from fastapi import APIRouter, FastAPI

{engin-0.0.18.dist-info → engin-0.0.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.18
+Version: 0.0.20
 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.20.dist-info/RECORD

@@ -0,0 +1,25 @@
+engin/__init__.py,sha256=A8TE_ci7idoR683535YoBrWZbYTgXXS-q7Y2y51nZ5M,486
+engin/_assembler.py,sha256=-ENSrXPMWacionIYrTSQO7th9DDBOPyAT8ybPbBRtQw,11318
+engin/_block.py,sha256=IacP4PoJKRhSQCbQSdoyCtmu362a4vj6qoUQKyaJwzI,3062
+engin/_dependency.py,sha256=xINk3sudxzsTmkUkNAKQwzBc0G0DfhpnrZli4z3ALBY,9459
+engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
+engin/_graph.py,sha256=y1g7Lm_Zy5GPEgRsggCKV5DDaDzcwUl8v3IZCK8jyGI,1631
+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=H3Tl-kJr2wY2RhaTXP9GrMqa2RsXMijHbjHKe1AxGmc,2276
+engin/exceptions.py,sha256=-VPwPReZb9YEIkrWMR9TW2K5HEwmHHgEO7QWH6wfV8c,1946
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/_cli/__init__.py,sha256=koD5WTkZXb8QQIiVU5bJiSR1wwPGb5rv2iwd-v-BA7A,564
+engin/_cli/_common.py,sha256=zMYb1Bs1yUuR3qf3r6WuVozYzDwHJvTVthVbTQfTF9w,1261
+engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
+engin/_cli/_graph.py,sha256=HMC91nWvTOr6_czPBNx1RU55Ib3qesJRCmbnL2DsdDk,4659
+engin/_cli/_inspect.py,sha256=0jm25d4wcbXVNJkyaeECSKY-irsxd-EIYBH1GDW_Yjc,3163
+engin/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/extensions/asgi.py,sha256=d5Z6gtMVWDZdAlvrTaMt987sKyiq__A0X4gJQ7IETmA,3247
+engin/extensions/fastapi.py,sha256=e8F4L_nZ9dU9j8mb9lXKwJG6CTu5aIk4N5faRj4EyUA,6369
+engin-0.0.20.dist-info/METADATA,sha256=KiKW4DvikfKJJNzoXh7oC4RMdr02W0PkhtxXB8DN6bo,2354
+engin-0.0.20.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.20.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
+engin-0.0.20.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.20.dist-info/RECORD,,

engin-0.0.18.dist-info/RECORD

@@ -1,25 +0,0 @@
-engin/__init__.py,sha256=rBTteMLAVKg4TJSaMElJUwz72BA_X7nBTREg-I-bWhA,584
-engin/_assembler.py,sha256=saxYTjT67WR2HLJAFXyDsDeQmLGp1uyDboTDiKTaZ_s,11177
-engin/_block.py,sha256=8ysWrmHkWpTm6bmSc6jZVoO0Ax5Svu1HwxpZwAtIF_o,2617
-engin/_dependency.py,sha256=5x4_0QvHtqv6R_brKHRc-INKE4oMh1JU8-9RCmulp4Q,8976
-engin/_engin.py,sha256=yIpZdeqvm8hv0RxOV0veFuvyu9xQ054JSaeuUWwHdOQ,7380
-engin/_exceptions.py,sha256=UzMppJWDk_Hx3qWAypcPVLw9OYCibqiZjLYeTl22zaE,1355
-engin/_graph.py,sha256=y1g7Lm_Zy5GPEgRsggCKV5DDaDzcwUl8v3IZCK8jyGI,1631
-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=koD5WTkZXb8QQIiVU5bJiSR1wwPGb5rv2iwd-v-BA7A,564
-engin/_cli/_common.py,sha256=zMYb1Bs1yUuR3qf3r6WuVozYzDwHJvTVthVbTQfTF9w,1261
-engin/_cli/_graph.html,sha256=rR5dnDKoz7KtSff0ERCi2UKuoH_Z03MRYiXI_W03G5k,2430
-engin/_cli/_graph.py,sha256=S0HKWb3PlC1ygYTdsFzEm-eYmrbHhOOMZ7nApOe7ac8,4645
-engin/_cli/_inspect.py,sha256=0jm25d4wcbXVNJkyaeECSKY-irsxd-EIYBH1GDW_Yjc,3163
-engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=d5Z6gtMVWDZdAlvrTaMt987sKyiq__A0X4gJQ7IETmA,3247
-engin/ext/fastapi.py,sha256=TGNf0LFLaTLMLlAycH7GgP_GcBld262v9xboGOwhvgE,6362
-engin-0.0.18.dist-info/METADATA,sha256=4d8IsPLHnEekTIP5Qdy2LfNYHHZ-G0DLWcjB2RRQdSs,2354
-engin-0.0.18.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.18.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.18.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.18.dist-info/RECORD,,