pydepi 0.1.0__tar.gz

pydepi-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: pydepi
+Version: 0.1.0
+Summary: A .NET-inspired, type-hint driven dependency injection container for Python
+Author: Dan Leonard
+License: MIT
+Project-URL: Homepage, https://github.com/danleonard-nj/depi
+Project-URL: Repository, https://github.com/danleonard-nj/depi
+Project-URL: Issues, https://github.com/danleonard-nj/depi/issues
+Keywords: dependency-injection,di,ioc,inversion-of-control,container
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: flask
+Requires-Dist: pydepi-flask; extra == "flask"
+Provides-Extra: quart
+Requires-Dist: pydepi-quart; extra == "quart"
+Provides-Extra: fastapi
+Requires-Dist: pydepi-fastapi; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: pydepi-django; extra == "django"
+Provides-Extra: all
+Requires-Dist: pydepi[django,fastapi,flask,quart]; extra == "all"
+
+# pydepi
+
+A .NET-inspired, type-hint driven dependency injection container for Python.
+
+`pydepi` resolves dependency graphs from constructor type annotations. It has **no dependencies** and knows nothing about the web — framework support ships as separate packages, so installing the container never drags a web framework into your environment.
+
+```bash
+pip install pydepi
+```
+
+```python
+from depi import ServiceCollection
+
+class Config:
+    def __init__(self):
+        self.dsn = 'postgres://localhost/app'
+
+class Database:
+    def __init__(self, config: Config):      # resolved from the annotation
+        self.dsn = config.dsn
+
+services = ServiceCollection()
+services.add_singleton(Config)
+services.add_scoped(Database)
+
+provider = services.build_provider()
+
+with provider.create_scope() as scope:
+    db = scope.resolve(Database)
+```
+
+## Lifetimes
+
+- **Transient** – a new instance on every resolution
+- **Singleton** – one instance for the life of the provider
+- **Scoped** – one instance per scope, typically per HTTP request
+
+Scopes dispose their instances on exit, and `async with` awaits async cleanup first.
+
+## Framework integrations
+
+Each is a separate distribution depending on this one:
+
+| Package          | Import         |
+| ---------------- | -------------- |
+| `pydepi-flask`   | `depi_flask`   |
+| `pydepi-quart`   | `depi_quart`   |
+| `pydepi-fastapi` | `depi_fastapi` |
+| `pydepi-django`  | `depi_django`  |
+
+Install one by name — `pip install pydepi-flask`. The extra `pydepi[flask]` works too, but the
+distribution name is the more accurate form: these are separate packages, versioned and released
+independently of core, not optional features of it.
+
+Full documentation, including the integration guide, factories, and the async API, is in the [project README](https://github.com/danleonard-nj/depi#readme).
+
+## License
+
+MIT

pydepi-0.1.0/README.md

@@ -0,0 +1,59 @@
+# pydepi
+
+A .NET-inspired, type-hint driven dependency injection container for Python.
+
+`pydepi` resolves dependency graphs from constructor type annotations. It has **no dependencies** and knows nothing about the web — framework support ships as separate packages, so installing the container never drags a web framework into your environment.
+
+```bash
+pip install pydepi
+```
+
+```python
+from depi import ServiceCollection
+
+class Config:
+    def __init__(self):
+        self.dsn = 'postgres://localhost/app'
+
+class Database:
+    def __init__(self, config: Config):      # resolved from the annotation
+        self.dsn = config.dsn
+
+services = ServiceCollection()
+services.add_singleton(Config)
+services.add_scoped(Database)
+
+provider = services.build_provider()
+
+with provider.create_scope() as scope:
+    db = scope.resolve(Database)
+```
+
+## Lifetimes
+
+- **Transient** – a new instance on every resolution
+- **Singleton** – one instance for the life of the provider
+- **Scoped** – one instance per scope, typically per HTTP request
+
+Scopes dispose their instances on exit, and `async with` awaits async cleanup first.
+
+## Framework integrations
+
+Each is a separate distribution depending on this one:
+
+| Package          | Import         |
+| ---------------- | -------------- |
+| `pydepi-flask`   | `depi_flask`   |
+| `pydepi-quart`   | `depi_quart`   |
+| `pydepi-fastapi` | `depi_fastapi` |
+| `pydepi-django`  | `depi_django`  |
+
+Install one by name — `pip install pydepi-flask`. The extra `pydepi[flask]` works too, but the
+distribution name is the more accurate form: these are separate packages, versioned and released
+independently of core, not optional features of it.
+
+Full documentation, including the integration guide, factories, and the async API, is in the [project README](https://github.com/danleonard-nj/depi#readme).
+
+## License
+
+MIT

pydepi-0.1.0/depi/__init__.py

@@ -0,0 +1,72 @@
+"""
+depi - a type-hint driven dependency injection container for Python.
+
+Core is dependency-free and framework-agnostic. Web framework support ships as
+separate distributions, each with its own top-level module, so importing
+``depi`` never pulls in a web framework:
+
+    pip install pydepi[flask]        # or: pip install pydepi-flask
+
+    from depi_flask import FlaskInjector
+
+Adapters build on :mod:`depi.context` and :mod:`depi.integration`.
+"""
+
+from .context import (
+    current_scope,
+    get_current_scope,
+    reset_current_scope,
+    set_current_scope,
+    use_scope,
+)
+from .exceptions import (
+    AsyncFactoryError,
+    CircularDependencyError,
+    DepiError,
+    InvalidLifetimeError,
+    MissingAnnotationError,
+    NoActiveScopeError,
+    RegistrationError,
+    ResolutionError,
+    ScopeRequiredError,
+    UnknownLifetimeError,
+    UnregisteredDependencyError,
+)
+from .services import (
+    ConstructorDependency,
+    DependencyRegistration,
+    Lifetime,
+    ServiceCollection,
+    ServiceProvider,
+    ServiceScope,
+)
+
+__all__ = [
+    # Container
+    'ServiceCollection',
+    'ServiceProvider',
+    'ServiceScope',
+    'Lifetime',
+    'ConstructorDependency',
+    'DependencyRegistration',
+
+    # Ambient scope
+    'current_scope',
+    'get_current_scope',
+    'set_current_scope',
+    'reset_current_scope',
+    'use_scope',
+
+    # Errors
+    'DepiError',
+    'RegistrationError',
+    'MissingAnnotationError',
+    'CircularDependencyError',
+    'InvalidLifetimeError',
+    'UnknownLifetimeError',
+    'ResolutionError',
+    'UnregisteredDependencyError',
+    'ScopeRequiredError',
+    'AsyncFactoryError',
+    'NoActiveScopeError',
+]

pydepi-0.1.0/depi/context.py

@@ -0,0 +1,91 @@
+"""
+Ambient scope tracking.
+
+Framework integrations bind a :class:`~depi.services.ServiceScope` to the
+current request or task context so view functions can reach it without it being
+threaded through every call.
+
+This lives in core rather than in an integration on purpose: every integration
+needs the *same* contextvar. If each one owned a private one, a scope opened by
+the Flask integration would be invisible to anything reading through another,
+and nested/mixed stacks (an ASGI app mounting a WSGI app, say) would silently
+resolve against the wrong scope.
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING, Iterator, Optional
+
+# Defined in exceptions.py so the whole hierarchy lives in one place; re-exported
+# here because this is where it is raised and where callers expect to find it.
+from .exceptions import NoActiveScopeError
+
+if TYPE_CHECKING:
+    from .services import ServiceScope
+
+__all__ = [
+    'NoActiveScopeError',
+    'current_scope',
+    'get_current_scope',
+    'set_current_scope',
+    'reset_current_scope',
+    'use_scope',
+]
+
+
+_current_scope: ContextVar[Optional['ServiceScope']] = ContextVar(
+    'depi_current_scope', default=None
+)
+
+
+def get_current_scope() -> Optional['ServiceScope']:
+    """Return the scope bound to the current context, or None if there is none."""
+    return _current_scope.get()
+
+
+def current_scope() -> 'ServiceScope':
+    """
+    Return the scope bound to the current context.
+
+    Raises:
+        NoActiveScopeError: if no scope is bound.
+    """
+    scope = _current_scope.get()
+    if scope is None:
+        raise NoActiveScopeError(
+            "No active depi scope. Ensure the integration's setup(app) ran and that "
+            "this code runs inside a request handled by its middleware."
+        )
+    return scope
+
+
+def set_current_scope(scope: Optional['ServiceScope']) -> Token:
+    """
+    Bind a scope to the current context.
+
+    Returns the token needed to restore the previous value; pass it to
+    :func:`reset_current_scope`. Prefer :func:`use_scope` where the bind and
+    restore happen in the same frame.
+    """
+    return _current_scope.set(scope)
+
+
+def reset_current_scope(token: Token) -> None:
+    """Restore the scope that was bound before ``token`` was issued."""
+    _current_scope.reset(token)
+
+
+@contextmanager
+def use_scope(scope: 'ServiceScope') -> Iterator['ServiceScope']:
+    """
+    Bind ``scope`` for the duration of the block, then restore the previous one.
+
+    Note this only binds the scope; it does not dispose it. Disposal stays with
+    whoever created the scope, since integrations differ on when it is safe
+    (Flask at teardown_request, ASGI after the response body is sent).
+    """
+    token = _current_scope.set(scope)
+    try:
+        yield scope
+    finally:
+        _current_scope.reset(token)

pydepi-0.1.0/depi/exceptions.py

@@ -0,0 +1,125 @@
+"""
+Exception hierarchy.
+
+Every error depi raises derives from :class:`DepiError`, so an application can
+catch depi's failures without catching everything. The classes are grouped by
+*when* the failure happens, because that maps to who can fix it:
+
+- :class:`RegistrationError` -- the container was described wrongly. Raised while
+  registering services or building a provider, i.e. at startup, before traffic.
+- :class:`ResolutionError` -- the container was asked for something it could not
+  produce. Raised at resolve time.
+
+These live in their own module so both :mod:`depi.services` and
+:mod:`depi.context` can import them without a cycle.
+
+Backwards compatibility: depi previously raised bare ``Exception`` and, for the
+async-factory guard, ``RuntimeError``. Every class here still derives from the
+type it used to be, so existing ``except Exception`` and ``except RuntimeError``
+handlers keep working unchanged.
+"""
+
+__all__ = [
+    'DepiError',
+    'RegistrationError',
+    'MissingAnnotationError',
+    'CircularDependencyError',
+    'InvalidLifetimeError',
+    'UnknownLifetimeError',
+    'ResolutionError',
+    'UnregisteredDependencyError',
+    'ScopeRequiredError',
+    'AsyncFactoryError',
+    'NoActiveScopeError',
+]
+
+
+class DepiError(Exception):
+    """Base class for every error raised by depi."""
+
+
+# --------------------------------------------------------------------------
+# Registration / build time: the container was described wrongly.
+# --------------------------------------------------------------------------
+
+class RegistrationError(DepiError):
+    """Raised while registering services or building a provider."""
+
+
+class MissingAnnotationError(RegistrationError):
+    """
+    A constructor parameter has no type annotation.
+
+    depi resolves by annotation, so an unannotated parameter cannot be resolved.
+    Raised at registration rather than at resolution, so it surfaces at startup.
+    """
+
+
+class CircularDependencyError(RegistrationError):
+    """
+    A dependency cycle was found while building the provider.
+
+    Detected by static analysis at build time, so a cycle cannot reach
+    production as a recursion error at request time.
+    """
+
+
+class InvalidLifetimeError(RegistrationError):
+    """
+    Two registrations combine in a way that breaks one of their lifetimes.
+
+    In practice this is a singleton depending on a transient or scoped service:
+    the dependency would be constructed exactly once, inside the singleton, and
+    would silently stop behaving like a transient or a scoped service.
+    """
+
+
+class UnknownLifetimeError(RegistrationError):
+    """A registration carries a lifetime depi does not recognise."""
+
+
+# --------------------------------------------------------------------------
+# Resolution time: the container could not produce what was asked for.
+# --------------------------------------------------------------------------
+
+class ResolutionError(DepiError):
+    """Raised while resolving a service."""
+
+
+class UnregisteredDependencyError(ResolutionError):
+    """
+    No registration exists for the requested type.
+
+    Either the service was never registered, or it was registered under a
+    different type -- an interface rather than the implementation, typically.
+    """
+
+
+class ScopeRequiredError(ResolutionError):
+    """
+    A scoped service was resolved without a scope.
+
+    Call ``provider.create_scope()``, or resolve from the scope a framework
+    integration opened for the current request.
+    """
+
+
+class AsyncFactoryError(ResolutionError, RuntimeError):
+    """
+    An async factory was resolved through the synchronous API.
+
+    Also derives from RuntimeError, which is what this used to be, so existing
+    ``except RuntimeError`` handlers still catch it.
+    """
+
+
+class NoActiveScopeError(DepiError, RuntimeError):
+    """
+    A request scope was needed but none is bound to the current context.
+
+    Raised by :func:`depi.context.current_scope` when no integration has opened
+    a scope -- typically because ``setup(app)`` never ran, or because the code
+    is executing outside a request.
+
+    Also derives from RuntimeError for backwards compatibility.
+    """

pydepi-0.1.0/depi/integration.py

@@ -0,0 +1,173 @@
+"""
+The contract every depi framework integration is built on.
+
+This lives in core, and stays dependency-free: adapters ship as separate
+distributions (pydepi-flask, pydepi-quart, ...) and all build against this.
+
+Integrations are deliberately thin: they open a :class:`ServiceScope` per
+request, bind it to the ambient context (see :mod:`depi.context`), dispose it
+when the request ends, and offer a decorator to hand that scope to a view
+function. Everything above that -- authentication, response shaping, blueprint
+conventions -- belongs to the application, not to depi.
+"""
+
+import inspect
+from abc import ABC, abstractmethod
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Dict
+
+from .context import current_scope
+from .services import get_signature
+
+if TYPE_CHECKING:
+    from .services import ServiceProvider, ServiceScope
+
+__all__ = ['BaseInjector', 'injectable_parameters']
+
+_VARIADIC = (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+
+
+def injectable_parameters(
+    fn: Callable,
+    provider: 'ServiceProvider'
+) -> Dict[str, type]:
+    """
+    Map parameter name -> registered type for the parameters depi should supply.
+
+    Parameters the provider does not know about are left alone, because the web
+    framework almost certainly owns them (URL converters, query arguments). That
+    is why autowire cannot fail fast on an unresolvable annotation: from here,
+    "unregistered" and "supplied by the framework" look identical.
+
+    Called once at decoration time, never per request.
+    """
+    try:
+        parameters = get_signature(fn).parameters
+    except Exception:
+        # Deliberately broad. Signatures are evaluated with eval_str=True, and
+        # under `from __future__ import annotations` every annotation is a
+        # string, so this can fail in many ways: an unimportable forward
+        # reference (NameError), a malformed one (SyntaxError), a dotted name
+        # whose attribute is missing (AttributeError), a builtin with no
+        # retrievable signature (ValueError).
+        #
+        # None of those are depi's to diagnose, and all of them happen at
+        # decoration time -- at import, before the app can even start. Claiming
+        # nothing lets the framework supply the parameter and report the real
+        # problem itself.
+        return {}
+
+    injectable = {}
+    for name, param in parameters.items():
+        if param.kind in _VARIADIC:
+            continue
+        annotation = param.annotation
+        if annotation is inspect.Parameter.empty:
+            continue
+        if isinstance(annotation, type) and provider.is_registered(annotation):
+            injectable[name] = annotation
+    return injectable
+
+
+class BaseInjector(ABC):
+    """Base class for framework integrations."""
+
+    def __init__(
+        self,
+        provider: 'ServiceProvider',
+        param_name: str = 'provider',
+        autowire: bool = False
+    ):
+        """
+        Args:
+            provider: the built ServiceProvider to resolve from.
+            param_name: the keyword argument the request scope is passed as in
+                the default (non-autowire) mode. Name it to taste -- ``container``
+                is a common alternative.
+            autowire: when True, :meth:`inject` resolves registered types by
+                annotation instead of passing the scope. Not supported by every
+                integration; FastAPI rejects it outright.
+        """
+        self._provider = provider
+        self._param_name = param_name
+        self._autowire = autowire
+
+    @property
+    def provider(self) -> 'ServiceProvider':
+        """The provider this injector resolves from."""
+        return self._provider
+
+    def create_scope(self) -> 'ServiceScope':
+        """Create a new, unbound dependency scope."""
+        return self._provider.create_scope()
+
+    def current_scope(self) -> 'ServiceScope':
+        """
+        Return the scope bound to the current request context.
+
+        Raises:
+            NoActiveScopeError: if setup(app) never ran, or this is called
+                outside a request.
+        """
+        return current_scope()
+
+    @abstractmethod
+    def setup(self, app) -> None:
+        """Install per-request scope management onto ``app``."""
+
+    def _make_inject_wrapper(self, fn: Callable) -> Callable:
+        """
+        Build the injecting wrapper for ``fn``.
+
+        Resolution work that can be done once (signature inspection) is done
+        here, at decoration time, so the per-request path stays a dict lookup.
+        """
+        param_name = self._param_name
+
+        if self._autowire:
+            targets = injectable_parameters(fn, self._provider)
+
+            def apply(kwargs: Dict[str, Any]) -> None:
+                # The ambient scope is fetched lazily, and only if something is
+                # actually missing -- so a view whose services were all passed
+                # in can be called straight from a test with no request context.
+                scope = None
+                for name, _type in targets.items():
+                    if name in kwargs:
+                        continue
+                    if scope is None:
+                        scope = current_scope()
+                    kwargs[name] = scope.resolve(_type)
+        else:
+            def apply(kwargs: Dict[str, Any]) -> None:
+                # An explicitly passed scope wins, which is what makes a view
+                # callable directly from a test with a hand-built scope.
+                if param_name not in kwargs:
+                    kwargs[param_name] = current_scope()
+
+        if inspect.iscoroutinefunction(fn):
+            @wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                apply(kwargs)
+                return await fn(*args, **kwargs)
+            return async_wrapper
+
+        @wraps(fn)
+        def sync_wrapper(*args, **kwargs):
+            apply(kwargs)
+            return fn(*args, **kwargs)
+        return sync_wrapper
+
+    def inject(self, fn: Callable) -> Callable:
+        """
+        Decorator handing the request scope to ``fn``.
+
+        Default mode passes the scope as the ``param_name`` keyword argument.
+        With ``autowire=True``, parameters annotated with registered types are
+        resolved and passed individually instead.
+
+        Uses functools.wraps, so it composes inside a decorator stack (route
+        registration, auth, response handling) without losing the wrapped
+        function's identity.
+        """
+        return self._make_inject_wrapper(fn)