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

engin/_assembler.py

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from collections import defaultdict
-from collections.abc import Iterable
+from collections.abc import Iterable, Sequence
 from contextvars import ContextVar
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
@@ -75,6 +75,11 @@ class Assembler:
             else:
                 self._multiproviders[type_id].append(provider)
 
+    @property
+    def providers(self) -> Sequence[Provide[Any]]:
+        multi_providers = [p for multi in self._multiproviders.values() for p in multi]
+        return [*self._providers.values(), *multi_providers]
+
     async def assemble(self, dependency: Dependency[Any, T]) -> AssembledDependency[T]:
         """
         Assemble a dependency.
@@ -228,7 +233,7 @@ class Assembler:
         yield from (
             child_provider
             for root_provider in root_providers
-            for root_provider_param in root_provider.parameter_types
+            for root_provider_param in root_provider.parameter_type_ids
             for child_provider in self._resolve_providers(root_provider_param)
         )
         yield from root_providers

engin/_cli/__init__.py

@@ -1,3 +1,6 @@
+import logging
+import sys
+
 try:
     import typer
 except ImportError:
@@ -7,7 +10,15 @@ except ImportError:
     ) from None
 
 from engin._cli._graph import cli as graph_cli
+from engin._cli._inspect import cli as inspect_cli
+
+# mute logging from importing of files + engin's debug logging.
+logging.disable()
+
+# add cwd to path to enable local package imports
+sys.path.insert(0, "")
 
 app = typer.Typer()
 
 app.add_typer(graph_cli)
+app.add_typer(inspect_cli)

engin/_cli/_common.py

@@ -0,0 +1,51 @@
+import importlib
+from typing import Never
+
+import typer
+from rich import print
+from rich.panel import Panel
+
+from engin import Engin
+
+
+def print_error(msg: str) -> Never:
+    print(
+        Panel(
+            title="Error",
+            renderable=msg,
+            title_align="left",
+            border_style="red",
+            highlight=True,
+        )
+    )
+    raise typer.Exit(code=1)
+
+
+COMMON_HELP = {
+    "app": (
+        "The import path of your Engin instance, in the form 'package:application'"
+        ", e.g. 'app.main:engin'"
+    )
+}
+
+
+def get_engin_instance(app: str) -> tuple[str, str, Engin]:
+    try:
+        module_name, engin_name = app.split(":", maxsplit=1)
+    except ValueError:
+        print_error("Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'")
+
+    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 AttributeError:
+        print_error(f"Module '{module_name}' has no attribute '{engin_name}'")
+
+    if not isinstance(instance, Engin):
+        print_error(f"'{app}' is not an Engin instance")
+
+    return module_name, engin_name, instance

engin/_cli/_graph.py

@@ -1,8 +1,5 @@
 import contextlib
-import importlib
-import logging
 import socketserver
-import sys
 import threading
 from http.server import BaseHTTPRequestHandler
 from pathlib import Path
@@ -12,8 +9,8 @@ from typing import Annotated, Any
 import typer
 from rich import print
 
-from engin import Engin, Entrypoint, Invoke, TypeId
-from engin._cli._utils import print_error
+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
 
@@ -24,53 +21,25 @@ except ImportError:
 
 cli = typer.Typer()
 
-# mute logging from importing of files + engin's debug logging.
-logging.disable()
 
 _APP_ORIGIN = ""
 
-_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"]),
+        typer.Argument(help=COMMON_HELP["app"]),
     ],
 ) -> None:
     """
     Creates a visualisation of your application's dependencies.
     """
-    # add cwd to path to enable local package imports
-    sys.path.insert(0, "")
-
-    try:
-        module_name, engin_name = app.split(":", maxsplit=1)
-    except ValueError:
-        print_error("Expected an argument of the form 'module:attribute', e.g. 'myapp:engin'")
+    module_name, _, instance = get_engin_instance(app)
 
     global _APP_ORIGIN
     _APP_ORIGIN = module_name.split(".", maxsplit=1)[0]
 
-    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 AttributeError:
-        print_error(f"module '{module_name}' has no attribute '{engin_name}'")
-
-    if not isinstance(instance, Engin):
-        print_error(f"'{app}' is not an Engin instance")
-
     nodes = instance.graph()
 
     # transform dependencies into mermaid syntax
@@ -165,7 +134,7 @@ def _render_node(node: Dependency, render_block: bool = True) -> str:
         md += f"{_short_name(node.return_type_id)}"
         return f'{node_id}["`{md}`"]{style}'
     if isinstance(node, Entrypoint):
-        entrypoint_type = node.parameter_types[0]
+        entrypoint_type = node.parameter_type_ids[0]
         md += f"{entrypoint_type}"
         return f'{node_id}[/"`{md}`"\\]{style}'
     if isinstance(node, Invoke):

engin/_cli/_inspect.py

@@ -0,0 +1,94 @@
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from engin import Supply
+from engin._cli._common import COMMON_HELP, get_engin_instance, print_error
+
+cli = typer.Typer()
+_CLI_HELP = {
+    "type": "Filter providers by the provided type, e.g. `AsyncClient` or `float[]`",
+    "module": "Filter providers by the provided types' module, e.g. `engin` or `httpx`",
+    "verbose": "Enables verbose output",
+}
+
+
+@cli.command(name="inspect")
+def serve_graph(
+    app: Annotated[
+        str,
+        typer.Argument(help=COMMON_HELP["app"]),
+    ],
+    type_: Annotated[
+        str | None,
+        typer.Option("--type", help=_CLI_HELP["type"]),
+    ] = None,
+    module: Annotated[
+        str | None,
+        typer.Option(help=_CLI_HELP["module"]),
+    ] = None,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help=_CLI_HELP["verbose"])
+    ] = False,
+) -> None:
+    """
+    Shows metadata for all matching providers.
+
+    Examples:
+
+        1. `engin inspect examples.simple.main:engin --module httpx`
+
+        2. `engin inspect examples.simple.main:engin --type AsyncClient`
+    """
+    module_name, _, instance = get_engin_instance(app)
+
+    console = Console()
+
+    providers = []
+    for provider in instance.assembler.providers:
+        type_id = provider.return_type_id
+        if type_ is not None:
+            type_name = str(type_id).rsplit(".", maxsplit=1)[-1]
+            if type_ != type_name:
+                if verbose:
+                    console.print(
+                        f"Ignoring '{provider.return_type_id}' as `{type_} != {type_name}",
+                        style="dim",
+                    )
+                continue
+        if module is not None:
+            module_name = str(type_id).split(".", maxsplit=1)[0]
+            if module != module_name:
+                if verbose:
+                    console.print(
+                        f"Ignoring '{provider.return_type_id}' as `{module} != {module_name}",
+                        style="dim",
+                    )
+                continue
+        providers.append(provider)
+
+    matching_provider_count = len(providers)
+    if matching_provider_count == 0:
+        available = sorted(map(str, instance.assembler.providers))
+        print_error(f"No matching providers, available: {available}")
+
+    if matching_provider_count > 1:
+        console.print(f"Found {matching_provider_count} matching providers", style="dim")
+
+    table = Table(show_header=False, show_lines=False, box=box.ASCII)
+
+    for provider in sorted(providers, key=lambda p: p.source_module):
+        is_supply = isinstance(provider, Supply)
+
+        table.add_row("name", str(provider), style="bold", end_section=True)
+        table.add_row("scope", provider.scope or "N/A")
+        table.add_row("func", provider.func_name if not is_supply else "N/A")
+        table.add_row("block", provider.block_name or "N/A")
+        table.add_row("source module", provider.source_module or "N/A")
+        table.add_row("source package", provider.source_package or "N/A")
+        table.add_section()
+
+    console.print(table)

engin/_dependency.py

@@ -76,7 +76,7 @@ class Dependency(ABC, Option, Generic[P, T]):
             return f"{self._func.__module__}.{self._func.__name__}"
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         parameters = list(self._signature.parameters.values())
         if not parameters:
             return []
@@ -136,7 +136,7 @@ class Entrypoint(Invoke):
         super().__init__(invocation=_noop)
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         return [TypeId.from_type(self._type)]
 
     @property
@@ -153,7 +153,12 @@ class Entrypoint(Invoke):
 
 class Provide(Dependency[Any, T]):
     def __init__(
-        self, builder: Func[P, T], *, scope: str | None = None, override: bool = False
+        self,
+        builder: 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.
@@ -161,19 +166,26 @@ class Provide(Dependency[Any, T]):
         Args:
             builder: the builder function that returns the type.
             scope: (optional) associate this provider with a specific scope.
-            override: (optional) allow this provider to override existing providers from
-                the same package.
+            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)
         self._scope = scope
         self._override = override
+        self._explicit_type = as_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
 
         # 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
-            for param in self.signature.parameters.values()
+            for param in self._signature.parameters.values()
         ):
             raise ValueError("A provider cannot depend on its own return type")
 
@@ -187,6 +199,8 @@ class Provide(Dependency[Any, T]):
 
     @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:
@@ -253,23 +267,19 @@ class Supply(Provide, Generic[T]):
         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.
+            value: the value to Supply.
+            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.
         """
         self._value = value
