mixinv2 0.2.0.post28.dev0__py3-none-any.whl

mixinv2/__init__.py

@@ -0,0 +1,100 @@
+"""
+MIXINv2: A dependency injection framework with pytest-fixture-like semantics.
+
+Public API
+==========
+
+Decorators:
+    - :func:`scope`
+    - :func:`resource`
+    - :func:`patch`
+    - :func:`patch_many`
+    - :func:`merge`
+    - :func:`extern`
+    - :func:`public`
+    - :func:`eager`
+    - :func:`extend`
+
+Runtime:
+    - :func:`evaluate`
+
+Reference types (parameters to :func:`extend`):
+    - :class:`AbsoluteReference`
+    - :class:`RelativeReference`
+    - :class:`LexicalReference`
+    - :class:`QualifiedThisReference`
+    - :data:`ResourceReference`
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Public API: decorators and evaluate
+from mixinv2._core import eager as eager
+from mixinv2._core import extend as extend
+from mixinv2._core import extern as extern
+from mixinv2._core import merge as merge
+from mixinv2._core import patch as patch
+from mixinv2._core import patch_many as patch_many
+from mixinv2._core import public as public
+from mixinv2._core import resource as resource
+from mixinv2._core import scope as scope
+from mixinv2._runtime import evaluate as evaluate
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+    from typing import Protocol, TypeAlias, final
+
+    @final
+    class AbsoluteReference(Protocol):
+        """An absolute reference to a resource starting from the root scope."""
+
+        path: tuple[Hashable, ...]
+
+        def __init__(self, *, path: tuple[Hashable, ...]) -> None: ...
+
+    @final
+    class RelativeReference(Protocol):
+        """A reference to a resource relative to the current lexical scope."""
+
+        de_bruijn_index: int
+        path: tuple[Hashable, ...]
+
+        def __init__(
+            self, *, de_bruijn_index: int, path: tuple[Hashable, ...]
+        ) -> None: ...
+
+    @final
+    class LexicalReference(Protocol):
+        """A lexical reference following the MIXINv2 spec resolution algorithm."""
+
+        path: tuple[Hashable, ...]
+
+        def __init__(self, *, path: tuple[Hashable, ...]) -> None: ...
+
+    @final
+    class QualifiedThisReference(Protocol):
+        """A qualified this reference: [SelfName, ~, property, path]."""
+
+        self_name: str
+        path: tuple[str, ...]
+
+        def __init__(
+            self, *, self_name: str, path: tuple[str, ...]
+        ) -> None: ...
+
+    ResourceReference: TypeAlias = (
+        AbsoluteReference
+        | RelativeReference
+        | LexicalReference
+        | QualifiedThisReference
+    )
+else:
+    from mixinv2._core import AbsoluteReference as AbsoluteReference
+    from mixinv2._core import LexicalReference as LexicalReference
+    from mixinv2._core import (
+        QualifiedThisReference as QualifiedThisReference,
+    )
+    from mixinv2._core import RelativeReference as RelativeReference
+    from mixinv2._core import ResourceReference as ResourceReference

mixinv2/_config.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class InitializationTiming(Enum):
+    LAZY = auto()
+    """
+    The resource is created when it is first accessed.
+    """
+
+    POST_INIT = auto()
+    """
+    The resource is created in ``Scope.__post_init__``.
+    """
+    ENTER = auto()
+    """
+    The resource is created in ``Scope.__enter__`` or ``Scope.__aenter__``, depending on whether the resource is async.
+    """
+
+
+@dataclass(kw_only=True, frozen=True, slots=True, weakref_slot=True)
+class Lifecycle:
+    is_weak_reference: bool
+    """
+    Whether the resource is cached using a weak reference.
+    """
+
+    initialization: InitializationTiming
+    """
+    When the resource is created.
+    """
+
+
+class LifecycleSentinel(Enum):
+    EPHEMERAL = auto()
+    """
+    The resource is not cached, and is created every time it is accessed.
+    """
+
+
+@dataclass(kw_only=True, frozen=True, slots=True, weakref_slot=True)
+class ResourceConfig:
+    lifecycle: Lifecycle | LifecycleSentinel
+    is_async: bool
+    """
+    Whether the resource is async.
+
+    When lifecycle is not EPHEMERAL, the resource (possibly after ``async_enter_context``) is converted to a Future when is_async is True.
+    """
+
+    is_contextmanager: bool
+    """
+    Whether the resource is a context manager.
+
+    If True, the ``TResult`` is either a ``ContextManager`` or ``AsyncContextManager``, and should be registered with ``scope.exit_stack.enter_context``` or ``scope.exit_stack.async_enter_context`` depending on ``is_async``.
+    """