# Engin 🏎️
[](https://codecov.io/gh/invokermain/engin)
---
**Documentation**: [https://engin.readthedocs.io/](https://engin.readthedocs.io/)
**Source Code**: [https://github.com/invokermain/engin](https://github.com/invokermain/engin)
---
Engin is a lightweight application framework powered by dependency injection, it helps
you build and maintain large monoliths and many microservices.
## Feature
The Engin framework gives you:
- A fully-featured dependency injection system.
- A robust application runtime with lifecycle hooks and supervised background tasks.
- Zero boilerplate code reuse across applications.
- Integrations for other frameworks such as FastAPI.
- Full async support.
- CLI commands to aid local development.
## Installation
Engin is available on PyPI, install it using your favourite dependency manager:
- `pip install engin`
- `poetry add engin`
- `uv add engin`
## Example
A small example which shows some of the features of Engin. This application
makes 3 http requests and shuts itself down.
```python
import asyncio
from httpx import AsyncClient
from engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor
def httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:
# create our http client
client = AsyncClient()
# this will open and close the AsyncClient as part of the application's lifecycle
lifecycle.append(client)
return client
async def main(
httpx_client: AsyncClient,
supervisor: Supervisor,
) -> None:
async def http_requests_task():
# simulate a background task
for x in range(3):
await httpx_client.get("https://httpbin.org/get")
await asyncio.sleep(1.0)
# raise an error to shutdown the application, normally you wouldn't do this!
raise RuntimeError("Forcing shutdown")
# supervise the http requests as part of the application's lifecycle
supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)
# define our modular application
engin = Engin(Provide(httpx_client_factory), Invoke(main))
# run it!
asyncio.run(engin.run())
```
With logs enabled this will output:
```shell
INFO:engin:starting engin
INFO:engin:startup complete
INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
INFO:httpx:HTTP Request: GET https://httpbin.org/get "HTTP/1.1 200 OK"
ERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown
Traceback (most recent call last):
File "C:\dev\python\engin\src\engin\_supervisor.py", line 58, in __call__
await self.factory()
File "C:\dev\python\engin\readme_example.py", line 29, in http_requests_task
raise RuntimeError("Forcing shutdown")
RuntimeError: Forcing shutdown
INFO:engin:stopping engin
INFO:engin:shutdown complete
```
## Inspiration
Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx)
and the [Injector framework for Python](https://github.com/python-injector/injector).
They are both great projects, go check them out.
Raw data
{
"_id": null,
"home_page": null,
"name": "engin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Application Framework, Dependency Injection",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/fd/78/7897568ea3cff68bf820d72ae1c762fdc35d401f388f7adb646456a1622b/engin-0.1.0.tar.gz",
"platform": null,
"description": "# Engin \ud83c\udfce\ufe0f\n\n[](https://codecov.io/gh/invokermain/engin)\n\n---\n\n**Documentation**: [https://engin.readthedocs.io/](https://engin.readthedocs.io/)\n\n**Source Code**: [https://github.com/invokermain/engin](https://github.com/invokermain/engin)\n\n---\n\nEngin is a lightweight application framework powered by dependency injection, it helps\nyou build and maintain large monoliths and many microservices.\n\n\n## Feature\n\nThe Engin framework gives you:\n\n- A fully-featured dependency injection system.\n- A robust application runtime with lifecycle hooks and supervised background tasks.\n- Zero boilerplate code reuse across applications.\n- Integrations for other frameworks such as FastAPI.\n- Full async support.\n- CLI commands to aid local development.\n\n\n## Installation\n\nEngin is available on PyPI, install it using your favourite dependency manager:\n\n- `pip install engin`\n- `poetry add engin`\n- `uv add engin`\n\n## Example\n\nA small example which shows some of the features of Engin. This application\nmakes 3 http requests and shuts itself down.\n\n```python\nimport asyncio\nfrom httpx import AsyncClient\nfrom engin import Engin, Invoke, Lifecycle, OnException, Provide, Supervisor\n\n\ndef httpx_client_factory(lifecycle: Lifecycle) -> AsyncClient:\n # create our http client\n client = AsyncClient()\n # this will open and close the AsyncClient as part of the application's lifecycle\n lifecycle.append(client)\n return client\n\n\nasync def main(\n httpx_client: AsyncClient,\n supervisor: Supervisor,\n) -> None:\n async def http_requests_task():\n # simulate a background task\n for x in range(3):\n await httpx_client.get(\"https://httpbin.org/get\")\n await asyncio.sleep(1.0)\n # raise an error to shutdown the application, normally you wouldn't do this!\n raise RuntimeError(\"Forcing shutdown\")\n\n # supervise the http requests as part of the application's lifecycle\n supervisor.supervise(http_requests_task, on_exception=OnException.SHUTDOWN)\n\n\n# define our modular application\nengin = Engin(Provide(httpx_client_factory), Invoke(main))\n\n# run it!\nasyncio.run(engin.run())\n```\n\nWith logs enabled this will output:\n\n```shell\nINFO:engin:starting engin\nINFO:engin:startup complete\nINFO:httpx:HTTP Request: GET https://httpbin.org/get \"HTTP/1.1 200 OK\"\nINFO:httpx:HTTP Request: GET https://httpbin.org/get \"HTTP/1.1 200 OK\"\nINFO:httpx:HTTP Request: GET https://httpbin.org/get \"HTTP/1.1 200 OK\"\nERROR:engin:supervisor task 'http_requests_task' raised RuntimeError, starting shutdown\nTraceback (most recent call last):\n File \"C:\\dev\\python\\engin\\src\\engin\\_supervisor.py\", line 58, in __call__\n await self.factory()\n File \"C:\\dev\\python\\engin\\readme_example.py\", line 29, in http_requests_task\n raise RuntimeError(\"Forcing shutdown\")\nRuntimeError: Forcing shutdown\nINFO:engin:stopping engin\nINFO:engin:shutdown complete\n```\n\n## Inspiration\n\nEngin is heavily inspired by [Uber's Fx framework for Go](https://github.com/uber-go/fx)\nand the [Injector framework for Python](https://github.com/python-injector/injector).\n\nThey are both great projects, go check them out.\n",
"bugtrack_url": null,
"license": null,
"summary": "An async-first modular application framework",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/invokermain/engin/blob/main/CHANGELOG.md",
"Documentation": "https://engin.readthedocs.io/en/latest/",
"Homepage": "https://github.com/invokermain/engin",
"Repository": "https://github.com/invokermain/engin.git"
},
"split_keywords": [
"application framework",
" dependency injection"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b8c90c59f44661bbcde43eae45b196ca1cabcba4415d8d278549c300ba051e1c",
"md5": "dc4efd58a3302145af8c1321eb56bdcc",
"sha256": "2136997588fd467a0cec4fe8cdeb6e720750eacbac49d5c88c28331432f2266e"
},
"downloads": -1,
"filename": "engin-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc4efd58a3302145af8c1321eb56bdcc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 37074,
"upload_time": "2025-08-16T16:10:36",
"upload_time_iso_8601": "2025-08-16T16:10:36.708403Z",
"url": "https://files.pythonhosted.org/packages/b8/c9/0c59f44661bbcde43eae45b196ca1cabcba4415d8d278549c300ba051e1c/engin-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fd787897568ea3cff68bf820d72ae1c762fdc35d401f388f7adb646456a1622b",
"md5": "e7d784b52604dff2a56a47d89fb2eda2",
"sha256": "a26ea5036e04309d6579cb58bb2d53c7540a5c0931f8d1e21953331698df6127"
},
"downloads": -1,
"filename": "engin-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e7d784b52604dff2a56a47d89fb2eda2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 186696,
"upload_time": "2025-08-16T16:10:37",
"upload_time_iso_8601": "2025-08-16T16:10:37.603933Z",
"url": "https://files.pythonhosted.org/packages/fd/78/7897568ea3cff68bf820d72ae1c762fdc35d401f388f7adb646456a1622b/engin-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 16:10:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "invokermain",
"github_project": "engin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "engin"
}
JSON
