engin 0.0.14__tar.gz → 0.0.16__tar.gz

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

@@ -6,25 +6,56 @@ 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.16] - 2025-04-16
+
+### Added
+
+- Preliminary support for scoped providers. Scoped providers are only accessible when
+  the assembler is in the matching scope, and the built output is only cached until the
+  assembler leaves the matching scope. This can be used for example to have request scoped
+  providers in a Web Server.
+
+### Changed
+
+- Minor improvements to the work-in-progress dependency grapher.
+
+
+## [0.0.15] - 2025-03-25
+
+### Changed
+
+- `Provide` & `Supply` will now raise an error if overriding an existing provider from the
+  same package. This is to prevent accidental overrides. Users can explicitly allow
+  overrides by specifying the `override` parameter when defining the provider
+  `Provide(..., override=True)` or `@provide(override=True)`.
+- Lifecycle startup tasks will now timeout after 15 seconds and raise an error.
+- Assembler's `get` method has been renamed to `build`.
+- Supply's `type_hint` parameter has been renamed to `as_type`.
+
+### Fixed
+
+- `Assembler` would occasionally fail to call all multiproviders due to inconsistent
+  ordering.
+
+
 ## [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.
+- Engin now uses `typer` for an improved cli experience. Note the package now has an extra `cli` which must be installed to use the 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.
+- `Engin.run()` doing a double shutdown.
+
 
 ## [0.0.13] - 2025-03-22
 

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

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

@@ -0,0 +1,100 @@
+from contextlib import asynccontextmanager
+
+# Lifecycle
+
+Certain types of object naturally have some form of startup and shutdown behaviour
+associated with them, these steps need to be tied the lifecycle of the application itself
+in order to be useful. For example, a database connection manager might want to fill its
+connection pool on startup, and gracefully release the connections on shutdown.
+
+Doing this yourself can be tricky and is application dependent: most will not have any
+special support for this and will expect you to manage your lifecycle concerns in your
+entrypoint function, leading to unwieldy code in larger applications, whilst other
+types application might expected you to translate the lifecyle tasks into something they
+offer, e.g. an ASGI server would expect you to manage this via its lifespan. In both cases
+you end up managing lifecycle in a completely different place to where you declare your
+objects, which make the codebase more complicated to understand.
+
+Luckily, engin makes declaring lifecycle tasks a breeze, and it can be done in the same
+provider that build your object keeping your code nicely collocated.
+
+## The Lifecycle type
+
+Engin automatically provides a special type called `Lifecycle` that can be used like any
+other provided type. This type allows you to register lifecycle tasks with the Engin which
+will automatically be run as part of your application lifecycle.
+
+## Registering lifecycle tasks
+
+There are a few different ways to declare and register your lifecycle tasks, they all do
+the same thing, so which one to use depends on whichever is easiest for your specific
+lifecycle tasks.
+
+### 1. Existing context manager
+
+If your type exposes a context manager interface to handle its lifecycle, registering it
+is as easy as calling `lifecycle.append(...)`, this works for sync and async context
+managers.
+
+Let's look at an example using `httpx.AsyncClient`:
+
+```python
+from engin import Lifecycle
+from httpx import AsyncClient
+
+
+def httpx_client(lifecycle: Lifecycle) -> AsyncClient:
+    client = AsyncClient()
+    lifecycle.append(client)  # register the lifecycle tasks
+    return client
+```
+
+### 2. Explict startup & shutdown methods
+
+If your type exposes meathods that must be called as part of the lifecycle, e.g. `start()`
+& `stop()`, then `lifecycle.hook(on_start=..., on_stop=...)` is the way.
+
+Let's look at an example using `piccolo.engine.PostgresEngin`:
+
+```python
+from engin import Lifecycle
+from piccolo.engine import PostgresEngine
+
+def postgres_engine(lifecyle: Lifecycle) -> PostgresEngine:
+    db_engine = PostgresEngine(...)  # fill in actual connection details
+
+    lifecyle.hook(
+        on_start=db_engine.start_connection_pool(),
+        on_stop=db_engine.close_connection_pool(),
+    )
+
+    return db_engine
+```
+
+### 3. Custom context managers
+
+For more advanced use cases you can always define your own context manager.
+
+In this example assume that `worker.run()` will not return to us when we await it, and
+therefore we want to manage it as a task.
+
+
+```python
+import asyncio
+from engin import Lifecycle
+from some_package import BlockingAsyncWorker
+
+def blocking_worker(lifecycle: Lifecycle) -> BlockingWorker:
+    worker = BlockingAsyncWorker()
+
+    @asynccontextmanager
+    async def worker_lifecycle() -> AsyncIterator[None]:
+        task = asyncio.create_task(worker.run())
+        yield None
+        worker.stop()
+        del task
+
+    lifecycle.append(worker_lifecycle())
+
+    return worker
+```

