engin 0.0.dev1__py3-none-any.whl

engin/__init__.py

@@ -0,0 +1,21 @@
+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._exceptions import AssemblyError
+from engin._lifecycle import Lifecycle
+
+__all__ = [
+    "Assembler",
+    "AssemblyError",
+    "Engin",
+    "Entrypoint",
+    "Invoke",
+    "Lifecycle",
+    "Block",
+    "Option",
+    "Provide",
+    "Supply",
+    "invoke",
+    "provide",
+]

engin/_assembler.py

@@ -0,0 +1,126 @@
+import asyncio
+import logging
+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 engin._dependency import Dependency, Provide, Supply
+from engin._exceptions import AssemblyError
+from engin._type_utils import TypeId, type_id_of
+
+LOG = logging.getLogger("engin")
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class AssembledDependency(Generic[T]):
+    dependency: Dependency[Any, T]
+    bound_args: BoundArguments
+
+    async def __call__(self) -> T:
+        return await self.dependency(*self.bound_args.args, **self.bound_args.kwargs)
+
+
+class Assembler:
+    def __init__(self, providers: Iterable[Provide]) -> None:
+        self._providers: dict[TypeId, Provide[Any]] = {}
+        self._multiproviders: dict[TypeId, list[Provide[list[Any]]]] = defaultdict(list)
+        self._dependencies: dict[TypeId, Any] = {}
+        self._consumed_providers: set[Provide[Any]] = set()
+        self._lock = asyncio.Lock()
+
+        for provider in providers:
+            type_id = provider.return_type_id
+            if not provider.is_multiprovider:
+                if type_id in self._providers:
+                    raise RuntimeError(f"A Provider already exists for '{type_id}'")
+                self._providers[type_id] = provider
+            else:
+                self._multiproviders[type_id].append(provider)
+
+    def _resolve_providers(self, type_id: TypeId) -> Collection[Provide]:
+        if type_id.multi:
+            providers = self._multiproviders.get(type_id)
+        else:
+            providers = [provider] if (provider := self._providers.get(type_id)) else None
+        if not providers:
+            if type_id.multi:
+                LOG.warning(f"no provider for '{type_id}' defaulting to empty list")
+                providers = [(Supply([], type_hint=list[type_id.type]))]
+            else:
+                raise LookupError(f"No Provider registered for dependency '{type_id}'")
+
+        required_providers: list[Provide[Any]] = []
+        for provider in providers:
+            required_providers.extend(
+                provider
+                for provider_param in provider.parameter_types
+                for provider in self._resolve_providers(provider_param)
+            )
+
+        return {*required_providers, *providers}
+
+    async def _satisfy(self, target: TypeId) -> None:
+        for provider in self._resolve_providers(target):
+            if provider in self._consumed_providers:
+                continue
+            self._consumed_providers.add(provider)
+            type_id = provider.return_type_id
+            bound_args = await self._bind_arguments(provider.signature)
+            try:
+                value = await provider(*bound_args.args, **bound_args.kwargs)
+            except Exception as err:
+                raise AssemblyError(
+                    provider=provider, error_type=type(err), error_message=str(err)
+                ) from err
+            if provider.is_multiprovider:
+                if type_id in self._dependencies:
+                    self._dependencies[type_id].extend(value)
+                else:
+                    self._dependencies[type_id] = value
+            else:
+                self._dependencies[type_id] = value
+
+    async def _bind_arguments(self, signature: Signature) -> BoundArguments:
+        args = []
+        kwargs = {}
+        for param_name, param in signature.parameters.items():
+            if param_name == "self":
+                args.append(object())
+                continue
+            param_key = type_id_of(param.annotation)
+            has_dependency = param_key in self._dependencies
+            if not has_dependency:
+                await self._satisfy(param_key)
+            val = self._dependencies[param_key]
+            if param.kind == param.POSITIONAL_ONLY:
+                args.append(val)
+            else:
+                kwargs[param.name] = val
+
+        return signature.bind(*args, **kwargs)
+
+    async def assemble(self, dependency: Dependency[Any, T]) -> AssembledDependency[T]:
+        async with self._lock:
+            return AssembledDependency(
+                dependency=dependency,
+                bound_args=await self._bind_arguments(dependency.signature),
+            )
+
+    async def get(self, type_: type[T]) -> T:
+        type_id = type_id_of(type_)
+        if type_id.multi:
+            out = []
+            for provider in self._multiproviders[type_id]:
+                assembled_dependency = await self.assemble(provider)
+                out.extend(await assembled_dependency())
+            return out
+        else:
+            assembled_dependency = await self.assemble(self._providers[type_id])
+            return await assembled_dependency()
+
+    def has(self, type_: type[T]) -> bool:
+        return type_id_of(type_) in self._providers

