engin 0.0.18__tar.gz → 0.0.20__tar.gz

engin-0.0.20/.github/workflows/benchmark.yaml

@@ -0,0 +1,38 @@
+name: Benchmark Main
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  benchmark-main:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install the project
+        run: uv sync --dev
+
+      - name: Run benchmark
+        run: |
+          uv run pytest tests --benchmark-only --benchmark-json bench.json
+
+      - name: Store benchmark result
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          tool: 'pytest'
+          output-file-path: bench.json
+          github-token: ${{ secrets.PAT }}
+          auto-push: true

{engin-0.0.18 → engin-0.0.20}/.github/workflows/check.yaml

@@ -6,7 +6,12 @@ on:
 jobs:
   check:
     name: python
-    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
 
     permissions:
       id-token: write

{engin-0.0.18 → engin-0.0.20}/CHANGELOG.md

@@ -6,6 +6,37 @@ 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.20] - 2025-06-18
+
+### Changed
+
+- Improved string representation of Provide & Supply to make error messages more helpful.
+
+### Fixed
+
+- Engin now correctly supports postponed evaluation of annotations, e.g. `x: "MyType"` in
+  a factory function.
+
+
+## [0.0.19] - 2025-04-27
+
+### Added
+
+- A new exception: `InvalidBlockError`.
+
+### Changed
+
+- Improved performance of Provide & Assembler by a factor of >2x (in certain scenarios).
+- Renamed the `ext` subpackage to `extensions`.
+- Errors are now imported from `engin.exceptions.*` instead of `engin.*`
+- Blocks will now raise an `InvalidBlockError` if the block has methods which are not
+  decorated with `@provide` & `@invoke`.
+
+### Fixed
+
+- `Assembler.add` incorrect cache invalidation logic.
+
+
 ## [0.0.18] - 2025-04-25
 
 ### Added

{engin-0.0.18 → engin-0.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.18
+Version: 0.0.20
 Summary: An async-first modular application framework
 Project-URL: Homepage, https://github.com/invokermain/engin
 Project-URL: Documentation, https://engin.readthedocs.io/en/latest/

engin-0.0.20/docs/concepts/blocks.md

@@ -0,0 +1,82 @@
+# Blocks
+
+A Block is a collection of options defined as a class.
+
+Blocks are useful for grouping related options, as they can then be passed to the Engin in
+one go helping manage complex applications.
+
+Blocks are preferred over other data structures such as a list of options as they
+integrate with other functionality in the rest of the framework.
+
+
+## Defining an empty Block
+
+A Block is just a class that inherits from `Block`:
+
+```python
+from engin import Engin, Block, provide, invoke
+
+
+class ExampleBlock(Block):
+    ...
+```
+
+## Adding options to the Block
+
+Blocks have a class attribute named `options` which can be used to include existing
+options.
+
+```python
+from engin import Engin, Block, Invoke, Provide, Supply
+
+
+def print_string(self, string: str) -> None:
+   print(string)
+
+   
+class ExampleBlock(Block):
+   options = [
+      Supply("hello"),
+      Invoke(print_string)
+   ]
+
+
+# register it as a provider with the Engin
+engin = Engin(ExampleBlock())
+
+await engin.run()  # prints 'hello'
+```
+
+!!!tip
+
+Blocks are themselves valid options, so Blocks can include other Blocks as options. This
+compisitional approach can help you build and manage larger applications.
+
+
+## Defining Providers & Invocations in the Block
+
+Engin ships two decorators: `@provide` & `@invoke` that can be used to define providers
+and invocations within a Block as methods. These decorators mirror the signature of their
+respective classes `Provide` & `Invoke`.
+
+
+```python
+from engin import Engin, Block, provide, invoke
+
+
+# this block is equivalent to the one in the example above
+class ExampleBlock(Block):
+    @provide
+    def string_factory() -> str:
+        return "hello"
+    
+    @invoke
+    def print_string(self, string: str) -> None:
+       print(string)
+```
+
+!!!note
+
+The `self` parameter in these methods is replaced with an empty object at runtime so
+should not be used. Blocks do not need to be instantiated to be passed to Engin as an
+option.

{engin-0.0.18 → engin-0.0.20}/docs/guides/fastapi.md

@@ -18,7 +18,7 @@ provide an instance of a `FastAPI` application:
 
 ```python
 from engin import Supply
-from engin.ext.fastapi import FastAPIEngin
+from engin.extensions.fastapi import FastAPIEngin
 from fastapi import FastAPI
 import uvicorn
 
@@ -74,19 +74,23 @@ reusable SQL session per request, we could use a nested dependency:
 ```python
 from typing import Annotated, AsyncIterable
 
-from engin.ext.fastapi import Inject
+from engin.extensions.fastapi import Inject
 from fastapi import Depends
 
+
 async def database_session(
-    database: Annotated[Database, Inject(Database)])
-) -> AsyncIterable[Session]:
+        database: Annotated[Database, Inject(Database)])
+
+    ) -> AsyncIterable[Session]:
     with database.new_session() as session:
         yield session
