objectstate 3.0.1__tar.gz → 3.0.2__tar.gz

{objectstate-3.0.1 → objectstate-3.0.2}/.github/badges/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 75.78%"><title>coverage: 75.78%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">75.78%</text><text x="865" y="150" fill-opacity=".3" textLength="430">75.78%</text></g><text x="865" y="140" textLength="430">75.78%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 81.07%"><title>coverage: 81.07%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">81.07%</text><text x="865" y="150" fill-opacity=".3" textLength="430">81.07%</text></g><text x="865" y="140" textLength="430">81.07%</text></g></g></svg>

{objectstate-3.0.1 → objectstate-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objectstate
-Version: 3.0.1
+Version: 3.0.2
 Summary: Generic lazy dataclass configuration framework with dual-axis inheritance and contextvars-based resolution
 Project-URL: Homepage, https://github.com/OpenHCSDev/objectstate
 Project-URL: Documentation, https://objectstate.readthedocs.io

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/__init__.py

@@ -210,7 +210,7 @@ __all__ = [
     'ObjectStateEditSession',
 ]
 
-__version__ = "3.0.1"
+__version__ = "3.0.2"
 __author__ = 'OpenHCS Team'
 __description__ = 'Generic configuration framework for lazy dataclass resolution'
 

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/docs/configuration_framework.rst

@@ -149,7 +149,7 @@ Usage Example
        )
    )
 
-The lazy configs resolve through dual-axis algorithm: check ``AppConfig`` context first, then ``GlobalAppConfig`` context, walking MRO at each level.
+The lazy configs resolve class first: ``DatabaseConfig`` is looked up in the ``AppConfig`` layer, then in the ``GlobalAppConfig`` layer, and only if neither holds a value is a base class of ``DatabaseConfig`` tried in those layers. A value on the more specific class in the global config therefore beats a value on a base class in the app config. :ref:`precedence-order` states the order with an example.
 
 Framework Modules
 ----------------

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/docs/context_system.rst

@@ -195,10 +195,37 @@ The dual-axis resolver reads the layer stack of the active context:
 
    value, source_scope, source_type = resolve_with_provenance(LazyDatabaseConfig, "port")
 
-For each type in the container type's MRO, most specific first, it asks every layer from
-innermost to outermost for a config of that type and returns the first value that is not
-``None``, together with the layer's scope id and the type it was read from. Attribute access
-on a lazy config returns the ``value`` of this same result.
+Attribute access on a lazy config returns the ``value`` of this same result.
+
+.. _precedence-order:
+
+Precedence Order
+~~~~~~~~~~~~~~~~
+
+Resolution is class first. For each class in the MRO of the type being read, most specific
+first, the resolver asks every layer from the innermost scope to the outermost for a config
+of that class and returns the first value that is not ``None``, together with the layer's
+scope id and the class it was read from. Only when no layer holds a value for a class is
+the next, less specific class tried.
+
+So the class decides before the scope does. Take ``Leaf(Base)``, a field ``value`` read on
+``Leaf`` in a step, and two layers that hold a value:
+
+==========================  ======================  =====================
+Layer (scope)               ``Base.value``          ``Leaf.value``
+==========================  ======================  =====================
+plate (inner)               ``"base at plate"``     ``None``
+global (outer)              ``None``                ``"leaf at global"``
+==========================  ======================  =====================
+
+The read returns ``"leaf at global"`` with source ``("", Leaf)``: ``Leaf`` is tried in
+every scope before ``Base`` is tried in any, although the plate is the nearer scope. A
+value on the same class in a nearer scope does win: with ``Leaf.value`` also set on the
+plate, the plate's value is returned.
+
+This is the only statement of the order. ``objectstate.dual_axis_resolver`` implements it
+in ``_resolve_in_layers``; ``tests/test_resolution_precedence_order.py`` checks it for
+every set of (class, scope) sites.
 
 Usage Pattern
 ------------

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/dual_axis_resolver.py

@@ -151,11 +151,16 @@ def resolve_in_stack(stack, container_type: type, field_name: str) -> ResolvedFi
 
 
 def _resolve_in_layers(layers: tuple, container_type: type, field_name: str) -> ResolvedField:
