engin 0.0.14__tar.gz → 0.0.15__tar.gz

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

@@ -6,25 +6,42 @@ 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.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.15}/PKG-INFO

@@ -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.15/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.15}/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.15}/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.15}/pyproject.toml

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

{engin-0.0.14 → engin-0.0.15}/src/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-0.0.14 → engin-0.0.15}/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, *, 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-0.0.14 → engin-0.0.15}/src/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-0.0.14 → engin-0.0.15}/src/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-0.0.14 → engin-0.0.15}/src/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-0.0.14 → engin-0.0.15}/src/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 → engin-0.0.15}/tests/test_assembler.py

@@ -60,18 +60,18 @@ def test_assembler_with_duplicate_provider_errors():
 async def test_assembler_get():
     assembler = Assembler([Provide(make_int), Provide(make_many_int)])
 
-    assert await assembler.get(int)
-    assert await assembler.get(list[int])
+    assert await assembler.build(int)
+    assert await assembler.build(list[int])
 
 
 async def test_assembler_with_unknown_type_raises_lookup_error():
     assembler = Assembler([])
 
     with pytest.raises(LookupError):
-        await assembler.get(str)
+        await assembler.build(str)
 
     with pytest.raises(LookupError):
-        await assembler.get(list[str])
+        await assembler.build(list[str])
 
     with pytest.raises(LookupError):
         await assembler.assemble(Entrypoint(str))
@@ -87,10 +87,10 @@ async def test_assembler_with_erroring_provider_raises_provider_error():
     assembler = Assembler([Provide(make_str), Provide(make_many_str)])
 
     with pytest.raises(ProviderError):
-        await assembler.get(str)
+        await assembler.build(str)
 
     with pytest.raises(ProviderError):
-        await assembler.get(list[str])
+        await assembler.build(list[str])
 
 
 async def test_annotations():
@@ -103,10 +103,10 @@ async def test_annotations():
     assembler = Assembler([Provide(make_str_1), Provide(make_str_2)])
 
     with pytest.raises(LookupError):
-        await assembler.get(str)
+        await assembler.build(str)
 
-    assert await assembler.get(Annotated[str, "1"]) == "bar"
-    assert await assembler.get(Annotated[str, "2"]) == "foo"
+    assert await assembler.build(Annotated[str, "1"]) == "bar"
+    assert await assembler.build(Annotated[str, "2"]) == "foo"
 
 
 async def test_assembler_has():
@@ -153,8 +153,8 @@ async def test_assembler_add_overrides():
     assembler = Assembler([])
     assembler.add(Provide(return_one))
 
-    assert await assembler.get(int) == 1
+    assert await assembler.build(int) == 1
 
     assembler.add(Provide(return_two))
 
-    assert await assembler.get(int) == 2
+    assert await assembler.build(int) == 2

{engin-0.0.14 → engin-0.0.15}/tests/test_block.py

@@ -8,12 +8,18 @@ def test_block():
             return 3
 
         @invoke
-        def invoke_square(self, some: int) -> None:
-            return some**2
+        def invoke_square(self, some: int) -> None: ...
+
+        @provide()
+        def provide_str(self) -> str:
+            return "3"
+
+        @invoke()
+        def invoke_str(self, some: str) -> None: ...
 
     my_block = MyBlock()
 
     options = list(my_block._method_options())
-    assert len(options) == 2
 
+    assert len(options) == 4
     assert Engin(my_block)

{engin-0.0.14 → engin-0.0.15}/tests/test_dependencies.py

@@ -1,4 +1,5 @@
 from typing import Annotated
+from unittest.mock import Mock
 
 import pytest
 
@@ -91,3 +92,40 @@ def test_provider_cannot_depend_on_self():
 
     with pytest.raises(ValueError, match="return type"):
         Provide(invalid_provider_2)