{engin-0.0.14 → engin-0.0.16}/docs/concepts/providers.md

@@ -17,17 +17,19 @@ class: `Provide`.
 ```python
 from engin import Engin, Provide
 
+
 # define our constructor
 def string_factory() -> str:
-   return "hello"
+    return "hello"
+
 
 # register it as a provider with the Engin
 engin = Engin(Provide(string_factory))
 
 # construct the string
-a_string = await engin.assembler.get(str)
+a_string = await engin.assembler.build(str)
 
-print(a_string) # hello
+print(a_string)  # hello
 ```
 
 Providers can be asynchronous as well, this factory function would work exactly the same
@@ -45,27 +47,31 @@ Providers that construct more interesting objects generally require their own pa
 ```python
 from engin import Engin, Provide
 
+
 class Greeter:
     def __init__(self, greeting: str) -> None:
         self._greeting = greeting
-        
+
     def greet(self, name: str) -> None:
         print(f"{self._greeting}, {name}!")
-        
+
+
 # define our constructors
 def string_factory() -> str:
-   return "hello"
+    return "hello"
+
 
 def greeter_factory(greeting: str) -> Greeter:
     return Greeter(greeting=greeting)
 
+
 # register them as providers with the Engin
 engin = Engin(Provide(string_factory), Provide(greeter_factory))
 
 # construct the Greeter
-greeter = await engin.assembler.get(Greeter)
+greeter = await engin.assembler.build(Greeter)
 
-greeter.greet("Bob") # hello, Bob!
+greeter.greet("Bob")  # hello, Bob!
 ```
 
 
@@ -81,19 +87,21 @@ from engin import Engin, Provide
 
 # define our constructors
 def string_factory() -> str:
-   return "hello"
+    return "hello"
+
 
 def evil_factory() -> int:
     raise RuntimeError("I have ruined your plans")
 
+
 # register them as providers with the Engin
 engin = Engin(Provide(string_factory), Provide(evil_factory))
 
 # this will not raise an error
-await engin.assembler.get(str)
+await engin.assembler.build(str)
 
 # this will raise an error
-await engin.assembler.get(int)
+await engin.assembler.build(int)
 ```
 
 
@@ -109,20 +117,23 @@ To turn a factory into a multiprovider, simply return a list:
 ```python
 from engin import Engin, Provide
 
+
 # define our constructors
 def animal_names_factory() -> list[str]:
-   return ["cat", "dog"]
+    return ["cat", "dog"]
+
 
 def other_animal_names_factory() -> list[str]:
-   return ["horse", "cow"]
+    return ["horse", "cow"]
+
 
 # register them as providers with the Engin
 engin = Engin(Provide(animal_names_factory), Provide(other_animal_names_factory))
 
 # construct the list of strings
-animal_names = await engin.assembler.get(list[str])
+animal_names = await engin.assembler.build(list[str])
 
-print(animal_names) # ["cat", "dog", "horse", "cow"]
+print(animal_names)  # ["cat", "dog", "horse", "cow"]
 ```
 
 
@@ -133,25 +144,28 @@ Providers of the same type can be discriminated using annotations.
 ```python
 from engin import Engin, Provide
 from typing import Annotated