-    """Walk the container type's MRO and, for each type, the layers from inner to outer.
+    """Resolve class first: the MRO is the outer loop, the layers the inner one.
 
-    MRO order dominates layer order: ``None`` in an inner layer means "inherit", so
-    every outer layer is asked for the same type before a less specific type is
-    tried. A layer that masks the layers outside it ends the walk outward.
+    For each class in the container type's MRO, most specific first, every layer is
+    asked from the innermost scope to the outermost; the first value that is not
+    ``None`` wins. ``None`` in an inner layer means "inherit", so a less specific
+    class is tried only after every layer was asked for the more specific one.
+    A layer that masks the layers outside it ends the walk outward.
+
+    The order is stated with an example in ``docs/context_system.rst`` under
+    "Precedence Order"; this function is its implementation.
     """
     container_base = _normalize_to_base(container_type)
 

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/object_state.py

@@ -226,6 +226,10 @@ class ObjectState:
         # Maps dotted_path → (source_scope_id, source_type) for inherited fields
         # source_type may differ from local container_type due to MRO inheritance
         self._live_provenance: dict[str, tuple[str | None, type | None]] = {}
+        # The registered ancestors each resolved snapshot was computed from, keyed by
+        # ``use_saved``. A snapshot is current only while ``_registered_ancestors()``
+        # still returns the same states.
+        self._ancestors_resolved_from: dict[bool, tuple[ObjectState, ...]] = {}
 
         # === Saved baseline (2 attributes) ===
         self._saved_resolved: dict[str, Any] = {}
@@ -476,8 +480,7 @@ class ObjectState:
     def to_saved_resolved_object(self) -> Any:
         """Reconstruct this state as an object with saved resolved values."""
         self._check_and_sync_delegate()
-        if not self._saved_resolved:
-            self._saved_resolved = self._compute_resolved_snapshot(use_saved=True)
+        self._ensure_saved_resolved()
         return self._reconstruct_from_resolved(
             "", self._saved_resolved, self._extraction_target, self._parameter_structure
         )
@@ -742,6 +745,12 @@ class ObjectState:
             self._invalid_fields.clear()
             return set()  # First populate - no "changes" to flash
 
+        if not self._resolved_from_registered_ancestors():
+            # Registration changed above this state: every inherited field may have
+            # another source, so both snapshots are resolved again in full. Pending
+            # field invalidations are covered by the full pass.
+            return self._resolve_again_from_registered_ancestors(notify=notify_flash)
+
         # Partial recompute for invalid fields only
         if self._invalid_fields:
             logger.debug(f"🔄 _ensure_live_resolved: scope={self.scope_id}, recomputing {len(self._invalid_fields)} invalid fields: {list(self._invalid_fields)}")
@@ -759,6 +768,60 @@ class ObjectState:
 
         return changed_paths
 
+    def _registered_ancestors(self) -> tuple[ObjectState, ...]:
+        """The other states this state's resolved values are computed from.
+
+        This state is left out: registering it adds no value it does not hold.
+        """
+        return tuple(
+            state
+            for _, state in ObjectStateRegistry.registered_ancestors(self.scope_id)
+            if state is not self
+        )
+
+    def _resolved_from_registered_ancestors(self) -> bool:
+        """Whether both resolved snapshots were computed from today's ancestors."""
+        ancestors = self._registered_ancestors()
+        return all(
+            self._ancestors_resolved_from.get(use_saved) == ancestors
+            for use_saved in (False, True)
+        )
+
+    def _resolve_again_from_registered_ancestors(self, *, notify: bool) -> set[str]:
+        """Resolve the live and saved snapshots in full; return the changed live paths."""
+        previous = self._live_resolved or {}
+        self._live_resolved = self._compute_resolved_snapshot()
+        self._invalid_fields.clear()
+        self._saved_resolved = self._compute_resolved_snapshot(use_saved=True)
+        changed_values = {
+            path: (previous.get(path), value)
+            for path, value in self._live_resolved.items()
+            if previous.get(path) != value
+        }
+        if changed_values:
+            self._set_last_changed_values(changed_values)
+        changed_paths = self.notification_fields_for_value_changes(changed_values)
+        self._sync_materialized_state(
+            changed_value_fields=changed_paths, emit_notifications=notify
+        )
+        return changed_paths
+
+    def resolve_again_if_ancestors_changed(self) -> None:
+        """Resolve again when other states are registered above this one than before.
+
+        Every resolved read makes this check itself. ``ObjectStateRegistry`` calls it
+        when registration changes so subscribers are told at once.
+        """
+        if self._live_resolved is not None:
+            self._ensure_live_resolved()
+
+    def _ensure_saved_resolved(self) -> None:
+        """Make ``_saved_resolved`` hold every field, resolved from today's ancestors."""
+        if self._live_resolved is not None and not self._resolved_from_registered_ancestors():
+            self._resolve_again_from_registered_ancestors(notify=True)
+        elif not self._saved_resolved:
+            self._saved_resolved = self._compute_resolved_snapshot(use_saved=True)
+
     # DELETED: _create_nested_states() - No longer needed with flat storage
     # Nested ObjectStates are no longer created - flat storage handles all parameters
 
