engin 0.0.6__tar.gz → 0.0.8__tar.gz

{engin-0.0.6 → engin-0.0.8}/CHANGELOG.md

@@ -6,6 +6,21 @@ 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.8] - 2025-02-22
+
+### Added
+
+- A package script, `engin-graph` for visualising the dependency graph.
+
+
+## [0.0.7] - 2025-02-20
+
+### Changed
+
+- TypeId retains Annotations allowing them to be used to discriminate otherwise identical
+  types.
+
+
 ## [0.0.6] - 2025-02-19
 
 ### Fixed

{engin-0.0.6 → engin-0.0.8}/PKG-INFO

@@ -1,8 +1,14 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.6
+Version: 0.0.8
 Summary: An async-first modular application framework
+Project-URL: Homepage, https://github.com/invokermain/engin
+Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/invokermain/engin.git
+Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+License-Expression: MIT
 License-File: LICENSE
+Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 

engin-0.0.8/docs/concepts/engin.md

@@ -0,0 +1,11 @@
+# The Engin
+
+The Engin is a self-contained modular application.
+
+When ran the Engin takes care of the complete application lifecycle:
+1. The Engin assembles all Invocations. Only Providers that are required to satisfy
+   the Invocations parameters are assembled.
+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.

engin-0.0.8/docs/concepts/invocations.md

@@ -0,0 +1,132 @@
+# Invocations
+
+Invocations define the behaviour of your application, therefore without any Invocations
+your application will not do anything.
+
+Like providers invocations are functions that take one or more dependencies as parameters,
+and they should always return None as the return value will not used by the Engin.
+
+As part of the Engin's startup, all declared invocations will be called sequentially in
+the order they were registered.
+
+Invocations can be used to define behaviour in two ways.
+
+**Implicit: Provider Lifecycle**
+
+Invocations are always called therefore their dependencies are always assembled. This
+means that any providers with lifecycles will register their lifecycles with the
+application if directly or indirectly used by an invocation.
+
+To illustrate this, imagine we have a provider for an imaginary `Worker` type that is our
+applications primary functionality. Our factory might look like the below (omitting 
+imports for brevity):
+
+```python
+def worker_factory(lifecycle: Lifecycle) -> Worker:
+   worker = Worker()
+   
+   @asynccontextmanager
+   async def worker_lifecycle() -> Iterable[None]:
+       worker.start()
+       yield
+       worker.shutdown()
+       
+    lifecycle.append(worker_lifecycle)
+   
+    return worker
+```
+
+We can register it with the Engin as a provider.
+
+```python 
+engin = Engin(Provide(worker_factory))
+```
+
+However, when we run the `engin` nothing happens. It will not start the `Worker` as it is
+not required by any invocations. Let us fix that by adding the invocation.
+
+```python
+def use_worker(worker: Worker) -> None:
+    return None
+
+
+engin = Engin(Provide(worker_factory), Invoke(use_worker))
+```
+
+Now when we run the `engin` a `Worker` is constructed and it starts up. This invocation
+has no behaviour of its own, hence we can call it implicit, but by registering it with the
+Engin it declares the behaviour we want our modular application to have at runtime.
+
+This pattern of empty invocations as declaration of intended behaviour is very common, so
+the framework has a marker class called `Entrypoint` as a shorthand for the above.
+
+```python
+engin = Engin(Provide(worker_factory), Entrypoint(Worker))
+```
+
+This `engin` has the same behaviour as the one declared above. Entrypoints can be
+considered idiomatic as they have more explicit semantics.
+
+**Explicit: Invoked Behaviour**
+
+Sometimes you want to have logic that runs before the lifecycle startup occurs and after
+the dependency graph is built, some examples might be:
+- Pining a server to check its healthy.
+- Running database migrations.
+- Configuring a logger.
+
+In these cases you would simply write an invocation that does these things, for example:
+
+```python
+def run_database_migrations(conn: SQLConnection) -> None:
+    print("running database migrations")
+    required_migrations = get_migrations(conn)
+    for migration in required_migrations:
+        print(f"migrating database to version {migration.version}")
+        migration.execute(conn)
+
+engin = Engin(Provide(sql_connection_factory), Invoke(run_database_migrations), ...)
+```
+
+
+## Defining an invocation
+
+Any function can be turned into an invocation by using the marker class: `Invoke`.
+
+```python
+import asyncio
+from engin import Engin, Invoke
+
+# define a function with some behaviour
+def print_hello_world() -> None:
+   print("hello world!")
+
+# register it as a invocation with the Engin
+engin = Engin(Invoke(print_hello_world))
+
+# run your application
+asyncio.run(engin.run())  # hello world!
+```
+
+
+## Invocations can use provided types
+
+Invocations can use any types as long as they have the matching providers.
+
+```python
+import asyncio
+from engin import Engin, Invoke
+
+# define a constructor
+def name_factory() -> str:
+    return "Dmitrii"
+
+def print_hello(name: str) -> None:
+   print(f"hello {name}!")
+
+# register it as a invocation with the Engin
+engin = Engin(Provide(name_factory()), Invoke(hello_world))
+
+# run your application
+asyncio.run(engin.run())  # hello Dmitrii!
+```