-        session.commit()
+    session.commit()
+
+    @ app.post("/{id}")
+    async
 
-@app.post("/{id}")
-async def add_item(session: Annotated[Session, Depends(database_session)]):
-    session.add(MyORMModel(...))
+    def add_item(session: Annotated[Session, Depends(database_session)]):
+        session.add(MyORMModel(...))
 ```
 
 
@@ -109,17 +113,18 @@ this is to use `Supply` as the router is already instantiated. We also need to a
 `APIRouter` to our `FastAPI` application, we can do this in the provider for `FastAPI`.
 
 ```python title="app.py"
-from engin.ext.fastapi import FastAPIEngin
+from engin.extensions.fastapi import FastAPIEngin
 from fastapi import FastAPI
 
 from api import users_router
 
+
 def create_fastapi_app(api_routers: list[APIRouter]) -> FastAPI:
     app = FastAPI()
-    
+
     for api_router in api_routers:
         app.include_router(api_router)
-        
+
     return app
 
 
@@ -135,21 +140,22 @@ Or similarly, we could use a block instead:
 
 ```python title="app.py"
 from engin import Block, provide
-from engin.ext.fastapi import FastAPIEngin
+from engin.extensions.fastapi import FastAPIEngin
 from fastapi import FastAPI
 
 from api import users_router
 
+
 class AppBlock(Block):
     options = [Supply([users_router])]
-    
+
     @provide
     def create_fastapi_app(self, api_routers: list[APIRouter]) -> FastAPI:
         app = FastAPI()
-        
+
         for api_router in api_routers:
             app.include_router(api_router)
-            
+
         return app
 
 

{engin-0.0.18 → engin-0.0.20}/examples/asgi/app.py

@@ -6,7 +6,7 @@ from starlette.responses import JSONResponse, Response
 from starlette.routing import Mount, Route
 
 from engin import Block, provide
-from engin.ext.asgi import ASGIType
+from engin.extensions.asgi import ASGIType
 
 
 class AppConfig(BaseSettings):

{engin-0.0.18 → engin-0.0.20}/examples/asgi/main.py

@@ -3,7 +3,7 @@ import logging
 import uvicorn
 
 from engin import Supply
-from engin.ext.asgi import ASGIEngin
+from engin.extensions.asgi import ASGIEngin
 from examples.asgi.app import AppBlock, AppConfig
 from examples.asgi.common.db.block import DatabaseBlock
 from examples.asgi.features.cats.block import CatBlock

{engin-0.0.18 → engin-0.0.20}/examples/fastapi/main.py

@@ -3,7 +3,7 @@ import logging
 import uvicorn
 
 from engin import Supply
-from engin.ext.fastapi import FastAPIEngin
+from engin.extensions.fastapi import FastAPIEngin
 from examples.fastapi.app import AppBlock, AppConfig
 from examples.fastapi.routes.cats.block import CatBlock
 

{engin-0.0.18 → engin-0.0.20}/examples/fastapi/routes/cats/api.py

@@ -3,7 +3,7 @@ from typing import Annotated
 from fastapi import APIRouter
 from pydantic import BaseModel
 
-from engin.ext.fastapi import Inject
+from engin.extensions.fastapi import Inject
 from examples.fastapi.routes.cats.domain import Cat, CatPersonality
 from examples.fastapi.routes.cats.ports import CatRepository
 

{engin-0.0.18 → engin-0.0.20}/mkdocs.yaml

@@ -33,6 +33,7 @@ nav:
       - Providers: "concepts/providers.md"
       - Invocations: "concepts/invocations.md"
       - Lifecycle: "concepts/lifecycle.md"
+      - Blocks: "concepts/blocks.md"
   - Guides:
       - FastAPI: "guides/fastapi.md"
   - Reference: "reference.md"

{engin-0.0.18 → engin-0.0.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "engin"
-version = "0.0.18"
+version = "0.0.20"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,6 +37,8 @@ dev = [
     "pytest-cov>=6.0.0",
     "typer>=0.15.2",
     "pytest-mock>=3.14.0",
+    "pytest-benchmark>=5.1.0",
+    "websockets>=15.0.1",
 ]
 docs = [
     "mkdocs-material>=9.5.50",
@@ -87,6 +89,29 @@ asyncio_default_fixture_loop_scope = "session"
 source = ["src"]
 omit = ["src/engin/scripts/**"]
 
+[tool.coverage.report]
+precision = 1
+skip_covered = true
+exclude_lines = [
+    "pragma: no cover",
+    "abc.abstractmethod",
+    "if TYPE_CHECKING.*:",
+    "if _t.TYPE_CHECKING:",
+    "if t.TYPE_CHECKING:",
+    "@overload",
+    'class .*\bProtocol\b.*\):',
+    "raise NotImplementedError",
+]
+partial_branches = [
+    "pragma: no branch",
+    "if not TYPE_CHECKING:",
+    "if not _t.TYPE_CHECKING:",
+    "if not t.TYPE_CHECKING:",
+    "if .* or not TYPE_CHECKING:",
+    "if .* or not _t.TYPE_CHECKING:",
+    "if .* or not t.TYPE_CHECKING:",
+]
+
 
 [tool.mypy]
 strict = true
@@ -112,6 +137,7 @@ check.sequence = [
 fix.default_item_type = "cmd"
 fix.sequence = ["ruff check src tests examples --fix"]
 
-test = "pytest tests"
-ci-test = "pytest --cov=engin --cov-branch --cov-report=xml tests"
+test = "pytest tests --benchmark-skip"
+ci-test = "pytest --cov=engin --cov-branch --cov-report=xml tests --benchmark-skip"
+bench = "pytest tests --benchmark-only"
 docs = "mkdocs serve"

{engin-0.0.18 → engin-0.0.20}/src/engin/__init__.py

@@ -1,9 +1,7 @@
-from engin import ext
 from engin._assembler import Assembler
 from engin._block import Block, invoke, provide
 from engin._dependency import Entrypoint, Invoke, Provide, Supply
 from engin._engin import Engin
-from engin._exceptions import ProviderError
 from engin._lifecycle import Lifecycle
 from engin._option import Option
 from engin._type_utils import TypeId
@@ -17,10 +15,8 @@ __all__ = [
     "Lifecycle",
     "Option",
     "Provide",
-    "ProviderError",
     "Supply",
     "TypeId",
-    "ext",
     "invoke",
     "provide",
 ]

{engin-0.0.18 → engin-0.0.20}/src/engin/_assembler.py

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

{engin-0.0.18 → engin-0.0.20}/src/engin/_block.py

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

{engin-0.0.18 → engin-0.0.20}/src/engin/_cli/_graph.py

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