@@ -1157,9 +1220,7 @@ class ObjectState:
         # Auto-detect delegate changes before resolving values
         self._check_and_sync_delegate()
 
-        # Ensure saved resolved cache is populated
-        if not self._saved_resolved:
-            self._saved_resolved = self._compute_resolved_snapshot(use_saved=True)
+        self._ensure_saved_resolved()
 
         # Check if this is a container/dataclass field (has subfields in _saved_resolved)
         prefix = f"{param_name}."
@@ -1190,8 +1251,7 @@ class ObjectState:
         self._check_and_sync_delegate()
         self._ensure_live_resolved()
         assert self._live_resolved is not None
-        if not self._saved_resolved:
-            self._saved_resolved = self._compute_resolved_snapshot(use_saved=True)
+        self._ensure_saved_resolved()
 
         path = owner_field_path
         raw_value = self.parameters.get(path.value, MISSING)
@@ -2092,6 +2152,7 @@ class ObjectState:
             raise TypeError("ObjectState.parameters must remain a canonical flat dictionary.")
         if not isinstance(self._saved_parameters, dict):
             raise TypeError("ObjectState._saved_parameters must remain a canonical flat dictionary.")
+        self._ancestors_resolved_from[use_saved] = self._registered_ancestors()
         ancestors = ObjectStateRegistry.get_ancestor_objects_with_scopes(
             self.scope_id, use_saved=use_saved
         )

{objectstate-3.0.1 → objectstate-3.0.2}/src/objectstate/object_state_registry.py

@@ -17,6 +17,7 @@ from typing import (
     Tuple,
     TYPE_CHECKING,
     Generator,
+    Iterable,
     TypeAlias,
 )
 import copy
@@ -409,6 +410,7 @@ class ObjectStateRegistry:
         cls._states[key] = state
         cls.mark_snapshot_dirty_scope(key)
         logger.debug(f"Registered ObjectState: scope={key}, type={type(state.object_instance).__name__}")
+        cls._resolve_again_below((key,))
 
         # Fire callbacks for UI binding
         cls._fire_register_callbacks(key, state)
@@ -433,6 +435,7 @@ class ObjectStateRegistry:
             # that reference this ObjectState. Graveyard persists for session lifetime.
             cls._graveyard[key] = removed_state
             logger.debug(f"Unregistered ObjectState: scope={key} (moved to graveyard)")
+            cls._resolve_again_below((key,))
 
             # Fire callbacks for UI binding
             cls._fire_unregister_callbacks(key, state)
@@ -440,6 +443,36 @@ class ObjectStateRegistry:
             # Structural unregistration is not a user-edit boundary. The
             # graveyard preserves state for explicit operation snapshots.
 