engin/_block.py

@@ -0,0 +1,36 @@
+import inspect
+from collections.abc import Iterable, Iterator
+
+from engin._dependency import Func, Invoke, Provide
+
+
+def provide(func: Func) -> Func:
+    func._opt = Provide(func)  # type: ignore[union-attr]
+    return func
+
+
+def invoke(func: Func) -> Func:
+    func._opt = Invoke(func)  # type: ignore[union-attr]
+    return func
+
+
+class Block(Iterable[Provide | Invoke]):
+    _name: str
+    _options: list[Provide | Invoke]
+
+    def __init__(self, /, block_name: str | None = None) -> None:
+        self._options: list[Provide | Invoke] = []
+        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)):
+                    raise RuntimeError("Block option is not an instance of Provide or Invoke")
+                opt.set_block_name(self._name)
+                self._options.append(opt)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def __iter__(self) -> Iterator[Provide | Invoke]:
+        return iter(self._options)

engin/_dependency.py

@@ -0,0 +1,162 @@
+import inspect
+import typing
+from abc import ABC
+from inspect import Parameter, Signature, isclass, iscoroutinefunction
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    ParamSpec,
+    Type,
+    TypeAlias,
+    TypeVar,
+    cast,
+    get_type_hints,
+)
+
+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]]
+)
+_SELF = object()
+
+
+def _noop(*args, **kwargs) -> None: ...
+
+
+class Dependency(ABC, Generic[P, T]):
+    def __init__(self, func: Func[P, T], block_name: str | None = None) -> None:
+        self._func = func
+        self._is_async = iscoroutinefunction(func)
+        self._signature = inspect.signature(self._func)
+        self._block_name = block_name
+
+    @property
+    def block_name(self) -> str | None:
+        return self._block_name
+
+    @property
+    def name(self) -> str:
+        if self._block_name:
+            return f"{self._block_name}.{self._func.__name__}"
+        else:
+            return f"{self._func.__module__}.{self._func.__name__}"
+
+    @property
+    def parameter_types(self) -> list[TypeId]:
+        parameters = list(self._signature.parameters.values())
+        if not parameters:
+            return []
+        if parameters[0].name == "self":
+            parameters.pop(0)
+        return [type_id_of(param.annotation) for param in parameters]
+
+    @property
+    def signature(self) -> Signature:
+        return self._signature
+
+    def set_block_name(self, name: str) -> None:
+        self._block_name = name
+
+    async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+        if self._is_async:
+            return await cast(Awaitable[T], self._func(*args, **kwargs))
+        else:
+            return cast(T, self._func(*args, **kwargs))
+
+
+class Invoke(Dependency):
+    def __init__(self, invocation: Func[P, T], block_name: str | None = None):
+        super().__init__(func=invocation, block_name=block_name)
+
+    def __str__(self) -> str:
+        return f"Invoke({self.name})"
+
+
+class Entrypoint(Invoke):
+    def __init__(self, type_: Type[Any], *, block_name: str | None = None) -> None:
+        self._type = type_
+        super().__init__(invocation=_noop, block_name=block_name)
+
+    @property
+    def parameter_types(self) -> list[TypeId]:
+        return [type_id_of(self._type)]
+
+    @property
+    def signature(self) -> Signature:
+        return Signature(
+            parameters=[
+                Parameter(name="x", kind=Parameter.POSITIONAL_ONLY, annotation=self._type)
+            ]
+        )
+
+    def __str__(self) -> str:
+        return f"Entrypoint({type_id_of(self._type)})"
+
+
+class Provide(Dependency[Any, T]):
+    def __init__(self, builder: Func[P, T], block_name: str | None = None):
+        super().__init__(func=builder, block_name=block_name)
+        self._is_multi = typing.get_origin(self.return_type) is list
+
+        if self._is_multi:
+            args = typing.get_args(self.return_type)
+            if len(args) != 1:
+                raise ValueError(
+                    f"A multiprovider must be of the form list[X], not '{self.return_type}'"
+                )
+
+    @property
+    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")
+
+        return return_type
+
+    @property
+    def return_type_id(self) -> TypeId:
+        return type_id_of(self.return_type)
+
+    @property
+    def is_multiprovider(self) -> bool:
+        return self._is_multi
+
+    def __hash__(self) -> int:
+        return hash(self.return_type_id)
+
+    def __str__(self) -> str:
+        return f"Provide({self.return_type_id})"
+
+
+class Supply(Provide, Generic[T]):
+    def __init__(
+        self, value: T, *, type_hint: type | None = None, block_name: str | None = None
+    ):
+        self._value = value
+        self._type_hint = type_hint
+        if self._type_hint is not None:
+            self._get_val.__annotations__["return"] = type_hint
+        super().__init__(builder=self._get_val, block_name=block_name)
+
+    @property
+    def return_type(self) -> Type[T]:
+        if self._type_hint is not None:
+            return self._type_hint
+        if isinstance(self._value, list):
+            return list[type(self._value[0])]  # type: ignore[misc,return-value]
+        return type(self._value)
+
+    def _get_val(self) -> T:
+        return self._value
+
+    def __str__(self) -> str:
+        return f"Supply({self.return_type_id})"