+
+
+def test_provides_implicit_overrides():
+    provide_a = Provide(make_int)
+    provide_b = Provide(make_int)
+
+    engin = Mock()
+    engin._providers = {}
+
+    provide_a.apply(engin)
+
+    with pytest.raises(RuntimeError, match="implicit"):
+        provide_b.apply(engin)
+
+
+def test_provides_explicit_overrides_allowed():
+    provide_a = Provide(make_int)
+    provide_b = Provide(make_int, override=True)
+
+    engin = Mock()
+    engin._providers = {}
+
+    provide_a.apply(engin)
+    provide_b.apply(engin)
+
+
+def test_provides_implicit_overrides_allowed_when_3rd_party():
+    provide_a = Provide(make_int)
+    provide_b = Provide(make_int)
+
+    provide_a._source_package = "foo"
+
+    engin = Mock()
+    engin._providers = {}
+
+    provide_a.apply(engin)
+    provide_b.apply(engin)

{engin-0.0.14 → engin-0.0.15}/uv.lock

@@ -206,7 +206,7 @@ toml = [
 
 [[package]]
 name = "engin"
-version = "0.0.14"
+version = "0.0.15"
 source = { editable = "." }
 
 [package.optional-dependencies]
@@ -273,16 +273,16 @@ wheels = [
 
 [[package]]
 name = "fastapi"
-version = "0.115.11"
+version = "0.115.12"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pydantic" },
     { name = "starlette" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b5/28/c5d26e5860df807241909a961a37d45e10533acef95fc368066c7dd186cd/fastapi-0.115.11.tar.gz", hash = "sha256:cc81f03f688678b92600a65a5e618b93592c65005db37157147204d8924bf94f", size = 294441 }
+sdist = { url = "https://files.pythonhosted.org/packages/f4/55/ae499352d82338331ca1e28c7f4a63bfd09479b16395dce38cf50a39e2c2/fastapi-0.115.12.tar.gz", hash = "sha256:1e2c2a2646905f9e83d32f04a3f86aff4a286669c6c950ca95b5fd68c2602681", size = 295236 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/5d/4d8bbb94f0dbc22732350c06965e40740f4a92ca560e90bb566f4f73af41/fastapi-0.115.11-py3-none-any.whl", hash = "sha256:32e1541b7b74602e4ef4a0260ecaf3aadf9d4f19590bba3e1bf2ac4666aa2c64", size = 94926 },
+    { url = "https://files.pythonhosted.org/packages/50/b3/b51f09c2ba432a576fe63758bddc81f78f0c6309d9e5c10d194313bf021e/fastapi-0.115.12-py3-none-any.whl", hash = "sha256:e94613d6c05e27be7ffebdd6ea5f388112e5e430c8f7d6494a9d1d88d43e814d", size = 95164 },
 ]
 
 [[package]]
@@ -580,7 +580,7 @@ python = [
 
 [[package]]
 name = "mkdocstrings-python"
-version = "1.16.7"
+version = "1.16.8"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "griffe" },
@@ -588,9 +588,9 @@ dependencies = [
     { name = "mkdocstrings" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/52/e0/cc35acb47593c138efbfc9dc296ccc26b7ad4452e868fd309f05f6ba0ded/mkdocstrings_python-1.16.7.tar.gz", hash = "sha256:cdfc1a99fe5f6f0d90446a364ef7cac12014a4ef46114b2677a58cec84007117", size = 1475398 }
+sdist = { url = "https://files.pythonhosted.org/packages/8e/b8/62190ea298fdb1e84670ef548590748c633ab4e05b35bcf902e89f2f28c6/mkdocstrings_python-1.16.8.tar.gz", hash = "sha256:9453ccae69be103810c1cf6435ce71c8f714ae37fef4d87d16aa92a7c800fe1d", size = 205119 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ab/5e/dc978b9fd6331e2070369579ad8f52145e9ef22a69bfc2811110be95e6d4/mkdocstrings_python-1.16.7-py3-none-any.whl", hash = "sha256:a5589a5be247a28ba651287f83630c69524042f8055d93b5c203d804a3409333", size = 1998312 },
+    { url = "https://files.pythonhosted.org/packages/67/d0/ef6e82f7a68c7ac02e1a01815fbe88773f4f9e40728ed35bd1664a5d76f2/mkdocstrings_python-1.16.8-py3-none-any.whl", hash = "sha256:211b7aaf776cd45578ecb531e5ad0d3a35a8be9101a6bfa10de38a69af9d8fd8", size = 124116 },
 ]
 
 [[package]]
@@ -851,14 +851,14 @@ wheels = [
 
 [[package]]
 name = "pytest-asyncio"
-version = "0.25.3"
+version = "0.26.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pytest" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f2/a8/ecbc8ede70921dd2f544ab1cadd3ff3bf842af27f87bbdea774c7baa1d38/pytest_asyncio-0.25.3.tar.gz", hash = "sha256:fc1da2cf9f125ada7e710b4ddad05518d4cee187ae9412e9ac9271003497f07a", size = 54239 }
+sdist = { url = "https://files.pythonhosted.org/packages/8e/c4/453c52c659521066969523e87d85d54139bbd17b78f09532fb8eb8cdb58e/pytest_asyncio-0.26.0.tar.gz", hash = "sha256:c4df2a697648241ff39e7f0e4a73050b03f123f760673956cf0d72a4990e312f", size = 54156 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/67/17/3493c5624e48fd97156ebaec380dcaafee9506d7e2c46218ceebbb57d7de/pytest_asyncio-0.25.3-py3-none-any.whl", hash = "sha256:9e89518e0f9bd08928f97a3482fdc4e244df17529460bc038291ccaf8f85c7c3", size = 19467 },
+    { url = "https://files.pythonhosted.org/packages/20/7f/338843f449ace853647ace35870874f69a764d251872ed1b4de9f234822c/pytest_asyncio-0.26.0-py3-none-any.whl", hash = "sha256:7b51ed894f4fbea1340262bdae5135797ebbe21d8638978e35d31c6d19f72fb0", size = 19694 },
 ]
 
 [[package]]
@@ -900,11 +900,11 @@ wheels = [
 
 [[package]]
 name = "python-dotenv"
-version = "1.0.1"
+version = "1.1.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/bc/57/e84d88dfe0aec03b7a2d4327012c1627ab5f03652216c63d49846d7a6c58/python-dotenv-1.0.1.tar.gz", hash = "sha256:e324ee90a023d808f1959c46bcbc04446a10ced277783dc6ee09987c37ec10ca", size = 39115 }
+sdist = { url = "https://files.pythonhosted.org/packages/88/2c/7bb1416c5620485aa793f2de31d3df393d3686aa8a8506d11e10e13c5baf/python_dotenv-1.1.0.tar.gz", hash = "sha256:41f90bc6f5f177fb41f53e87666db362025010eb28f60a01c9143bfa33a2b2d5", size = 39920 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/6a/3e/b68c118422ec867fa7ab88444e1274aa40681c606d59ac27de5a5588f082/python_dotenv-1.0.1-py3-none-any.whl", hash = "sha256:f7b63ef50f1b690dddf550d03497b66d609393b40b564ed0d674909a68ebf16a", size = 19863 },
+    { url = "https://files.pythonhosted.org/packages/1e/18/98a99ad95133c6a6e2005fe89faedf294a748bd5dc803008059409ac9b1e/python_dotenv-1.1.0-py3-none-any.whl", hash = "sha256:d7c01d9e2293916c18baf562d95698754b0dbbb5e74d457c45d4f6561fb9d55d", size = 20256 },
 ]
 
 [[package]]

engin-0.0.14/docs/guides/dependency_injection.md

@@ -1,4 +0,0 @@
-
-## Dependency Injection
-
-TODO