mixinv2 0.3.0.post56.dev0__tar.gz → 0.3.0.post58.dev0__tar.gz

{mixinv2-0.3.0.post56.dev0 → mixinv2-0.3.0.post58.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mixinv2
-Version: 0.3.0.post56.dev0
+Version: 0.3.0.post58.dev0
 Summary: A dependency injection framework with pytest-fixture syntax, plus a configuration language for declarative programming
 Project-URL: Repository, https://github.com/Atry/MIXINv2
 Author-email: "Yang, Bo" <yang-bo@yang-bo.com>

{mixinv2-0.3.0.post56.dev0 → mixinv2-0.3.0.post58.dev0}/src/mixinv2/__init__.py

@@ -18,6 +18,9 @@ Decorators:
 Runtime:
     - :func:`evaluate`
 
+Exceptions:
+    - :class:`Bottom`
+
 Reference types (parameters to :func:`extend`):
     - :class:`AbsoluteReference`
     - :class:`RelativeReference`
@@ -40,6 +43,7 @@ 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._core import Bottom as Bottom
 from mixinv2._runtime import evaluate as evaluate
 
 if TYPE_CHECKING:

{mixinv2-0.3.0.post56.dev0 → mixinv2-0.3.0.post58.dev0}/src/mixinv2/_core.py

@@ -530,6 +530,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from collections import defaultdict, deque
+from contextvars import ContextVar
 from dataclasses import dataclass, field, replace
 from enum import Enum, auto
 from functools import cached_property
@@ -603,6 +604,334 @@ TResult_co = TypeVar("TResult_co", covariant=True)
 P = ParamSpec("P")
 
 
+class _FixpointContext:
+    """Tracks the state of a fixpoint iteration (digest cycle).
+
+    Stored in a ContextVar so that nested/concurrent fixpoint computations
+    are isolated per-thread/per-coroutine.
+    """
+
+    __slots__ = ("computing", "reentrant", "participant_ids", "participant_refs",
+                 "_clearable_attr_names", "approximations")
+
+    def __init__(self, clearable_attr_names: frozenset[str]) -> None:
+        self.computing: set[tuple[int, str]] = set()
+        self.reentrant: bool = False
+        self.participant_ids: set[int] = set()
+        self.participant_refs: list[object] = []
+        self._clearable_attr_names = clearable_attr_names
+        self.approximations: dict[tuple[int, str], object] = {}
+
+    def add_participant(self, instance: object) -> None:
+        instance_id = id(instance)
+        if instance_id not in self.participant_ids:
+            self.participant_ids.add(instance_id)
+            self.participant_refs.append(instance)
+
+    def clear_participant_caches(self) -> None:
+        """Clear all fixpoint-related cached values on all participants.
+
+        Before clearing, save each value into ``approximations`` so that
+        intermediate fixpoint_cached_property computations can use their
+        previous iteration's result as an approximation instead of bottom
+        when they encounter reentry.
+        """
+        for instance in self.participant_refs:
+            instance_dict = instance.__dict__
+            instance_id = id(instance)
+            for attr_name in self._clearable_attr_names:
+                value = instance_dict.pop(attr_name, None)
+                if value is not None:
+                    self.approximations[(instance_id, attr_name)] = value
+
+
+_fixpoint_context_var: ContextVar[_FixpointContext | None] = ContextVar(
+    "_fixpoint_context_var", default=None
+)
+
+
+class Bottom(RecursionError):
+    """Raised when fixpoint iteration is exhausted or reentry is detected with no iterations remaining.
+
+    Carries the best approximation computed so far in ``incomplete_result``.
+    As a ``RecursionError`` subclass, existing code that catches ``RecursionError``
+    will also catch ``Bottom``.
+    """
+
+    incomplete_result: object
+
+    def __init__(self, message: str, *, incomplete_result: object) -> None:
+        super().__init__(message)
+        self.incomplete_result = incomplete_result
+
+
+_max_fixpoint_iterations_var: ContextVar[int] = ContextVar(
+    "_max_fixpoint_iterations_var", default=100
+)
+_FIXPOINT_SENTINEL = object()
+
+# Registry of attribute names that need clearing during fixpoint digest cycles.
+# Populated by fixpoint_cached_property and fixpoint_dependent decorators.
+_fixpoint_clearable_attrs: set[str] = set()
+
+
+def _accumulate_defaultdict_set(
+    accumulator: defaultdict[object, set[object]],
+    new_result: defaultdict[object, set[object]],
+) -> bool:
+    """Merge new_result into accumulator (pointwise set union).
+
+    Returns True if accumulator grew (new entries were added).
+    """
+    changed = False
+    for key, values in new_result.items():
+        existing = accumulator[key]
+        old_size = len(existing)
+        existing.update(values)
+        if len(existing) > old_size:
+            changed = True
+    return changed
+
+
+class fixpoint_cached_property:
+    """A cached_property that supports mutual-recursion via least fixpoint iteration.
+
+    API-compatible with functools.cached_property. When reentry is detected
+    (mutual recursion), returns the previous iteration's approximation
+    (or ``bottom()`` on the first iteration). The outermost caller drives
+    a digest loop until values stabilize (no reentry occurs in a round).
+
+    Usage::
+
+        @fixpoint_cached_property(bottom=lambda: defaultdict(set))
+        def qualified_this(self):
+            ...
+    """
+
+    def __init__(
+        self,
+        func: Callable = None,
+        *,
+        bottom: Callable[[], object],
+        accumulate: Callable[[object, object], bool] | None = None,
+    ) -> None:
+        # Support both @fixpoint_cached_property(bottom=...) and direct call
+        self._bottom = bottom
+        self._accumulate = accumulate
+        if func is not None:
+            self.func: Callable = func
+            self.attrname: str = func.__name__
+            self.__doc__ = func.__doc__
+            _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __call__(self, func: Callable) -> "fixpoint_cached_property":
+        """Support @fixpoint_cached_property(bottom=...) decorator syntax."""
+        self.func = func
+        self.attrname = func.__name__
+        self.__doc__ = func.__doc__
+        _fixpoint_clearable_attrs.add(self.attrname)
+        return self
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(self, "attrname"):
+            self.attrname = name
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __get__(self, instance: object, owner: type = None) -> object:
+        if instance is None:
+            return self
+
+        # Fast path: already cached
+        cache = instance.__dict__
+        value = cache.get(self.attrname)
+        if value is not None:
+            max_iterations = _max_fixpoint_iterations_var.get()
+            if max_iterations == 0:
+                return value
+            # Detect reentry: if this key is currently being computed
+            # (on the call stack), accessing its cached approximation
+            # means the fixpoint has not converged yet.
+            context = _fixpoint_context_var.get()
+            if context is not None:
+                key = (id(instance), self.attrname)
+                if key in context.computing:
+                    context.reentrant = True
+                    context.add_participant(instance)
+            return value
+
+        max_iterations = _max_fixpoint_iterations_var.get()
+        context = _fixpoint_context_var.get()
+        instance_id = id(instance)
+        key = (instance_id, self.attrname)
+
+        if context is None:
+            # I am the driver — start a digest loop (or single-pass for max_iterations=0)
+            context = _FixpointContext(
+                clearable_attr_names=frozenset(_fixpoint_clearable_attrs)
+            )
+            token = _fixpoint_context_var.set(context)
+            try:
+                if max_iterations == 0:
+                    # Zero-iteration mode: compute once with reentry detection.
+                    # Reentry raises Bottom instead of infinite recursion.
+                    context.computing.add(key)
+                    result = self.func(instance)
+                    cache[self.attrname] = result
+                    return result
+
+                approximation = self._bottom()
+                accumulator = self._bottom() if self._accumulate is not None else None
+                previous_result = _FIXPOINT_SENTINEL
+                for iteration in range(max_iterations):
+                    context.computing.add(key)
+                    context.add_participant(instance)
+                    result = self.func(instance)
+
+                    if not context.reentrant:
+                        # No reentry this round — fixpoint reached
+                        cache[self.attrname] = result
+                        return result
+
+                    if self._accumulate is not None:
+                        # Monotonic accumulation: merge each iteration's
+                        # result into an accumulator that only grows.
+                        # This prevents oscillation when intermediate
+                        # computations encounter cycles in varying order.
+                        changed = self._accumulate(accumulator, result)
+                        if not changed and iteration > 0:
+                            cache[self.attrname] = accumulator
+                            return accumulator
+                        # Use the accumulator as next round's approximation
+                        approximation = accumulator
+                    else:
+                        # Exact equality convergence (original behavior)
+                        if result == previous_result:
+                            cache[self.attrname] = result
+                            return result
+                        previous_result = result
+                        approximation = result
+
+                    # Cache current approximation, clear all intermediate
+                    # caches, and re-run
+                    cache[self.attrname] = approximation
+                    context.clear_participant_caches()
+                    # Restore driver's own approximation
+                    cache[self.attrname] = approximation
+                    context.computing.clear()
+                    context.reentrant = False
+
+                raise Bottom(
+                    f"fixpoint_cached_property '{self.attrname}' did not converge "
+                    f"after {max_iterations} iterations",
+                    incomplete_result=approximation,
+                )
+            finally:
+                _fixpoint_context_var.reset(token)
+        elif key in context.computing:
+            # Reentry detected — return previous approximation or bottom.
+            context.reentrant = True
+            context.add_participant(instance)
+            if max_iterations == 0:
+                raise Bottom(
+                    f"fixpoint_cached_property '{self.attrname}': "
+                    f"reentry detected with max_fixpoint_iterations=0",
+                    incomplete_result=self._bottom(),
+                )
+            # Check the instance cache first, then fall back to saved
+            # approximations from the previous iteration.
+            approximation = cache.get(self.attrname)
+            if approximation is not None:
+                return approximation
+            saved = context.approximations.get(key)
+            if saved is not None:
+                return saved
+            return self._bottom()
+        else:
+            # Inside a fixpoint context but this is a fresh (instance, attr)
+            # pair — compute normally.  Keep the key in ``computing`` only
+            # while ``self.func`` runs so that cycles through this key are
+            # detected by the ``elif`` branch above.  Once computation
+            # finishes, remove the key so the fast-path cache check does
+            # not misidentify a later read of this cached value as reentry.
+            context.computing.add(key)
+            context.add_participant(instance)
+            result = self.func(instance)
+            context.computing.discard(key)
+            cache[self.attrname] = result
+            return result
+
+    def __set__(self, instance: object, value: object) -> None:
+        """Data descriptor setter to ensure __get__ is always called."""
+        instance.__dict__[self.attrname] = value
+
+
+class _fixpoint_dependent_property:
+    """A cached_property that registers its instance as a fixpoint participant.
+
+    Behaves like ``functools.cached_property`` but, when computed inside an
+    active fixpoint context, registers the instance so that
+    ``clear_participant_caches`` will clear the cached value between
+    iterations.  Without this, stale values computed from an incomplete
+    fixpoint approximation survive across iterations.
+    """
+
+    def __init__(self, func: Callable) -> None:
+        self.func = func
+        self.attrname = func.__name__
+        self.__doc__ = func.__doc__
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if not hasattr(self, "attrname"):
+            self.attrname = name
+        _fixpoint_clearable_attrs.add(self.attrname)
+
+    def __get__(self, instance: object, owner: type = None) -> object:
+        if instance is None:
+            return self
+
+        cache = instance.__dict__
+        value = cache.get(self.attrname)
+        if value is not None:
+            return value
+
+        if _max_fixpoint_iterations_var.get() > 0:
+            # Register as participant so clear_participant_caches can
+            # invalidate this cached value between fixpoint iterations.
+            context = _fixpoint_context_var.get()
+            if context is not None:
+                context.add_participant(instance)
+
+        value = self.func(instance)
+        cache[self.attrname] = value
+        return value
+
+
+def fixpoint_dependent(func: Callable) -> _fixpoint_dependent_property:
+    """Mark a cached_property as dependent on fixpoint_cached_property values.
+
+    During fixpoint digest cycles, these caches are cleared between iterations
+    so they are recomputed with updated approximations.
+
+    Usage::
+
+        @fixpoint_dependent
+        @cached_property
+        def symbol_kind(self):
+            ...
+
+    Or equivalently::
+
+        @fixpoint_dependent
+        def symbol_kind(self):
+            ...
+    """
+    if isinstance(func, cached_property):
+        return _fixpoint_dependent_property(func.func)
+    else:
+        return _fixpoint_dependent_property(func)
+
+
 class HasDict:
     """
     Extendable helper class that adds ``__dict__`` slot for classes that need ``@cached_property``.
@@ -892,7 +1221,7 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
                 return tuple(definitions)
 
     @final
-    @cached_property
+    @fixpoint_dependent
     def normalized_references(self) -> tuple["ResolvedReference", ...]:
         """
         Flatten all bases from all definitions into a single tuple.
@@ -1051,9 +1380,14 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
         # Use Nested to create child symbol with lazy definition resolution
         compiled_symbol = MixinSymbol(origin=Nested(outer=self, key=key))
 
-        # Check if any super union of self has this key as an own key
-        if not any(super_union.has_own_key(key) for super_union in self.qualified_this):
-            raise KeyError(key)
+        # Check if self or any super union of self has this key as an own key.
+        # During fixpoint iteration, qualified_this may not have converged yet,
+        # so skip this validation to avoid false negatives.
+        if _fixpoint_context_var.get() is None:
+            if not self.has_own_key(key) and not any(
+                super_union.has_own_key(key) for super_union in self.qualified_this
+            ):
+                raise KeyError(key)
 
         self._nested[key] = compiled_symbol
         return compiled_symbol
@@ -1072,16 +1406,19 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
             case MixinSymbol() as outer_symbol:
                 return outer_symbol.depth + 1
 
-    @cached_property
+    @fixpoint_dependent
     def is_public(self):
-        # Check if any definition is public
+        # Check own definitions first (does not depend on qualified_this)
+        if any(definition.is_public for definition in self.definitions):
+            return True
+        # Check inherited definitions via qualified_this
         return any(
             definition.is_public
             for super_symbol in self.qualified_this
             for definition in super_symbol.definitions
         )
 
-    @cached_property
+    @fixpoint_dependent
     def is_eager(self):
         return any(
             definition.is_eager
@@ -1090,7 +1427,7 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
             if isinstance(definition, MergerDefinition)
         )
 
-    @cached_property
+    @fixpoint_dependent
     def symbol_kind(self) -> "SymbolKind":
         """Classify this symbol into one of three categories.
 
@@ -1176,7 +1513,10 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
             case _:
                 raise ValueError("Multiple pure merger definitions found")
 
-    @cached_property
+    @fixpoint_cached_property(
+        bottom=lambda: defaultdict(set),
+        accumulate=_accumulate_defaultdict_set,
+    )
     def qualified_this(self) -> Mapping["MixinSymbol", Collection[MixinSymbol]]:
         """Map each overlay of ``self`` to the outer scopes that instantiate it.
 
@@ -1220,7 +1560,7 @@ class MixinSymbol(HasDict, Mapping[Hashable, "MixinSymbol"], Symbol):
                     if outer_union.has_own_key(key):
                         yield outer_union[key]
 
-    @cached_property
+    @fixpoint_dependent
     def overlays(self):
         return frozenset(self._generate_overlays())
 
@@ -2475,9 +2815,15 @@ class AbsoluteReference:
         for part in self.path:
             child_symbol = current_symbol.get(part)
             if child_symbol is None:
+                kind_hint = (
+                    f" (unexpected kind {current_symbol.symbol_kind.name})"
+                    if current_symbol.symbol_kind is not SymbolKind.SCOPE
+                    else ""
+                )
                 raise ValueError(
                     f"Cannot navigate path {self.path!r}: "
-                    f"'{current_symbol.key}' has no child '{part}'"
+                    f"{current_symbol.path}{kind_hint}"
+                    f" has no child '{part}'"
                 )
             current_symbol = child_symbol
 
@@ -2533,7 +2879,9 @@ class RelativeReference:
             if child_symbol is None:
                 raise ValueError(
                     f"Cannot navigate path {self.path!r}: "
-                    f"'{current_symbol.key}' has no child '{part}'"
+                    f"{current_symbol.path} (unexpected kind"
+                    f" {current_symbol.symbol_kind.name})"
+                    f" has no child '{part}'"
                 )
             current_symbol = child_symbol
 
@@ -2738,9 +3086,15 @@ class LexicalReference:
         for part in hashable_path:
             child_symbol = current_symbol.get(part)
             if child_symbol is None:
+                kind_hint = (
+                    f" (unexpected kind {current_symbol.symbol_kind.name})"
+                    if current_symbol.symbol_kind is not SymbolKind.SCOPE
+                    else ""
+                )
                 raise ValueError(
                     f"Cannot navigate path {hashable_path!r}: "
-                    f"'{current_symbol.key}' has no child '{part}'"
+                    f"{current_symbol.path}{kind_hint}"
+                    f" has no child '{part}'"
                 )
             current_symbol = child_symbol
 
@@ -2828,9 +3182,15 @@ class QualifiedThisReference:
         for part in hashable_path:
             child_symbol = current_symbol.get(part)
             if child_symbol is None:
+                kind_hint = (
+                    f" (unexpected kind {current_symbol.symbol_kind.name})"
+                    if current_symbol.symbol_kind is not SymbolKind.SCOPE
+                    else ""
+                )
                 raise ValueError(
                     f"Cannot navigate path {hashable_path!r}: "
-                    f"'{current_symbol.key}' has no child '{part}'"
+                    f"{current_symbol.path}{kind_hint}"
+                    f" has no child '{part}'"
                 )
             current_symbol = child_symbol
 

{mixinv2-0.3.0.post56.dev0 → mixinv2-0.3.0.post58.dev0}/src/mixinv2/_runtime.py

@@ -30,7 +30,12 @@ from typing import (
     final,
 )
 
-from mixinv2._core import HasDict, OuterSentinel, SymbolKind
+from mixinv2._core import (
+    HasDict,
+    OuterSentinel,
+    SymbolKind,
+    _max_fixpoint_iterations_var,
+)
 
 
 class KwargsSentinel(Enum):
@@ -634,6 +639,7 @@ class MultiplePatcher(Patcher[TPatch_co]):
 def evaluate(
     *namespaces: "ModuleType | ScopeDefinition",
     modules_public: bool = False,
+    max_fixpoint_iterations: int = 100,
 ) -> Scope:
     """
     Resolves a Scope from the given namespaces.
@@ -650,6 +656,10 @@ def evaluate(
     :param namespaces: Modules or namespace definitions (decorated with @scope) to resolve.
     :param modules_public: If True, modules are marked as public, making their submodules
         accessible via attribute access. Defaults to False (private by default).
+    :param max_fixpoint_iterations: Maximum number of fixpoint iterations for
+        resolving cyclic dependencies.  ``0`` disables fixpoint iteration and
+        raises ``Bottom`` on reentry.  Default ``100`` iterates until convergence
+        or raises ``Bottom`` if not converged.
     :return: The root Scope.
 
     Example::
@@ -657,6 +667,7 @@ def evaluate(
         root = evaluate(MyNamespace)
         root = evaluate(Base, Override)  # Union mount
         root = evaluate(my_package, modules_public=True)  # Make modules accessible
+        root = evaluate(MyNamespace, max_fixpoint_iterations=0)  # No fixpoint iteration
 
     """
     from dataclasses import replace
@@ -671,36 +682,44 @@ def evaluate(
     )
 
     assert namespaces, "evaluate() requires at least one namespace"
+    if max_fixpoint_iterations < 0:
+        raise ValueError(
+            f"max_fixpoint_iterations must be non-negative, got {max_fixpoint_iterations}"
+        )
 
-    def to_scope_definition(
-        namespace: ModuleType | ScopeDefinition,
-    ) -> ScopeDefinition:
-        if isinstance(namespace, ScopeDefinition):
-            return namespace
-        if isinstance(namespace, ModuleType):
-            definition = _parse_package(namespace)
-            if modules_public:
-                return replace(definition, is_public=True)
-            return definition
-        assert_never(namespace)
-
-    definitions = tuple(to_scope_definition(namespace) for namespace in namespaces)
-
-    root_symbol = MixinSymbol(origin=definitions)
-
-    # Create a synthetic root Mixin to enable lexical scope navigation
-    # This is needed so that children of the root scope can navigate up
-    # to find parent scope dependencies (via get_mixin)
-    root_mixin = Mixin(
-        symbol=root_symbol,
-        outer=OuterSentinel.ROOT,
-        kwargs=KwargsSentinel.STATIC,  # Root is always static
-    )
+    token = _max_fixpoint_iterations_var.set(max_fixpoint_iterations)
+    try:
+        def to_scope_definition(
+            namespace: ModuleType | ScopeDefinition,
+        ) -> ScopeDefinition:
+            if isinstance(namespace, ScopeDefinition):
+                return namespace
+            if isinstance(namespace, ModuleType):
+                definition = _parse_package(namespace)
+                if modules_public:
+                    return replace(definition, is_public=True)
+                return definition
+            assert_never(namespace)
+
+        definitions = tuple(to_scope_definition(namespace) for namespace in namespaces)
+
+        root_symbol = MixinSymbol(origin=definitions)
+
+        # Create a synthetic root Mixin to enable lexical scope navigation
+        # This is needed so that children of the root scope can navigate up
+        # to find parent scope dependencies (via get_mixin)
+        root_mixin = Mixin(
+            symbol=root_symbol,
+            outer=OuterSentinel.ROOT,
+            kwargs=KwargsSentinel.STATIC,  # Root is always static
+        )
 
-    # Evaluate the root mixin to get the Scope
-    result = root_mixin.evaluated
-    assert isinstance(result, Scope)
-    return result
+        # Evaluate the root mixin to get the Scope
+        result = root_mixin.evaluated
+        assert isinstance(result, Scope)
+        return result
+    finally:
+        _max_fixpoint_iterations_var.reset(token)
 
 
 # Re-export types needed by TYPE_CHECKING imports