engin-0.0.8/docs/concepts/providers.md

@@ -0,0 +1,176 @@
+# Providers
+
+Providers are the factories of your application, they are reponsible for the construction
+of the objects that your application needs.
+
+Remember, the Engin only calls the providers that are necessary to run your application.
+More specifically: when starting up the Engin will call all providers necessary to run its
+invocations, and the Assembler (the component responsible for constructing types) will
+call any providers that these providers require and so on.
+
+
+## Defining a provider
+
+Any function that returns an object can be turned into a provider by using the marker
+class: `Provide`.
+
+```python
+from engin import Engin, Provide
+
+# define our constructor
+def string_factory() -> str:
+   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)
+
+print(a_string) # hello
+```
+
+Providers can be asynchronous as well, this factory function would work exactly the same
+in the above example.
+
+```python
+async def string_factory() -> str:
+   return "hello"
+```
+
+## Providers can use other providers
+
+Providers that construct more interesting objects generally require their own parameters.
+
+```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"
+
+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.greet("Bob") # hello, Bob!
+```
+
+
+## Providers are only called when required
+
+The Assembler will only call a provider when the type is requested, directly or indirectly
+when constructing an object. This means that your application will do the minimum work
+required on startup.
+
+```python
+from engin import Engin, Provide
+
+
+# define our constructors
+def string_factory() -> str:
+   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)
+
+# this will raise an error
+await engin.assembler.get(int)
+```
+
+
+## Multiproviders
+
+Sometimes it is useful for many providers to construct a single collection of objects,
+these are called multiproviders. For example in a web application, many
+distinct providers could register one or more routes, and the root of the application
+would handle registering them.
+
+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"]
+
+def other_animal_names_factory() -> list[str]:
+   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])
+
+print(animal_names) # ["cat", "dog", "horse", "cow"]
+```
+
+
+## Discriminating providers of the same type
+
+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"
+
+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"])
+
+# this will return "Jelena"
+await engin.assembler.get(Annotated[str, "name"])
+
+# N.B. this will raise an error!
+await engin.assembler.get(str)
+```
+
+
+## Supply can be used for static objects
+
+The `Supply` marker class can be used as a shorthand when provided static objects. The
+provided type is automatically inferred.
+
+For example the first example on this page could be rewritten as:
+
+
+```python
+from engin import Engin, Supply
+
+# Supply the Engin with a str value
+engin = Engin(Supply("hello"))
+
+# construct the string
+a_string = await engin.assembler.get(str)
+
+print(a_string) # hello
+```

{engin-0.0.6 → engin-0.0.8}/examples/fastapi/main.py

@@ -11,4 +11,6 @@ logging.basicConfig(level=logging.DEBUG)
 
 app = FastAPIEngin(AppBlock(), CatBlock(), Supply(AppConfig(debug=True)))
 
-uvicorn.run(app)
+
+if __name__ == "__main__":
+    uvicorn.run(app)

{engin-0.0.6 → engin-0.0.8}/examples/simple/main.py

@@ -19,4 +19,5 @@ async def main(http_client: AsyncClient) -> None:
 
 engin = Engin(Provide(new_httpx_client), Invoke(main))
 
-asyncio.run(engin.run())
+if __name__ == "__main__":
+    asyncio.run(engin.run())

{engin-0.0.6 → engin-0.0.8}/pyproject.toml