engin/_engin.py

@@ -0,0 +1,89 @@
+import logging
+from asyncio import Event
+from collections.abc import Iterable
+from itertools import chain
+from typing import ClassVar, TypeAlias
+
+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._lifecycle import Lifecycle
+from engin._type_utils import TypeId
+
+LOG = logging.getLogger("engin")
+
+Option: TypeAlias = Invoke | Provide | Supply | Block
+_Opt: TypeAlias = Invoke | Provide | Supply
+
+
+class Engin:
+    _LIB_OPTIONS: ClassVar[list[Option]] = [Provide(Lifecycle)]
+
+    def __init__(self, *options: Option) -> None:
+        self._providers: dict[TypeId, Provide] = {}
+        self._invokables: list[Invoke] = []
+        self._stop_event = Event()
+
+        self._destruct_options(chain(self._LIB_OPTIONS, options))
+        self._assembler = Assembler(self._providers.values())
+
+    @property
+    def assembler(self) -> Assembler:
+        return self._assembler
+
+    async def run(self):
+        await self.start()
+
+        # lifecycle startup
+
+        # wait till stop signal recieved
+        await self._stop_event.wait()
+
+        # lifecycle shutdown
+
+    async def start(self) -> None:
+        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()
+
+        lifecycle = await self._assembler.get(Lifecycle)
+        await lifecycle.startup()
+        self._stop_event = Event()
+        LOG.info("startup complete")
+
+    async def stop(self) -> None:
+        self._stop_event.set()
+
+    def _destruct_options(self, options: Iterable[Option]):
+        for opt in options:
+            if isinstance(opt, Block):
+                self._destruct_options(opt)
+            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
+            elif isinstance(opt, Invoke):
+                self._log_option(opt)
+                self._invokables.append(opt)
+
+    @staticmethod
+    def _log_option(opt: Dependency, overwrites: Dependency | None = None) -> None:
+        if overwrites is not None:
+            extra = f"\tOVERWRITES {overwrites.name}"
+            if overwrites.block_name:
+                extra += f" [{overwrites.block_name}]"
+        else:
+            extra = ""
+        if isinstance(opt, Supply):
+            LOG.debug(f"SUPPLY      {opt.return_type_id!s:<35}{extra}")
+        elif isinstance(opt, Provide):
+            LOG.debug(f"PROVIDE     {opt.return_type_id!s:<35} <- {opt.name}() {extra}")
+        elif isinstance(opt, Entrypoint):
+            type_id = opt.parameter_types[0]
+            LOG.debug(f"ENTRYPOINT  {type_id!s:<35}")
+        elif isinstance(opt, Invoke):
+            LOG.debug(f"INVOKE      {opt.name:<35}")

engin/_exceptions.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from engin._dependency import Provide
+
+
+class AssemblyError(Exception):
+    def __init__(
+        self, provider: Provide[Any], error_type: type[Exception], error_message: str
+    ) -> None:
+        self.provider = provider
+        self.error_type = error_type
+        self.error_message = error_message
+        self.message = (
+            f"provider '{provider.name}' errored with error "
+            f"({error_type.__name__}): '{error_message}'"
+        )
+
+    def __str__(self) -> str:
+        return self.message

engin/_lifecycle.py

@@ -0,0 +1,21 @@
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager, AsyncExitStack
+
+
+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)
+
+    async def startup(self) -> None:
+        self._stack = AsyncExitStack()
+        for cm in self._context_managers:
+            await self._stack.enter_async_context(cm)
+
+    async def shutdown(self) -> None:
+        await self._stack.aclose()

engin/_type_utils.py

