engin 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

engin/_assembler.py

@@ -4,7 +4,7 @@ from collections import defaultdict
 from collections.abc import Collection, Iterable
 from dataclasses import dataclass
 from inspect import BoundArguments, Signature
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic, TypeVar, cast
 
 from engin._dependency import Dependency, Provide, Supply
 from engin._exceptions import AssemblyError
@@ -113,7 +113,7 @@ class Assembler:
     async def get(self, type_: type[T]) -> T:
         type_id = type_id_of(type_)
         if type_id in self._dependencies:
-            return self._dependencies[type_id]
+            return cast(T, self._dependencies[type_id])
         if type_id.multi:
             out = []
             for provider in self._multiproviders[type_id]:

engin/_block.py

@@ -1,29 +1,29 @@
 import inspect
 from collections.abc import Iterable, Iterator
+from typing import ClassVar
 
 from engin._dependency import Func, Invoke, Provide
 
 
 def provide(func: Func) -> Func:
-    func._opt = Provide(func)  # type: ignore[union-attr]
+    func._opt = Provide(func)  # type: ignore[attr-defined]
     return func
 
 
 def invoke(func: Func) -> Func:
-    func._opt = Invoke(func)  # type: ignore[union-attr]
+    func._opt = Invoke(func)  # type: ignore[attr-defined]
     return func
 
 
 class Block(Iterable[Provide | Invoke]):
-    _name: str
-    _options: list[Provide | Invoke]
+    options: ClassVar[list[Provide | Invoke]] = []
 
     def __init__(self, /, block_name: str | None = None) -> None:
-        self._options: list[Provide | Invoke] = []
+        self._options: list[Provide | Invoke] = self.options[:]
         self._name = block_name or f"{type(self).__name__}"
         for _, method in inspect.getmembers(self):
             if opt := getattr(method, "_opt", None):
-                if not isinstance(opt, (Provide, Invoke)):
+                if not isinstance(opt, Provide | Invoke):
                     raise RuntimeError("Block option is not an instance of Provide or Invoke")
                 opt.set_block_name(self._name)
                 self._options.append(opt)

engin/_dependency.py

@@ -1,14 +1,12 @@
 import inspect
 import typing
 from abc import ABC
+from collections.abc import Awaitable, Callable
 from inspect import Parameter, Signature, isclass, iscoroutinefunction
 from typing import (
     Any,
-    Awaitable,
-    Callable,
     Generic,
     ParamSpec,
-    Type,
     TypeAlias,
     TypeVar,
     cast,
@@ -19,13 +17,11 @@ from engin._type_utils import TypeId, type_id_of
 
 P = ParamSpec("P")
 T = TypeVar("T")
-Func: TypeAlias = (
-    Callable[P, T] | Callable[P, Awaitable[T]] | Callable[[], T] | Callable[[], Awaitable[T]]
-)
+Func: TypeAlias = Callable[P, T]
 _SELF = object()
 
 
-def _noop(*args, **kwargs) -> None: ...
+def _noop(*args: Any, **kwargs: Any) -> None: ...
 
 
 class Dependency(ABC, Generic[P, T]):
@@ -66,11 +62,11 @@ class Dependency(ABC, Generic[P, T]):
         if self._is_async:
             return await cast(Awaitable[T], self._func(*args, **kwargs))
         else:
-            return cast(T, self._func(*args, **kwargs))
+            return self._func(*args, **kwargs)
 
 
 class Invoke(Dependency):
-    def __init__(self, invocation: Func[P, T], block_name: str | None = None):
+    def __init__(self, invocation: Func[P, T], block_name: str | None = None) -> None:
         super().__init__(func=invocation, block_name=block_name)
 
     def __str__(self) -> str:
@@ -78,7 +74,7 @@ class Invoke(Dependency):
 
 
 class Entrypoint(Invoke):
-    def __init__(self, type_: Type[Any], *, block_name: str | None = None) -> None:
+    def __init__(self, type_: type[Any], *, block_name: str | None = None) -> None:
         self._type = type_
         super().__init__(invocation=_noop, block_name=block_name)
 
@@ -99,7 +95,7 @@ class Entrypoint(Invoke):
 
 
 class Provide(Dependency[Any, T]):
-    def __init__(self, builder: Func[P, T], block_name: str | None = None):
+    def __init__(self, builder: Func[P, T], block_name: str | None = None) -> None:
         super().__init__(func=builder, block_name=block_name)
         self._is_multi = typing.get_origin(self.return_type) is list
 
@@ -111,14 +107,16 @@ class Provide(Dependency[Any, T]):
                 )
 
     @property