+    @classmethod
+    def _resolve_again_below(cls, changed_scopes: Iterable[ScopeKey]) -> None:
+        """Tell registered states at or below ``changed_scopes`` that registration changed.
+
+        Each state compares the ancestors registered now with the ones its resolved
+        values were computed from (``ObjectState.resolve_again_if_ancestors_changed``),
+        so a state whose ancestors are the same does no work. This call only makes
+        the comparison happen now, so subscribers hear of changed values without
+        waiting for the next read.
+        """
+        changed_scopes = tuple(changed_scopes)
+        for state in tuple(cls._states.values()):
+            if any(scope.contains(state.scope_id) for scope in changed_scopes):
+                state.resolve_again_if_ancestors_changed()
+
+    @classmethod
+    def registered_ancestors(
+        cls, scope_id: str | None
+    ) -> tuple[tuple[ScopeKey, 'ObjectState'], ...]:
+        """The states registered at the global scope, each prefix of ``scope_id`` and
+        ``scope_id`` itself, least specific first.
+
+        Resolved values of a state at ``scope_id`` are computed from these states.
+        """
+        return tuple(
+            (ancestor_key, cls._states[ancestor_key])
+            for ancestor_key in cls._normalize_scope_id(scope_id).ancestors()
+            if ancestor_key in cls._states
+        )
+
     @classmethod
     def unregister_scope_and_descendants(cls, scope_id: Optional[str], _skip_snapshot: bool = False) -> int:
         """Unregister an ObjectState and all its descendants from the registry.
@@ -474,8 +507,9 @@ class ObjectStateRegistry:
         # NOTE: Unlike plain unregister(), this is often used for hierarchical deletes.
         # When history is enabled we must preserve removed states for time-travel (undo/redo),
         # otherwise snapshots may reference scopes that can no longer be resurrected.
-        for key in scopes_to_delete:
-            state = cls._states.pop(key)
+        removed = [(key, cls._states.pop(key)) for key in scopes_to_delete]
+        cls._resolve_again_below(scopes_to_delete)
+        for key, state in removed:
             if cls._history_enabled:
                 cls._graveyard[key] = state
                 logger.debug(f"Unregistered ObjectState (cascade): scope={key} (moved to graveyard)")
@@ -669,21 +703,10 @@ class ObjectStateRegistry:
             List of objects from ancestor scopes, ordered least→most specific.
             Each object is from state.object_instance (saved) or state.to_object() (live).
         """
-        scope_key = cls._normalize_scope_id(scope_id)
-
-        # Get objects from ancestor scopes, least-specific to most-specific
-        objects = []
-        for ancestor_key in scope_key.ancestors():
-            state = cls._states.get(ancestor_key)
-            if state:
-                if use_saved:
-                    # Return saved baseline (saved_object handles delegation correctly)
-                    objects.append(state.saved_object)
-                else:
-                    # Return live state with current edits
-                    objects.append(state.to_object(update_delegate=False))
-
-        return objects
+        return [
+            state.saved_object if use_saved else state.to_object(update_delegate=False)
+            for _, state in cls.registered_ancestors(scope_id)
+        ]
 
     @classmethod
     def get_ancestor_objects_with_scopes(
@@ -714,28 +737,20 @@ class ObjectStateRegistry:
         Returns:
             List of (scope_id, object) tuples from ancestor scopes, ordered least→most specific.
         """
-        scope_key = cls._normalize_scope_id(scope_id)
-
-        # Get (scope_id, object) tuples from ancestor scopes
-        results: List[Tuple[str, Any]] = []
-        for ancestor_key in scope_key.ancestors():
-            state = cls._states.get(ancestor_key)
-            if state:
-                # Get object - either with or without delegate sync
-                logger.debug(f"🐛 get_ancestor_objects_with_scopes: Getting object for ancestor_key={ancestor_key!r}, skip_delegate_sync={skip_delegate_sync}, use_saved={use_saved}")
-
-                if use_saved:
-                    # For saved baseline, we want object_instance (the original saved state)
-                    # Not reconstructed, no delegate sync needed
-                    obj = state._extraction_target
-                else:
-                    # For live state, reconstruct from current parameters
-                    # Control whether delegate sync happens
-                    obj = state.to_object(update_delegate=False, sync_delegate=not skip_delegate_sync)
-
-                results.append((ancestor_key, obj))
-
-        return results
+        # Saved: the object as last saved, without delegate sync or reconstruction.
+        # Live: rebuilt from the current parameters; ``skip_delegate_sync`` decides
+        # whether the delegate is synchronised first.
+        return [
+            (
+                ancestor_key,
+                state._extraction_target
+                if use_saved
+                else state.to_object(
+                    update_delegate=False, sync_delegate=not skip_delegate_sync
+                ),
+            )
+            for ancestor_key, state in cls.registered_ancestors(scope_id)
+        ]
 
     # ========== SCOPE + TYPE + FIELD AWARE INVALIDATION ==========