engin 0.0.13__tar.gz → 0.0.15__tar.gz

{engin-0.0.13 → engin-0.0.15}/.readthedocs.yaml

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

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

@@ -6,7 +6,44 @@ 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.13] - 2025-03-12
+## [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.
+
+### Changed
+
+- `engin-graph` has been replaced by `engin graph`.
+- 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
 
 ### Changed
 

{engin-0.0.13 → engin-0.0.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.0.13
+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/
@@ -10,6 +10,8 @@ License-Expression: MIT
 License-File: LICENSE
 Keywords: Application Framework,Dependency Injection
 Requires-Python: >=3.10
+Provides-Extra: cli
+Requires-Dist: typer>=0.15; extra == 'cli'
 Description-Content-Type: text/markdown
 
 [![codecov](https://codecov.io/gh/invokermain/engin/graph/badge.svg?token=4PJOIMV6IB)](https://codecov.io/gh/invokermain/engin)

{engin-0.0.13 → engin-0.0.15}/docs/concepts/engin.md

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

{engin-0.0.13 → engin-0.0.15}/docs/concepts/invocations.md

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

engin-0.0.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.13 → 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.13 → engin-0.0.15}/docs/getting-started.md

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

{engin-0.0.13 → engin-0.0.15}/docs/guides/fastapi.md

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

engin-0.0.15/docs/js/readthedocs.js

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

{engin-0.0.13 → 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.13 → engin-0.0.15}/pyproject.toml

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

{engin-0.0.13 → engin-0.0.15}/src/engin/__init__.py

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