-    def return_type(self) -> Type[T]:
+    def return_type(self) -> type[T]:
         if isclass(self._func):
             return_type = self._func  # __init__ returns self
         else:
             try:
                 return_type = get_type_hints(self._func)["return"]
-            except KeyError:
-                raise RuntimeError(f"Dependency '{self.name}' requires a return typehint")
+            except KeyError as err:
+                raise RuntimeError(
+                    f"Dependency '{self.name}' requires a return typehint"
+                ) from err
 
         return return_type
 
@@ -140,7 +138,7 @@ 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
-    ):
+    ) -> None:
         self._value = value
         self._type_hint = type_hint
         if self._type_hint is not None:
@@ -148,7 +146,7 @@ class Supply(Provide, Generic[T]):
         super().__init__(builder=self._get_val, block_name=block_name)
 
     @property
-    def return_type(self) -> Type[T]:
+    def return_type(self) -> type[T]:
         if self._type_hint is not None:
             return self._type_hint
         if isinstance(self._value, list):

engin/_engin.py

@@ -1,7 +1,12 @@
+import asyncio
 import logging
-from asyncio import Event
+import os
+import signal
+from asyncio import Event, Task
 from collections.abc import Iterable
+from contextlib import AsyncExitStack
 from itertools import chain
+from types import FrameType
 from typing import ClassVar, TypeAlias
 
 from engin import Entrypoint
@@ -16,14 +21,47 @@ LOG = logging.getLogger("engin")
 Option: TypeAlias = Invoke | Provide | Supply | Block
 _Opt: TypeAlias = Invoke | Provide | Supply
 
+_OS_IS_WINDOWS = os.name == "nt"
+
 
 class Engin:
+    """
+    The Engin class runs your application. It assembles the required dependencies, invokes
+    any invocations and manages your application's lifecycle.
+
+    Examples:
+        ```python
+        import asyncio
+
+        from httpx import AsyncClient
+
+        from engin import Engin, Invoke, Provide
+
+
+        def httpx_client() -> AsyncClient:
+            return AsyncClient()
+
+
+        async def main(http_client: AsyncClient) -> None:
+            print(await http_client.get("https://httpbin.org/get"))
+
+        engin = Engin(Provide(httpx_client), Invoke(main))
+
+        asyncio.run(engin.run())
+        ```
+    """
+
     _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
 
     def __init__(self, *options: Option) -> None:
         self._providers: dict[TypeId, Provide] = {TypeId.from_type(Engin): Provide(self._self)}
         self._invokables: list[Invoke] = []
-        self._stop_event = Event()
+
+        self._stop_requested_event = Event()
+        self._stop_complete_event = Event()
+        self._exit_stack: AsyncExitStack = AsyncExitStack()
+        self._shutdown_task: Task | None = None
+        self._run_task: Task | None = None
 
         self._destruct_options(chain(self._LIB_OPTIONS, options))
         self._assembler = Assembler(self._providers.values())
@@ -32,33 +70,69 @@ class Engin:
     def assembler(self) -> Assembler:
         return self._assembler
 
-    async def run(self):
+    async def run(self) -> None:
+        """
+        Run the Engin and wait for it to be stopped via an external signal or by calling
+        the `stop` method.
+        """
         await self.start()
-
-        # wait till stop signal recieved
-        await self._stop_event.wait()
+        self._run_task = asyncio.create_task(_raise_on_stop(self._stop_requested_event))
+        await self._stop_requested_event.wait()
+        await self._shutdown()
 
     async def start(self) -> None:
+        """
+        Starts the engin, this method waits for the shutdown lifecycle to complete.
+        """
         LOG.info("starting engin")
         assembled_invocations: list[AssembledDependency] = [
             await self._assembler.assemble(invocation) for invocation in self._invokables
         ]
+
         for invocation in assembled_invocations:
-            await invocation()
+            try:
+                await invocation()
+            except Exception as err:
+                name = invocation.dependency.name
+                LOG.error(f"invocation '{name}' errored, exiting", exc_info=err)
+                return
 
         lifecycle = await self._assembler.get(Lifecycle)
-        await lifecycle.startup()
-        self._stop_event = Event()
+
+        try:
+            for hook in lifecycle.list():
+                await self._exit_stack.enter_async_context(hook)
+        except Exception as err:
+            LOG.error("lifecycle startup error, exiting", exc_info=err)
+            await self._exit_stack.aclose()
+            return
+
         LOG.info("startup complete")
 
-    async def stop(self) -> None:
-        self._stop_event.set()
+        self._shutdown_task = asyncio.create_task(self._shutdown_when_stopped())
 
