engin 0.2.0a1__tar.gz → 0.2.1__tar.gz

{engin-0.2.0a1 → engin-0.2.1}/PKG-INFO

@@ -1,20 +1,20 @@
 Metadata-Version: 2.4
 Name: engin
-Version: 0.2.0a1
-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
+Version: 0.2.1
+Summary: A dependency-injection powered application framework
+Keywords: Dependency Injection,Application Framework
 License-Expression: MIT
-License-File: LICENSE
-Keywords: Application Framework,Dependency Injection
-Requires-Python: >=3.10
 Requires-Dist: anyio>=4
 Requires-Dist: exceptiongroup>=1
+Requires-Dist: typing-extensions>=4
+Requires-Dist: typer>=0.15 ; extra == 'cli'
+Requires-Dist: tomli>=2.0 ; python_full_version < '3.11' and extra == 'cli'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/invokermain/engin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://engin.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/invokermain/engin
+Project-URL: Repository, https://github.com/invokermain/engin.git
 Provides-Extra: cli
-Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
-Requires-Dist: typer>=0.15; extra == 'cli'
 Description-Content-Type: text/markdown
 
 # Engin 🏎️
@@ -29,11 +29,11 @@ Description-Content-Type: text/markdown
 
 ---
 
-Engin is a lightweight application framework powered by dependency injection, it helps
-you build and maintain large monoliths and many microservices.
+Engin is a lightweight application framework powered by dependency injection. It helps
+you build and maintain everything from large monoliths to hundreds of microservices.
 
 
-## Feature
+## Features
 
 The Engin framework gives you:
 
