engin 0.0.12__tar.gz → 0.0.14__tar.gz

{engin-0.0.12 → engin-0.0.14}/.readthedocs.yaml

@@ -22,4 +22,4 @@ build:
           - NO_COLOR=1 uv run mkdocs build -f mkdocs.yaml --strict --site-dir $READTHEDOCS_OUTPUT/html
 
 mkdocs:
-  configuration: mkdocs.yaml
+  configuration: mkdocs.yaml

{engin-0.0.12 → engin-0.0.14}/CHANGELOG.md

@@ -6,6 +6,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.0.14] - 2025-03-23
+
+### Added
+
+- `LifecycleHook` class to help build simple lifecycles with a start and stop call.
+- `TypeId` now attempts to introspect type aliases, this is experimental and currently on
+  used to enrich error messages.
+
+### Changed
+
+- `engin-graph` has been replaced by `engin graph`.
+- Engin now uses `typer` for an improved cli experience.
+- The package now has an extra `cli` which must be installed to use the developer cli.
+- `Assembler.add(...)` does not error when adding already registered providers.
+- Use a more performant algorithm for inspecting frame stack.
+
+### Fixed
+
+- `ASGIEngin` now properly surfaces startup errors.
+
+## [0.0.13] - 2025-03-22
+
+### Changed
+
+- `Provide` now supports union types.
+
+
 ## [0.0.12] - 2025-03-03
 
 ### Added

{engin-0.0.12 → engin-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.12
+Version: 0.0.14
 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.12 → engin-0.0.14}/docs/concepts/engin.md

@@ -9,4 +9,4 @@ When ran the Engin takes care of the complete application lifecycle:
 2. All Invocations are run sequentially in the order they were passed in to the Engin.
 3. Any Lifecycle Startup defined by Provider that were assembled is ran.
 4. The Engin waits for a stop signal, i.e. SIGINT or SIGTERM.
-5. Any Lifecyce Shutdown task is ran, in the reverse order to the Startup order.
+5. Any Lifecyce Shutdown tasks are run, in reverse order to the Startup order.

{engin-0.0.12 → engin-0.0.14}/docs/concepts/invocations.md

@@ -23,15 +23,12 @@ imports for brevity):
 
 ```python
 def worker_factory(lifecycle: Lifecycle) -> Worker:
-   worker = Worker()
+    worker = Worker()
    
-   @asynccontextmanager
-   async def worker_lifecycle() -> Iterable[None]:
-       worker.start()
-       yield
-       worker.shutdown()
-       
-    lifecycle.append(worker_lifecycle)
+    lifecycle.hook(
+        on_start=worker.start,
+        on_stop=worker.shutdown
+    )
    
     return worker
 ```

{engin-0.0.12 → engin-0.0.14}/docs/getting-started.md

@@ -2,6 +2,6 @@
 
 Engin is available on PyPI, install using your favourite dependency manager:
 
-- **pip**:`pip install engin`
+- **pip**: `pip install engin`
 - **poetry**: `poetry add engin`
 - **uv**: `uv add engin`

{engin-0.0.12 → engin-0.0.14}/docs/guides/fastapi.md

@@ -159,7 +159,7 @@ app = FastAPIEngin(AppBlock())
 
 ## Graphing Dependencies
 
-Engin provides dependency visualisation functionality via the `engin-graph` script. When
+Engin provides dependency visualisation functionality via the `engin graph` script. When
 working with a FastAPI application this can be used to visualise API Routes along with
 their respective dependencies.
 

engin-0.0.14/docs/js/readthedocs.js

@@ -0,0 +1,7 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+// Trigger Read the Docs' search addon instead of Material MkDocs default
+document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+        const event = new CustomEvent("readthedocs-search-show");
+        document.dispatchEvent(event);
+    });
+});

{engin-0.0.12 → engin-0.0.14}/mkdocs.yaml

@@ -57,7 +57,7 @@ plugins:
           show_signature_annotations: true
           show_source: false
           signature_crossrefs: true
-        import:
+        inventories:
           - url: https://docs.python.org/3/objects.inv
             domains: [py, std]
 

{engin-0.0.12 → engin-0.0.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.12"
+version = "0.0.14"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -8,19 +8,21 @@ license = "MIT"
 keywords = ["Dependency Injection", "Application Framework"]
 dependencies = []
 
+[project.optional-dependencies]
+cli = ["typer>=0.15"]
+
+[project.scripts]
+engin = "engin._cli:app"
+
 [project.urls]
 Homepage = "https://github.com/invokermain/engin"
 Documentation = "https://engin.readthedocs.io/en/latest/"
 Repository = "https://github.com/invokermain/engin.git"
 Changelog = "https://github.com/invokermain/engin/blob/main/CHANGELOG.md"
 
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
     "fastapi>=0.115.6",
     "httpx>=0.27.2",
     "mypy>=1",
@@ -33,18 +35,20 @@ dev-dependencies = [
     "starlette>=0.39.2",
     "uvicorn>=0.31.1",
     "pytest-cov>=6.0.0",
+    "typer>=0.15.2",
+    "pytest-mock>=3.14.0",
 ]
-
-
-[dependency-groups]
 docs = [
     "mkdocs-material>=9.5.50",
     "mkdocstrings[python]>=0.27.0",
 ]
 
+[tool.uv]
+default-groups = ["dev", "docs"]
 
-[project.scripts]
-engin-graph = "engin.scripts.graph:serve_graph"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
 
 
 [tool.ruff]

{engin-0.0.12 → engin-0.0.14}/src/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-0.0.12 → engin-0.0.14}/src/engin/_assembler.py

@@ -8,7 +8,7 @@ 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")
 
@@ -54,8 +54,7 @@ class Assembler:
     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:
@@ -106,13 +105,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 +123,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 +138,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 +151,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,24 +161,23 @@ 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]:
@@ -192,7 +192,9 @@ class Assembler:
                 # store default to prevent the warning appearing multiple times
                 self._multiproviders[type_id] = providers
             else:
-                raise LookupError(f"No Provider registered for dependency '{type_id}'")
+                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:
@@ -206,9 +208,11 @@ class Assembler:
 
     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 +222,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 +236,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-0.0.12 → engin-0.0.14}/src/engin/_block.py

@@ -1,8 +1,13 @@
 import inspect
-from collections.abc import Iterable, Iterator
-from typing import ClassVar
+from collections.abc import 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:
@@ -21,7 +26,7 @@ def invoke(func: Func) -> Func:
     return func
 
 
-class Block(Iterable[Provide | Invoke]):
+class Block(Option):
     """
     A Block is a collection of providers and invocations.
 
@@ -48,23 +53,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-0.0.14/src/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-0.0.12/src/engin/scripts/graph.py → engin-0.0.14/src/engin/_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-0.0.14/src/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)