-    def _destruct_options(self, options: Iterable[Option]):
+    async def stop(self) -> None:
+        """
+        Stops the engin, this method waits for the shutdown lifecycle to complete.
+        """
+        self._stop_requested_event.set()
+        await self._stop_complete_event.wait()
+
+    async def _shutdown(self) -> None:
+        LOG.info("stopping engin")
+        await self._exit_stack.aclose()
+        self._stop_complete_event.set()
+        LOG.info("shutdown complete")
+
+    async def _shutdown_when_stopped(self) -> None:
+        await self._stop_requested_event.wait()
+        await self._shutdown()
+
+    def _destruct_options(self, options: Iterable[Option]) -> None:
         for opt in options:
             if isinstance(opt, Block):
                 self._destruct_options(opt)
-            if isinstance(opt, (Provide, Supply)):
+            if isinstance(opt, Provide | Supply):
                 existing = self._providers.get(opt.return_type_id)
                 self._log_option(opt, overwrites=existing)
                 self._providers[opt.return_type_id] = opt
@@ -86,3 +160,44 @@ class Engin:
 
     def _self(self) -> "Engin":
         return self
+
+
+class _StopRequested(RuntimeError):
+    pass
+
+
+async def _raise_on_stop(stop_requested_event: Event) -> None:
+    """
+    This method is based off of the Temporal Python SDK's Worker class:
+    https://github.com/temporalio/sdk-python/blob/main/temporalio/worker/_worker.py#L488
+    """
+    try:
+        # try to gracefully handle sigint/sigterm
+        if not _OS_IS_WINDOWS:
+            loop = asyncio.get_running_loop()
+            for signame in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(signame, stop_requested_event.set)
+
+            await stop_requested_event.wait()
+            raise _StopRequested()
+        else:
+            should_stop = False
+
+            # windows does not support signal_handlers, so this is the workaround
+            def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
+                nonlocal should_stop
+                if should_stop:
+                    raise KeyboardInterrupt("Forced keyboard interrupt")
+                should_stop = True
+
+            signal.signal(signal.SIGINT, ctrlc_handler)
+
+            while not should_stop:
+                # In case engin is stopped via external `stop` call.
+                if stop_requested_event.is_set():
+                    return
+                await asyncio.sleep(0.1)
+
+            stop_requested_event.set()
+    except asyncio.CancelledError:
+        pass

engin/_lifecycle.py

@@ -1,21 +1,38 @@
-from collections.abc import Callable
-from contextlib import AbstractAsyncContextManager, AsyncExitStack
+import logging
+from contextlib import AbstractAsyncContextManager
+from types import TracebackType
+
+LOG = logging.getLogger("engin")
 
 
 class Lifecycle:
     def __init__(self) -> None:
-        self._on_startup: list[Callable] = []
-        self._on_shutdown: list[Callable] = []
         self._context_managers: list[AbstractAsyncContextManager] = []
-        self._stack: AsyncExitStack = AsyncExitStack()
 
-    def register_context(self, cm: AbstractAsyncContextManager):
-        self._context_managers.append(cm)
+    def append(self, cm: AbstractAsyncContextManager) -> None:
+        suppressed_cm = _AExitSuppressingAsyncContextManager(cm)
+        self._context_managers.append(suppressed_cm)
+
+    def list(self) -> list[AbstractAsyncContextManager]:
+        return self._context_managers[:]
+
+
+class _AExitSuppressingAsyncContextManager(AbstractAsyncContextManager):
+    def __init__(self, cm: AbstractAsyncContextManager) -> None:
+        self._cm = cm
 
-    async def startup(self) -> None:
-        self._stack = AsyncExitStack()
-        for cm in self._context_managers:
-            await self._stack.enter_async_context(cm)
+    async def __aenter__(self) -> AbstractAsyncContextManager:
+        await self._cm.__aenter__()
+        return self._cm
 
-    async def shutdown(self) -> None:
-        await self._stack.aclose()
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None:
+        try:
+            await self._cm.__aexit__(exc_type, exc_value, traceback)
+        except Exception as err:
+            LOG.error("error in lifecycle hook stop, ignoring...", exc_info=err)

engin/ext/asgi.py

@@ -1,16 +1,16 @@
 import traceback
-import typing
-from typing import ClassVar, Protocol, TypeAlias
+from collections.abc import Awaitable, Callable, MutableMapping
+from typing import Any, ClassVar, Protocol, TypeAlias
 
 from engin import Engin, Option
 
 __all__ = ["ASGIEngin", "ASGIType"]
 
 