@@ -120,3 +120,8 @@ Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/ube
 and the [Injector framework for Python](https://github.com/python-injector/injector).
 
 They are both great projects, go check them out.
+
+## Benchmarks
+
+Automated benchmarks for the Engin framework can be viewed
+[here](https://invokermain.github.io/engin/dev/bench/).

{engin-0.2.0a1 → engin-0.2.1}/README.md

@@ -10,11 +10,11 @@
 
 ---
 
-Engin is a lightweight application framework powered by dependency injection, it helps
-you build and maintain large monoliths and many microservices.
+Engin is a lightweight application framework powered by dependency injection. It helps
+you build and maintain everything from large monoliths to hundreds of microservices.
 
 
-## Feature
+## Features
 
 The Engin framework gives you:
 
@@ -101,3 +101,8 @@ Engin is heavily inspired by [Uber's Fx framework for Go](https://github.com/ube
 and the [Injector framework for Python](https://github.com/python-injector/injector).
 
 They are both great projects, go check them out.
+
+## Benchmarks
+
+Automated benchmarks for the Engin framework can be viewed
+[here](https://invokermain.github.io/engin/dev/bench/).

{engin-0.2.0a1 → engin-0.2.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "engin"
-version = "0.2.0a1"
-description = "An async-first modular application framework"
+version = "0.2.1"
+description = "A dependency-injection powered application framework"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
@@ -10,6 +10,7 @@ dependencies = [
     "anyio>=4",
     # backwards compatability for exception group in 3.10
     "exceptiongroup>=1",
+    "typing-extensions>=4",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +45,7 @@ dev = [
     "pytest-benchmark>=5.1.0",
     "websockets>=15.0.1",
     "valkey>=6.1.0",
+    "tomli"
 ]
 docs = [
     "mkdocs-material>=9.5.50",
@@ -54,8 +56,8 @@ docs = [
 default-groups = ["dev", "docs"]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["uv_build"]
+build-backend = "uv_build"
 
 
 [tool.ruff]
@@ -106,6 +108,7 @@ exclude_lines = [
     "@overload",
     'class .*\bProtocol\b.*\):',
     "raise NotImplementedError",
+    "assert_never\\(",
 ]
 partial_branches = [
     "pragma: no branch",
@@ -119,6 +122,7 @@ partial_branches = [
 
 
 [tool.mypy]
+python_version = "3.10"
 strict = true
 disable_error_code = [
     "type-arg", # allow generic types without type arguments

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_assembler.py

@@ -8,6 +8,8 @@ from inspect import BoundArguments, Signature
 from types import TracebackType
 from typing import Any, Generic, TypeVar, cast
 
+from typing_extensions import Self
+
 from engin._dependency import Dependency, Provide, Supply
 from engin._type_utils import TypeId
 from engin.exceptions import NotInScopeError, ProviderError, TypeNotProvidedError
@@ -76,6 +78,34 @@ class Assembler:
             else:
                 self._multiproviders[type_id].append(provider)
 
+    @classmethod
+    def from_mapped_providers(
+        cls,
+        providers: dict[TypeId, Provide[Any]],
+        multiproviders: dict[TypeId, list[Provide[list[Any]]]],
+    ) -> Self:
+        """
+        Create an Assembler from pre-mapped providers.
+
+        This method is only exposed for performance reasons in the case that Providers
+        have already been mapped, it is recommended to use the `__init__` method if this
+        is no the case.
+
+        Args:
+            providers: a dictionary of Providers with the Provider's `return_type_id` as
+              the key.
+            multiproviders: a dictionary of list of Providers with the Provider's
+              `return_type_id` as key. All Providers in the given list must be for the
+              related `return_type_id`.
+
+        Returns:
+            An Assembler instance.
+        """
+        assembler = cls(tuple())  # noqa: C408
+        assembler._providers = providers
+        assembler._multiproviders = multiproviders
+        return assembler
+
     @property
     def providers(self) -> Sequence[Provide[Any]]:
         multi_providers = [p for multi in self._multiproviders.values() for p in multi]

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_block.py

@@ -10,6 +10,8 @@ from engin.exceptions import InvalidBlockError
 if TYPE_CHECKING:
     from engin._engin import Engin
 
+_BUILTIN_CLASS_FUNCTIONS = ("__annotate_func__",)
+
 
 def provide(
     func_: Func | None = None, *, scope: str | None = None, override: bool = False
@@ -84,6 +86,8 @@ class Block:
     @classmethod
     def _method_options(cls) -> Iterable[Provide | Invoke]:
         for name, method in inspect.getmembers(cls, inspect.isfunction):
+            if name in _BUILTIN_CLASS_FUNCTIONS:
+                continue
             if option := getattr(method, "_opt", None):
                 if not isinstance(option, Provide | Invoke):
                     raise InvalidBlockError(

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_cli/_common.py

@@ -1,11 +1,11 @@
 import importlib
 import sys
 from pathlib import Path
-from typing import Never
 
 import typer
 from rich import print
 from rich.panel import Panel
+from typing_extensions import Never
 
 from engin import Engin
 

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_dependency.py

@@ -184,7 +184,9 @@ class Provide(Dependency[Any, T]):
         if self._explicit_type is not None:
             self._signature = self._signature.replace(return_annotation=self._explicit_type)
 
-        self._is_multi = typing.get_origin(self._return_type) is list
+        self._is_multi = (
+            typing.get_origin(self._return_type) is list or self._return_type is list
+        )
 
         # Validate that the provider does to depend on its own output value, as this will
         # cause a recursion error and is undefined behaviour wise.
@@ -198,9 +200,11 @@ class Provide(Dependency[Any, T]):
         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}'"
+                msg = (
+                    "A multiprovider must be of the form list[X], not "
+                    f"'{self._return_type_id}'"
                 )
+                raise ValueError(msg)
 
     @property
     def return_type(self) -> type[T]:

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_engin.py

@@ -1,14 +1,14 @@
 import asyncio
 import logging
-import os
 import signal
+import sys
 from asyncio import Event
 from collections import defaultdict
 from contextlib import AsyncExitStack
 from enum import Enum
 from itertools import chain
 from types import FrameType
-from typing import ClassVar
+from typing import TYPE_CHECKING, ClassVar
 
 from anyio import create_task_group, open_signal_receiver
 
@@ -18,10 +18,12 @@ from engin._graph import DependencyGrapher, Node
 from engin._lifecycle import Lifecycle
 from engin._option import Option
 from engin._supervisor import Supervisor
-from engin._type_utils import TypeId
 from engin.exceptions import EnginError
 
-_OS_IS_WINDOWS = os.name == "nt"
+if TYPE_CHECKING:
+    from engin._type_utils import TypeId
+
+_OS_IS_WINDOWS = sys.platform == "win32"
 LOG = logging.getLogger("engin")
 
 
@@ -107,12 +109,9 @@ class Engin:
         self._stop_requested_event = Event()
         self._stop_complete_event = Event()
         self._exit_stack = AsyncExitStack()
-        self._assembler = Assembler([])
         self._async_context_run_task: asyncio.Task | None = None
 
-        self._providers: dict[TypeId, Provide] = {
-            TypeId.from_type(Assembler): Supply(self._assembler),
-        }
+        self._providers: dict[TypeId, Provide] = {}
         self._multiproviders: dict[TypeId, list[Provide]] = defaultdict(list)
         self._invocations: list[Invoke] = []
 
@@ -120,10 +119,12 @@ class Engin:
         for option in chain(self._LIB_OPTIONS, options):
             option.apply(self)
 
-        multi_providers = [p for multi in self._multiproviders.values() for p in multi]
-
-        for provider in chain(self._providers.values(), multi_providers):
-            self._assembler.add(provider)
+        # initialise Assembler
+        self._assembler = Assembler.from_mapped_providers(
+            providers=self._providers,
+            multiproviders=self._multiproviders,
+        )
+        self._assembler.add(Supply(self._assembler))
 
     @property
     def assembler(self) -> Assembler:
@@ -253,29 +254,37 @@ class Engin:
 async def _stop_engin_on_signal(stop_requested_event: Event) -> None:
     """
     A task that waits for a stop signal (SIGINT/SIGTERM) and notifies the given event.
+
+    On unix-like systems we can use asyncio's `loop.add_signal_handler` method but this
+    does not work on Windows as `signal.set_wakeup_fd` is not supported.
+
+    Therefore on Windows we fallback to using `signal.signal` directly.
     """
     if not _OS_IS_WINDOWS:
-        with open_signal_receiver(signal.SIGINT, signal.SIGTERM) as recieved_signals:
-            async for signum in recieved_signals:
-                LOG.debug(f"received {signum.name} signal")
+        with open_signal_receiver(signal.SIGINT, signal.SIGTERM) as received_signals:
+            async for signum in received_signals:
+                LOG.debug(f"received signal: {signum.name}")
                 stop_requested_event.set()
+                break
     else:
-        should_stop = False
 
-        # windows does not support signal_handlers, so this is the workaround
         def ctrlc_handler(sig: int, frame: FrameType | None) -> None:
-            LOG.debug(f"received {signal.SIGINT.name} signal")
-            nonlocal should_stop
-            if should_stop:
+            LOG.debug(f"received signal: {signal.Signals(sig).name}")
+            if stop_requested_event.is_set():
                 raise KeyboardInterrupt("Forced keyboard interrupt")
-            should_stop = True
+            else:
+                stop_requested_event.set()
 
-        signal.signal(signal.SIGINT, ctrlc_handler)
+        previous_signal_handler_sigint = 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)
+        # technically not needed due to the _OS_IS_WINDOWS checks but keeps mypy happy
+        if hasattr(signal, "SIGBREAK"):
+            previous_signal_handler_sigbreak = signal.signal(signal.SIGBREAK, ctrlc_handler)
 
-        stop_requested_event.set()
+        try:
+            await stop_requested_event.wait()
+        finally:
+            # restore orginal signal handlers
+            signal.signal(signal.SIGINT, previous_signal_handler_sigint)
+            if hasattr(signal, "SIGBREAK"):
+                signal.signal(signal.SIGBREAK, previous_signal_handler_sigbreak)

{engin-0.2.0a1 → engin-0.2.1}/src/engin/_supervisor.py

@@ -5,10 +5,11 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
 from types import TracebackType
-from typing import TypeAlias, assert_never
+from typing import TypeAlias
 
 import anyio
 from anyio import get_cancelled_exc_class
+from typing_extensions import assert_never
 
 if typing.TYPE_CHECKING:
     from anyio.abc import TaskGroup

engin-0.2.0a1/.github/workflows/benchmark.yaml

@@ -1,41 +0,0 @@
-name: Benchmark Main
-
-on:
-  push:
-    branches: [main]
-
-env:
-  UV_FROZEN: "1"
-
-jobs:
-  benchmark-main:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: "pyproject.toml"
-
-      - name: Install the project
-        run: uv sync --dev
-
-      - name: Run benchmark
-        run: |
-          uv run pytest tests --benchmark-only --benchmark-json bench.json
-
-      - name: Store benchmark result
-        uses: benchmark-action/github-action-benchmark@v1
-        with:
-          tool: 'pytest'
-          output-file-path: bench.json
-          github-token: ${{ secrets.PAT }}
-          auto-push: true

engin-0.2.0a1/.github/workflows/check.yaml

@@ -1,49 +0,0 @@
-name: Check
-
-on:
-  push:
-
-env:
-  UV_FROZEN: "1"
-
-jobs:
-  check:
-    name: python
-
-    strategy:
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-
-    runs-on: ${{ matrix.os }}
-
-    permissions:
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: "pyproject.toml"
-
-      - name: Install the project
-        run: uv sync --all-extras --dev
-
-      - name: Quality
-        run: uv run poe check
-
-      - name: Test
-        run: uv run poe ci-test
-
-      - name: Upload coverage reports to Codecov
-        if: matrix.os == 'ubuntu-latest'
-        uses: codecov/codecov-action@v5
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}

engin-0.2.0a1/.github/workflows/publish.yaml

@@ -1,34 +0,0 @@
-name: Publish
-
-on:
-  workflow_dispatch:
-  release:
-    types: [created]
-
-jobs:
-  publish-to-pypi:
-    name: python
-    runs-on: ubuntu-latest
-
-    permissions:
-      id-token: write
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version-file: "pyproject.toml"
-
-      - name: Build the Project
-        run: uv build
-
-      - name: Publish
-        run: uv publish

engin-0.2.0a1/.gitignore

@@ -1,167 +0,0 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
-.pdm.toml
-.pdm-python
-.pdm-build/
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# Python local version specifier
-.python-version
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-.idea/
-
-scrap/**

engin-0.2.0a1/.readthedocs.yaml

@@ -1,25 +0,0 @@
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
-version: 2
-
-# Set the OS, Python version, and other tools you might need
-build:
-  os: ubuntu-24.04
-  tools:
-    python: "3.13"
-  jobs:
-    create_environment:
-       - asdf plugin add uv
-       - asdf install uv latest
-       - asdf global uv latest
-       - uv venv
-    install:
-       - uv sync --group docs
-    build:
-       html:
-          - NO_COLOR=1 uv run mkdocs build -f mkdocs.yaml --strict --site-dir $READTHEDOCS_OUTPUT/html
-
-mkdocs:
-  configuration: mkdocs.yaml