-        self._type_hint = as_type
-        if self._type_hint is not None:
-            self._get_val.__annotations__["return"] = as_type
-        super().__init__(builder=self._get_val, override=override)
+        super().__init__(builder=self._get_val, as_type=as_type, override=override)
 
     @property
     def return_type(self) -> type[T]:
-        if self._type_hint is not None:
-            return self._type_hint
+        if self._explicit_type is not None:
+            return self._explicit_type
         if isinstance(self._value, list):
             return list[type(self._value[0])]  # type: ignore[misc,return-value]
         return type(self._value)

engin/_graph.py

@@ -31,7 +31,7 @@ class DependencyGrapher:
     ) -> list[Node]:
         nodes: list[Node] = []
         for root in roots:
-            for parameter in root.parameter_types:
+            for parameter in root.parameter_type_ids:
                 provider = self._providers[parameter]
 
                 # multiprovider

engin/ext/fastapi.py

@@ -75,7 +75,7 @@ class _FastAPIDependencyGrapher(DependencyGrapher):
     ) -> list[Node]:
         nodes: list[Node] = []
         for root in roots:
-            for parameter in root.parameter_types:
+            for parameter in root.parameter_type_ids:
                 provider = self._providers[parameter]
 
                 # multiprovider
@@ -162,7 +162,7 @@ class APIRouteDependency(Dependency):
         return self._route
 
     @property