@@ -0,0 +1,65 @@
+import typing
+from dataclasses import dataclass
+from typing import Any
+
+_implict_modules = ["builtins", "typing", "collections.abc"]
+
+
+@dataclass(frozen=True, eq=True)
+class TypeId:
+    type: type
+    multi: bool
+
+    @classmethod
+    def from_type(cls, type_: Any) -> "TypeId":
+        if is_multi_type(type_):
+            inner_obj = typing.get_args(type_)[0]
+            return TypeId(type=inner_obj, multi=True)
+        else:
+            return TypeId(type=type_, multi=False)
+
+    def __str__(self) -> str:
+        module = self.type.__module__
+        out = f"{module}." if module not in _implict_modules else ""
+        out += _args_to_str(self.type)
+        if self.multi:
+            out += "[]"
+        return out
+
+
+def _args_to_str(type_: Any) -> str:
+    args = typing.get_args(type_)
+    if args:
+        arg_str = f"{type_.__name__}["
+        for idx, arg in enumerate(args):
+            if isinstance(arg, list):
+                arg_str += "["
+                for inner_idx, inner_arg in enumerate(arg):
+                    arg_str += _args_to_str(inner_arg)
+                    if inner_idx < len(arg) - 1:
+                        arg_str += ", "
+                arg_str += "]"
+            elif typing.get_args(arg):
+                arg_str += _args_to_str(arg)
+            else:
+                arg_str += getattr(arg, "__name__", str(arg))
+            if idx < len(args) - 1:
+                arg_str += ", "
+        arg_str += "]"
+    else:
+        arg_str = type_.__name__
+    return arg_str
+
+
+def type_id_of(type_: Any) -> TypeId:
+    """
+    Generates a string TypeId for any type.
+    """
+    return TypeId.from_type(type_)
+
+
+def is_multi_type(type_: Any) -> bool:
+    """
+    Discriminates a type to determine whether it is the return type of a multiprovider.
+    """
+    return typing.get_origin(type_) is list

engin/extensions/asgi.py

@@ -0,0 +1,55 @@
+import traceback
+import typing
+from typing import 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]]
+
+
+class ASGIType(Protocol):
+    async def __call__(self, scope: _Scope, receive: _Receive, send: _Send) -> None: ...
+
+
+class ASGIEngin(Engin, ASGIType):
+    _asgi_app: ASGIType
+
+    def __init__(self, *options: Option) -> None:
+        super().__init__(*options)
+
+        if not self._assembler.has(ASGIType):
+            raise LookupError("A provider for `ASGIType` was expected, none found")
+
+    async def __call__(self, scope: _Scope, receive: _Receive, send: _Send) -> None:
+        if scope["type"] == "lifespan":
+            message = await receive()
+            receive = _Rereceive(message)
+            if message["type"] == "lifespan.startup":
+                try:
+                    await self._startup()
+                except Exception as err:
+                    exc = "".join(traceback.format_exception(err))
+                    await send({"type": "lifespan.startup.failed", "message": exc})
+
+            elif message["type"] == "lifespan.shutdown":
+                await self.stop()
+
+        await self._asgi_app(scope, receive, send)
+
+    async def _startup(self) -> None:
+        await self.start()
+        self._asgi_app = await self._assembler.get(ASGIType)
+
+
+class _Rereceive:
+    def __init__(self, message: _Message) -> None:
+        self._message = message
+
+    async def __call__(self, *args, **kwargs) -> _Message:
+        return self._message

engin-0.0.dev1.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.3
+Name: engin
+Version: 0.0.dev1
+Summary: An async-first modular application framework
+License-File: LICENSE
+Requires-Python: >=3.10

engin-0.0.dev1.dist-info/RECORD

@@ -0,0 +1,15 @@
+engin/__init__.py,sha256=T2tv-pdULMTp-p0PhB_XYmr9CEWOmMzcu0jebZx7-2Q,475
+engin/_assembler.py,sha256=HPnrTGk6XbO-iG3BZfD65zzOxWC4C1yWOZf7Vv3MMKk,4944
+engin/_block.py,sha256=XrGMFEeps_rvOGsYTlsefUkJGAY6jqdp71G8jE9FbwU,1109
+engin/_dependency.py,sha256=cL1qQFKDt7Rgg7mx8IXVkCZlUigg5cvhPFF9g2LNrgg,4749
+engin/_engin.py,sha256=Sg7sxESuwzTXx-4xgFv869YkpBRxE9d-kjIOTOTtcxU,3071
+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/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+engin/extensions/asgi.py,sha256=EHQhevGJt3UJZp_7Y7AIuYVm-bYUO-seuzE3kMuOJWM,1775
+engin-0.0.dev1.dist-info/METADATA,sha256=263kjboSCI7Th0GHl7bbpF5cCHAKsB51_56v5xcJThk,152
+engin-0.0.dev1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+engin-0.0.dev1.dist-info/licenses/LICENSE,sha256=XHh5LPUPKZWTBqBv2xxN2RU7D59nHoiJGb5RIt8f45w,1070
+engin-0.0.dev1.dist-info/RECORD,,

engin-0.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

engin-0.0.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tim OSullivan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.