-_Scope: TypeAlias = typing.MutableMapping[str, typing.Any]
-_Message: TypeAlias = typing.MutableMapping[str, typing.Any]
-_Receive: TypeAlias = typing.Callable[[], typing.Awaitable[_Message]]
-_Send: TypeAlias = typing.Callable[[_Message], typing.Awaitable[None]]
+_Scope: TypeAlias = MutableMapping[str, Any]
+_Message: TypeAlias = MutableMapping[str, Any]
+_Receive: TypeAlias = Callable[[], Awaitable[_Message]]
+_Send: TypeAlias = Callable[[_Message], Awaitable[None]]
 
 
 class ASGIType(Protocol):
@@ -54,5 +54,5 @@ class _Rereceive:
     def __init__(self, message: _Message) -> None:
         self._message = message
 
-    async def __call__(self, *args, **kwargs) -> _Message:
+    async def __call__(self, *args: Any, **kwargs: Any) -> _Message:
         return self._message

engin/ext/fastapi.py

@@ -1,4 +1,3 @@
-import typing
 from typing import ClassVar, TypeVar
 
 from engin import Engin, Invoke, Option
@@ -8,13 +7,10 @@ try:
     from fastapi import FastAPI
     from fastapi.params import Depends
     from starlette.requests import HTTPConnection
-except ImportError:
-    raise ImportError("fastapi must be installed to use the corresponding extension")
-
-
-if typing.TYPE_CHECKING:
-    from fastapi import FastAPI
-    from fastapi.params import Depends
+except ImportError as err:
+    raise ImportError(
+        "fastapi package must be installed to use the fastapi extension"
+    ) from err
 
 __all__ = ["FastAPIEngin", "Inject"]
 
@@ -27,7 +23,7 @@ def _attach_engin(
 
 
 class FastAPIEngin(ASGIEngin):
-    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]  # type: ignore[arg-type]
+    _LIB_OPTIONS: ClassVar[list[Option]] = [*ASGIEngin._LIB_OPTIONS, Invoke(_attach_engin)]
     _asgi_type = FastAPI
 
 

engin-0.0.4.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: engin
+Version: 0.0.4
+Summary: An async-first modular application framework
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Engin 🏎️
+
+Engin is a zero-dependency application framework for modern Python.
+
+**Documentation**: https://engin.readthedocs.io/
+
+## Features ✨
+
+- **Dependency Injection** - Engin includes a fully-featured Dependency Injection system,
+  powered by type hints.
+- **Lifecycle Management** - Engin provides a simple & portable approach for attaching
+  startup and shutdown tasks to the application's lifecycle.
+- **Code Reuse** - Engin's modular components, called Blocks, work great as distributed
+  packages allowing zero boiler-plate code reuse across multiple applications. Perfect for
+  maintaining many services across your organisation.
+- **Ecosystem Compatability** - Engin ships with integrations for popular frameworks that
+  provide their own Dependency Injection, for example FastAPI, allowing you to integrate
+  Engin into existing code bases incrementally.
+- **Async Native**: Engin is an async framework, meaning first class support for async
+  dependencies. However Engin will happily run synchronous code as well.
+
+## Installation
+
+Engin is available on PyPI, install using your favourite dependency manager:
+
+- **pip**:`pip install engin`
+- **poetry**: `poetry add engin`
+- **uv**: `uv add engin`
+
+## Getting Started
+
+A minimal example:
+
+```python
+import asyncio
+
+from httpx import AsyncClient
+
+from engin import Engin, Invoke, Provide
+
+
+def httpx_client() -> AsyncClient:
+    return AsyncClient()
+
+
+async def main(http_client: AsyncClient) -> None:
+    print(await http_client.get("https://httpbin.org/get"))
+
+engin = Engin(Provide(httpx_client), Invoke(main))
+
+asyncio.run(engin.run())
+```
+

engin-0.0.4.dist-info/RECORD