-        
+
+
 # define our constructors
 def greeting_factory() -> Annotated[str, "greeting"]:
-   return "hello"
+    return "hello"
+
 
 def name_factory() -> Annotated[str, "name"]:
     return "Jelena"
 
+
 # register them as providers with the Engin
 engin = Engin(Provide(greeting_factory), Provide(name_factory))
 
 # this will return "hello"
-await engin.assembler.get(Annotated[str, "greeting"])
+await engin.assembler.build(Annotated[str, "greeting"])
 
 # this will return "Jelena"
-await engin.assembler.get(Annotated[str, "name"])
+await engin.assembler.build(Annotated[str, "name"])
 
 # N.B. this will raise an error!
-await engin.assembler.get(str)
+await engin.assembler.build(str)
 ```
 
 
@@ -162,7 +176,6 @@ provided type is automatically inferred.
 
 For example the first example on this page could be rewritten as:
 
-
 ```python
 from engin import Engin, Supply
 
@@ -170,7 +183,7 @@ from engin import Engin, Supply
 engin = Engin(Supply("hello"))
 
 # construct the string
-a_string = await engin.assembler.get(str)
+a_string = await engin.assembler.build(str)
 
-print(a_string) # hello
+print(a_string)  # hello
 ```

{engin-0.0.14 → engin-0.0.16}/examples/fastapi/main.py

@@ -9,7 +9,7 @@ from examples.fastapi.routes.cats.block import CatBlock
 
 logging.basicConfig(level=logging.DEBUG)
 
-app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True)))
+app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True), override=True))
 
 
 if __name__ == "__main__":

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

@@ -34,7 +34,6 @@ nav:
       - Invocations: "concepts/invocations.md"
       - Lifecycle: "concepts/lifecycle.md"
   - Guides:
-      - Dependency Injection: "guides/dependency_injection.md"
       - FastAPI: "guides/fastapi.md"
   - Reference: "reference.md"
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.14"
+version = "0.0.16"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"

{engin-0.0.14 → engin-0.0.16}/src/engin/_assembler.py

@@ -1,18 +1,27 @@
 import asyncio
 import logging
 from collections import defaultdict
-from collections.abc import Collection, Iterable
+from collections.abc import Iterable
+from contextvars import ContextVar
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
+from types import TracebackType
 from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
-from engin._exceptions import ProviderError
+from engin._exceptions import NotInScopeError, ProviderError
 from engin._type_utils import TypeId
 
 LOG = logging.getLogger("engin")
 
 T = TypeVar("T")
+_SCOPE: ContextVar[list[str] | None] = ContextVar("_SCOPE", default=None)
+
+
+def _get_scope() -> list[str]:
+    if _SCOPE.get() is None:
+        _SCOPE.set([])
+    return cast("list[str]", _SCOPE.get())
 
 
 @dataclass(slots=True, kw_only=True, frozen=True)
@@ -39,7 +48,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 +56,7 @@ class Assembler:
             return "foo"
 
         a = Assembler([Provide(build_str)])
-        await a.get(str)
+        await a.build(str)
         ```
     """
 
@@ -85,17 +94,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.
@@ -114,6 +121,8 @@ class Assembler:
 
             out = []
             for provider in self._multiproviders[type_id]:
+                if provider.scope and provider.scope not in _get_scope():
+                    raise NotInScopeError(provider=provider, scope_stack=_get_scope())
                 assembled_dependency = await self.assemble(provider)
                 try:
                     out.extend(await assembled_dependency())
@@ -129,12 +138,16 @@ class Assembler:
             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])
+            provider = self._providers[type_id]
+            if provider.scope and provider.scope not in _get_scope():
+                raise NotInScopeError(provider=provider, scope_stack=_get_scope())
+
+            assembled_dependency = await self.assemble(provider)
             try:
                 value = await assembled_dependency()
             except Exception as err:
                 raise ProviderError(
-                    provider=self._providers[type_id],
+                    provider=provider,
                     error_type=type(err),
                     error_message=str(err),
                 ) from err
@@ -180,31 +193,45 @@ class Assembler:
                 del self._assembled_outputs[type_id]
             self._providers[type_id] = provider
 
-    def _resolve_providers(self, type_id: TypeId) -> Collection[Provide]:
+    def scope(self, scope: str) -> "_ScopeContextManager":
+        return _ScopeContextManager(scope=scope, assembler=self)
+
+    def _exit_scope(self, scope: str) -> None:
+        for type_id, provider in self._providers.items():
+            if provider.scope == scope:
+                self._assembled_outputs.pop(type_id, None)
+
+    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):
@@ -247,3 +274,27 @@ class Assembler:
                 kwargs[param.name] = val
 
         return signature.bind(*args, **kwargs)
+
+
+class _ScopeContextManager:
+    def __init__(self, scope: str, assembler: Assembler) -> None:
+        self._scope = scope
+        self._assembler = assembler
+
+    def __enter__(self) -> Assembler:
+        _get_scope().append(self._scope)
+        return self._assembler
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        popped = _get_scope().pop()
+        if popped != self._scope:
+            raise RuntimeError(
+                f"Exited scope '{popped}' is not the expected scope '{self._scope}'"
+            )
+        self._assembler._exit_scope(self._scope)

{engin-0.0.14 → engin-0.0.16}/src/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, *, scope: str | 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, scope=scope)  # 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-0.0.16/src/engin/_cli/_graph.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+  <style>
+    #mermaid-container {
+    width: 100%;
+    height: 100%;
+    overflow: auto; /* Enables scrolling */
+    border: 1px solid #ddd;
+    cursor: grab;
+    position: relative;
+    white-space: nowrap; /* Prevents wrapping */
+  }
+
+  #mermaid-content {
+    width: max-content; /* Ensures content can expand */
+    height: max-content;
+  }
+  </style>
+  <script type="module">
+      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+      let config = { flowchart: { useMaxWidth: false, htmlLabels: true, defaultRenderer: "elk" } };
+      mermaid.initialize(config);
+
+      // Drag-to-Move Functionality
+      const container = document.getElementById("mermaid-container");
+
+      let isDragging = false;
+      let startX, startY, scrollLeft, scrollTop;
+
+      container.addEventListener("pointerdown", (e) => {
+        isDragging = true;
+        startX = e.clientX;
+        startY = e.clientY;
+        scrollLeft = container.scrollLeft;
+        scrollTop = container.scrollTop;
+        container.style.cursor = "grabbing";
+      });
+
+      container.addEventListener("pointermove", (e) => {
+        if (!isDragging) return;
+        const x = e.clientX - startX;
+        const y = e.clientY - startY;
+        container.scrollLeft = scrollLeft - x;
+        container.scrollTop = scrollTop - y;
+      });
+
+      container.addEventListener("pointerup", () => {
+        isDragging = false;
+        container.style.cursor = "grab";
+      });
+
+      container.addEventListener("pointerleave", () => {
+        isDragging = false;
+        container.style.cursor = "grab";
+      });
+  </script>
+  <body>
+    <div style="border-style:outset">
+        <p>LEGEND</p>
+        <pre class="mermaid" id="legend">
+          graph LR
+            %%LEGEND%%
+            classDef b0 fill:#7fc97f;
+            classDef external stroke-dasharray: 5 5;
+        </pre>
+    </div>
+    <div id="mermaid-container" style="width: 100%; overflow-x: auto; border: 1px solid #ddd; cursor: grab; position: relative;">
+        <div id="mermaid-content" style="width: max-content; height: max-content;">
+            <pre class="mermaid" id="graph">
+              %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
+              graph LR
+                  %%DATA%%
+                  classDef external stroke-dasharray: 5 5;
+            </pre>
+        </div>
+    </div>
+  </body>
+</html>