@@ -1,11 +1,19 @@
 [project]
 name = "engin"
-version = "0.0.6"
+version = "0.0.8"
 description = "An async-first modular application framework"
 readme = "README.md"
 requires-python = ">=3.10"
+license = "MIT"
+keywords = ["Dependency Injection", "Application Framework"]
 dependencies = []
 
+[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"
@@ -34,6 +42,10 @@ docs = [
 ]
 
 
+[project.scripts]
+engin-graph = "engin.scripts.graph:serve_graph"
+
+
 [tool.ruff]
 line-length = 95
 target-version = "py310"
@@ -54,7 +66,9 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "**/src/*" = ["PT"]
 "**/tests/*" = ["S", "ANN"]
+# allow print statements in examples/scripts
 "**/examples/*" = ["T201"]
+"**/scripts/*" = ["T201"]
 
 
 [tool.pytest.ini_options]

{engin-0.0.6 → engin-0.0.8}/src/engin/_dependency.py

@@ -18,7 +18,6 @@ from engin._type_utils import TypeId, type_id_of
 P = ParamSpec("P")
 T = TypeVar("T")
 Func: TypeAlias = Callable[P, T]
-_SELF = object()
 
 
 def _noop(*args: Any, **kwargs: Any) -> None: ...
@@ -31,6 +30,10 @@ class Dependency(ABC, Generic[P, T]):
         self._signature = inspect.signature(self._func)
         self._block_name = block_name
 
+    @property
+    def module(self) -> str:
+        return self._func.__module__
+
     @property
     def block_name(self) -> str | None:
         return self._block_name
@@ -136,7 +139,7 @@ class Provide(Dependency[Any, T]):
             return_type = self._func  # __init__ returns self
         else:
             try:
-                return_type = get_type_hints(self._func)["return"]
+                return_type = get_type_hints(self._func, include_extras=True)["return"]
             except KeyError as err:
                 raise RuntimeError(
                     f"Dependency '{self.name}' requires a return typehint"

{engin-0.0.6 → engin-0.0.8}/src/engin/_engin.py

@@ -13,6 +13,7 @@ from engin import Entrypoint
 from engin._assembler import AssembledDependency, Assembler
 from engin._block import Block
 from engin._dependency import Dependency, Invoke, Provide, Supply
+from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._type_utils import TypeId
 
@@ -35,8 +36,7 @@ class Engin:
     Supply) and at least one invocation (Invoke or Entrypoint).
 
     When instantiated the Engin can be run. This is typically done via the `run` method,
-    but certain use cases, e.g. testing, it can be easier to use the `start` and `stop`
-    methods.
+    but for advanced usecases it can be easier to use the `start` and `stop` methods.
 
     When ran the Engin takes care of the complete application lifecycle:
     1. The Engin assembles all Invocations. Only Providers that are required to satisfy
@@ -81,7 +81,6 @@ class Engin:
         Args:
             *options: an instance of Provide, Supply, Invoke, Entrypoint or a Block.
         """
-
         self._stop_requested_event = Event()
         self._stop_complete_event = Event()
         self._exit_stack: AsyncExitStack = AsyncExitStack()
@@ -96,8 +95,6 @@ class Engin:
         self._destruct_options(chain(self._LIB_OPTIONS, options))
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]
         self._assembler = Assembler(chain(self._providers.values(), multi_providers))
-        self._providers.clear()
-        self._multiproviders.clear()
 
     @property
     def assembler(self) -> Assembler:
@@ -163,6 +160,10 @@ class Engin:
             return
         await self._stop_complete_event.wait()
 
+    def graph(self) -> list[Node]:
+        grapher = DependencyGrapher({**self._providers, **self._multiproviders})
+        return grapher.resolve(self._invocations)
+
     async def _shutdown(self) -> None:
         LOG.info("stopping engin")
         await self._exit_stack.aclose()

engin-0.0.8/src/engin/_graph.py

@@ -0,0 +1,39 @@
+from collections.abc import Iterable
+from typing import TypedDict
+
+from engin._dependency import Dependency, Provide
+from engin._type_utils import TypeId
+
+
+class Node(TypedDict):
+    node: Dependency
+    parent: Dependency | None
+
+
+class DependencyGrapher:
+    def __init__(self, providers: dict[TypeId, Provide | list[Provide]]) -> None:
+        self._providers: dict[TypeId, Provide | list[Provide]] = providers
+
+    def resolve(self, roots: Iterable[Dependency]) -> list[Node]:
+        seen: set[TypeId] = set()
+        nodes: list[Node] = []
+
+        for root in roots:
+            for parameter in root.parameter_types:
+                if parameter in seen:
+                    continue
+
+                seen.add(parameter)
+                provider = self._providers[parameter]
+
+                # multiprovider
+                if isinstance(provider, list):
+                    for p in provider:
+                        nodes.append({"node": p, "parent": root})
+                        nodes.extend(self.resolve([p]))
+                # single provider
+                else:
+                    nodes.append({"node": provider, "parent": root})
+                    nodes.extend(self.resolve([provider]))
+
+        return nodes

engin-0.0.8/src/engin/scripts/graph.py

@@ -0,0 +1,122 @@
+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 engin import Engin
+from engin._dependency import Dependency, Provide
+
+# 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(
+    "-e", "--exclude", help="a list of packages or module to exclude", default=["engin"]
+)
+args.add_argument(
+    "app",
+    help=(
+        "the import path of your Engin instance, in the form "
+        "'package:application', e.g. 'app.main:engin'"
+    ),
+)
+
+
+def serve_graph() -> None:
+    # add cwd to path to enable local package imports
+    sys.path.insert(0, "")
+
+    parsed = args.parse_args()
+
+    app = parsed.app
+    excluded_modules = parsed.exclude
+
+    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
+
+    module = importlib.import_module(module_name)
+
+    try:
+        instance = getattr(module, engin_name)
+    except LookupError:
+        raise LookupError(f"Module '{module_name}' has no attribute '{engin_name}'") from None
+
+    if not isinstance(instance, Engin):
+        raise TypeError(f"'{app}' is not an Engin instance")
+
+    nodes = instance.graph()
+
+    # transform dependencies into mermaid syntax
+    dependencies = [
+        f"{_render_node(node['parent'])} --> {_render_node(node['node'])}"
+        for node in nodes
+        if node["parent"] is not None
+        and not _should_exclude(node["node"].module, excluded_modules)
+    ]
+
+    html = _GRAPH_HTML.replace("%%DATA%%", "\n".join(dependencies)).encode("utf8")
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:
+            self.send_response(200, "OK")
+            self.send_header("Content-type", "html")
+            self.end_headers()
+            self.wfile.write(html)
+
+        def log_message(self, format: str, *args: Any) -> None:
+            return
+
+    def _start_server() -> None:
+        with socketserver.TCPServer(("localhost", 8123), Handler) as httpd:
+            print("Serving dependency graph on http://localhost:8123")
+            httpd.serve_forever()
+
+    server_thread = threading.Thread(target=_start_server)
+    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...")
+
+
+def _render_node(node: Dependency) -> str:
+    if isinstance(node, Provide):
+        return str(node.return_type_id)
+    else:
+        return node.name
+
+
+def _should_exclude(module: str, excluded: list[str]) -> bool:
+    return any(module.startswith(e) for e in excluded)
+
+
+_GRAPH_HTML = """
+<!doctype html>
+<html lang="en">
+  <body>
+    <pre class="mermaid">
+      graph TD
+          %%DATA%%
+    </pre>
+    <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 } };
+      mermaid.initialize(config);
+    </script>
+  </body>
+</html>
+"""

{engin-0.0.6 → engin-0.0.8}/tests/test_assembler.py

@@ -1,3 +1,5 @@
+from typing import Annotated
+
 import pytest
 
 from engin import Assembler, Invoke, Provide
@@ -65,3 +67,19 @@ async def test_assembler_with_unknown_type_raises_assembly_error():
 
     with pytest.raises(ProviderError):
         await assembler.get(str)
+
+
+async def test_annotations():
+    def make_str_1() -> Annotated[str, "1"]:
+        return "bar"
+
+    def make_str_2() -> Annotated[str, "2"]:
+        return "foo"
+
+    assembler = Assembler([Provide(make_str_1), Provide(make_str_2)])
+
+    with pytest.raises(LookupError):
+        await assembler.get(str)
+
+    assert await assembler.get(Annotated[str, "1"]) == "bar"
+    assert await assembler.get(Annotated[str, "2"]) == "foo"