@@ -0,0 +1,16 @@
+engin/__init__.py,sha256=AIE9wnwvfXwS1mwp6Sa9xtatBYyYzhWa36GKfAkEx_M,508
+engin/_assembler.py,sha256=UY97tXdHgvRi_iph_kolXZ8YTrxRjHKoIc4tAhqYOcw,5258
+engin/_block.py,sha256=Sdl9o3ZmmplZgB6pWFCbKjMemWzJXUso63p_bUg6BtM,1152
+engin/_dependency.py,sha256=G0ooXhYVauWiZ2keisot8iQXjGwdAwyvpwMtE1rjQzw,4754
+engin/_engin.py,sha256=tkW-QP-CNwKH9tr3xIZh-uvBKgyn9MrSvXjn3xLp7VU,6833
+engin/_exceptions.py,sha256=nkzTqxrW5nkcNgFDGoZ2TBtnHtO2RLk0qghM5LNAEmU,542
+engin/_lifecycle.py,sha256=LrDTrxEW6Mo0U4Nol9Rq-49Bi0UCa-7pbSCYjuSmG50,1211
+engin/_type_utils.py,sha256=naEk-lknC3Fdsd4jiP4YZAxjX3KXZN0MhFde9EV-Fmo,1835
+engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/ext/asgi.py,sha256=6vuC4zIhsvAdmwRn2I6uuUWPYfqobox1dv7skg2OWwE,1940
+engin/ext/fastapi.py,sha256=CH2Zi7Oh_Va0TJGx05e7_LqAiCsoI1qcu0Z59_rgfRk,899
+engin-0.0.4.dist-info/METADATA,sha256=CMTjhIBzTSn-PYAAnV6wAVpr-32GqV_BVUg-uQgsKVY,1806
+engin-0.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+engin-0.0.4.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.4.dist-info/RECORD,,

engin-0.0.2.dist-info/METADATA

@@ -1,56 +0,0 @@
-Metadata-Version: 2.4
-Name: engin
-Version: 0.0.2
-Summary: An async-first modular application framework
-License-File: LICENSE
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# Engin 🏎️
-
-Engin is a zero-dependency application framework for modern Python.
-
-## Features ✨
-
-- **Lightweight**: Engin has no dependencies.
-- **Async First**: Engin provides first-class support for applications. 
-- **Dependency Injection**: Engin promotes a modular decoupled architecture in your application.
-- **Lifecycle Management**: Engin provides an simple, portable approach for implememting
-  startup and shutdown tasks.
-- **Ecosystem Compatability**: seamlessly integrate with frameworks such as FastAPI without
-  having to migrate your dependencies.
-- **Code Reuse**: Engin's modular components work great as packages and distributions. Allowing
-  low boiler-plate code reuse within your Organisation.
-
-## Installation
-
-Engin is available on PyPI, install using your favourite dependency manager:
-
-- **pip**:`pip install engin`
-- **poetry**: `poetry add engin`
-- **uv**: `uv add engin`
-
-## Getting Started
-
-A minimal example:
-
-```python
-import asyncio
-
-from httpx import AsyncClient
-
-from engin import Engin, Invoke, Provide
-
-
-def httpx_client() -> AsyncClient:
-    return AsyncClient()
-
-
-async def main(http_client: AsyncClient) -> None:
-    print(await http_client.get("https://httpbin.org/get"))
-
-engin = Engin(Provide(httpx_client), Invoke(main))
-
-asyncio.run(engin.run())
-```
-

engin-0.0.2.dist-info/RECORD

@@ -1,16 +0,0 @@
-engin/__init__.py,sha256=AIE9wnwvfXwS1mwp6Sa9xtatBYyYzhWa36GKfAkEx_M,508
-engin/_assembler.py,sha256=Py159y4HvI54QuDcmbjL2kfXtbucYDE2KFBOgoC4qCM,5243
-engin/_block.py,sha256=XrGMFEeps_rvOGsYTlsefUkJGAY6jqdp71G8jE9FbwU,1109
-engin/_dependency.py,sha256=cL1qQFKDt7Rgg7mx8IXVkCZlUigg5cvhPFF9g2LNrgg,4749
-engin/_engin.py,sha256=KHjtncm0bG_N4sAFt7haxUBMeuLp0zP8Bxpftp7Zgy8,3109
-engin/_exceptions.py,sha256=nkzTqxrW5nkcNgFDGoZ2TBtnHtO2RLk0qghM5LNAEmU,542
-engin/_lifecycle.py,sha256=0hk24fiwaBos5kaZrnG_Qm0VmUhWKnGtwYCjc007XDk,729
-engin/_type_utils.py,sha256=naEk-lknC3Fdsd4jiP4YZAxjX3KXZN0MhFde9EV-Fmo,1835
-engin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-engin/ext/asgi.py,sha256=7viV6YgEwa0KatypDUrEYZT3YIQ3URQbzfVTGG7OuZE,1931
-engin/ext/fastapi.py,sha256=vf7eB5no6eVuZyYdJZdvDYZmjJAmoKbrKhskgiSWg5g,1005
-engin-0.0.2.dist-info/METADATA,sha256=CxEA114Eb2DF_voKUqPITeZiU1KWfSZaqvzIVNXaUAw,1491
-engin-0.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-engin-0.0.2.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
-engin-0.0.2.dist-info/RECORD,,