-    def parameter_types(self) -> list[TypeId]:
+    def parameter_type_ids(self) -> list[TypeId]:
         parameters = list(self._signature.parameters.values())
         if not parameters:
             return []

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

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

@@ -1,24 +1,25 @@
 engin/__init__.py,sha256=rBTteMLAVKg4TJSaMElJUwz72BA_X7nBTREg-I-bWhA,584
-engin/_assembler.py,sha256=8rt16LGvPpXHtjSdEDQJ6XC6DVwSbr_4_Mcfcfnpf70,10949
+engin/_assembler.py,sha256=saxYTjT67WR2HLJAFXyDsDeQmLGp1uyDboTDiKTaZ_s,11177
 engin/_block.py,sha256=8ysWrmHkWpTm6bmSc6jZVoO0Ax5Svu1HwxpZwAtIF_o,2617
-engin/_dependency.py,sha256=KM_d4TEu7NaoOSuIC7lRO7UvPzBFb0sxR74ZbInLMng,8561
+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=1pMB0cr--uS0XJycDb1rS_X45RBpoyA6NkKqbeSuz1Q,1628
+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=lp1KiBpcgk_dZU5V9DjgLPwmp0ja444fwLH2CYCscNc,302
+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=2v-l5rEC4zm36SWgmzQ2UK-nIHofYpexTo3et55AtE0,5539
-engin/_cli/_utils.py,sha256=AQFtLO8qjYRCTQc9A8Z1HVf7eZr8iGWogxbYzsgIkS4,360
+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=e8UV521Mq9Iqr55CT7_jtd51iaIZjWlAacoqFBXsh-k,6356
-engin-0.0.16.dist-info/METADATA,sha256=1-9KPa3HdnKUM38_OD3yAdNHHTb4-cOBds8dlqedv9s,2354
-engin-0.0.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.16.dist-info/entry_points.txt,sha256=sW247zZUMxm0b5UKYvPuqQQljYDtU-j2zK3cu7gHwM0,41
-engin-0.0.16.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.16.dist-info/RECORD,,
+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,,

engin/_cli/_utils.py

@@ -1,18 +0,0 @@
-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)