objectstate 3.0.2__tar.gz → 3.0.4__tar.gz

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

@@ -1 +1 @@
-<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>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 82.63%"><title>coverage: 82.63%</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">82.63%</text><text x="865" y="150" fill-opacity=".3" textLength="430">82.63%</text></g><text x="865" y="140" textLength="430">82.63%</text></g></g></svg>

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objectstate
-Version: 3.0.2
+Version: 3.0.4
 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.2 → objectstate-3.0.4}/docs/architecture.rst

@@ -527,6 +527,9 @@ Sets the **instance** (concrete values) for resolution:
 * Required for lazy resolution to work
 * Internally calls ``set_global_config_for_editing()``
 * Should be called at application startup (GUI) or before pipeline execution
+* Not needed after an edit or a save made through the ``ObjectState`` of the global
+  config: that state stores the live and the saved instance itself
+  (see :doc:`state_propagation`)
 
 **Key Differences:**
 

{objectstate-3.0.2 → objectstate-3.0.4}/docs/provenance.rst

@@ -119,7 +119,9 @@ A ``ResolvedField`` named tuple:
 
 * ``value``: The resolved field value (may be ``None``)
 * ``source_scope``: The scope id of the layer that supplied the value. ``None`` for a layer
-  entered with ``config_context(obj)`` without a ``scope_id``.
+  entered with ``config_context(obj)`` without a ``scope_id``. ``ObjectState.get_provenance``
+  never reports such a layer: a state resolves against the global config and its registered
+  ancestors only (:ref:`state-resolution-inputs`).
 * ``source_type``: The type the value was read from: the container type or one of its bases.
 
 When no layer holds a value, ``value`` is the declared default and the source names the

objectstate-3.0.4/docs/state_propagation.rst

@@ -0,0 +1,169 @@
+State Propagation and Parent Notification
+=========================================
+
+``ObjectState.forward_to_parent_state()`` lets one independently scoped state
+notify a parent state that a conceptual field changed. It is a callback bridge,
+not a second mutation or persistence path.
+
+Scope hierarchy is not dataclass hierarchy
+-------------------------------------------
+
+Nested dataclasses are flattened inside one ``ObjectState`` and updated with a
+dotted path. They do not need parent forwarding:
+
+.. code-block:: python
+
+   from dataclasses import dataclass, field
+
+   from objectstate import ObjectState
+
+   @dataclass
+   class Palette:
+       background: str = "black"
+
+   @dataclass
+   class DisplayConfig:
+       palette: Palette = field(default_factory=Palette)
+
+   state = ObjectState(DisplayConfig(), scope_id="display")
+   state.update_parameter("palette.background", "white")
+
+By contrast, two objects with distinct lifecycles may have independent states
+whose scopes form a parent/child relationship. The child can use its
+``parent_state`` for ancestor context and can notify the parent when the parent
+view owns a summary or preview of that child.
+
+Explicit parent notification
+----------------------------
+
+.. code-block:: python
+
+   from dataclasses import dataclass
+
+   from objectstate import ObjectState
+
+   @dataclass
+   class Collection:
+       summary: str = ""
+
+   @dataclass
+   class Entry:
+       value: int = 0
+
+   parent = ObjectState(Collection(), scope_id="collection")
+   child = ObjectState(
+       Entry(),
+       scope_id="collection::entry_0",
+       parent_state=parent,
+   )
+
+   parent.on_resolved_changed(lambda paths: print(paths))
+   child.forward_to_parent_state("summary")
+   # {'summary'}
+
+The method requires a parent state. It guards against reentrant forwarding and
+calls the parent's resolved-change callbacks with the chosen path. It does not
+write to the parent's ``parameters`` or advance either saved baseline.
+
+Field-path selection
+--------------------
+
+The notification path is selected in this order:
+
+1. the explicit ``field_path`` argument;
+2. the child's internal parent-field binding, when its composing owner set one;
+3. the last ``scope_id`` segment, with a numeric suffix removed.
+
+Prefer an explicit field path at public composition boundaries. The scope-based
+fallback is useful for conventional child scopes such as ``entry_0``, but scope
+naming is not structural dataclass ownership.
+
+Navigation and flashing
+-----------------------
+
+Parent resolved-change callbacks may refresh a summary, request navigation, or
+flash a parent-owned target. Those are view-layer reactions. ObjectState owns
+only the notification and reentrancy contract; UI code remains responsible for
+mapping the reported field path to widgets.
+
+Use parent forwarding when all of the following are true:
+
+* child and parent are independently scoped states;
+* the parent presents information derived from the child; and
+* an ordinary child callback cannot update that parent presentation directly.
+
+For a nested dataclass field in the same state, call ``update_parameter()`` on
+the dotted path instead.
+
+.. _state-resolution-inputs:
+
+What a resolved value is computed from
+--------------------------------------
+
+A resolved value of a state depends only on the state's place in the registered
+hierarchy. It is computed from three things: which states are registered at the
+scopes above it, what each of them stores for the field's config type and field name,
+and what the global config stores. Nothing else is an input. In particular a
+``config_context`` that the caller has entered is not: a state built, read or resolved
+again inside such a block has the values, saved values, reported sources, dirty
+fields and notifications it has outside it, during the block and after it. The state
+resolves against a layer stack of its own (``build_context_stack``) that starts from
+the global config and holds the registered ancestors and the state's object; the
+caller's context is set aside while it does and is active again afterwards. So the
+reported source of a resolved value is always a scope where a state is registered, or
+``""`` for the global config.
+
+This is the only statement of the rule. A lazy config object that no state owns is a
+different route: plain attribute access on it resolves against whatever
+``config_context`` is entered (see ``context_system.rst`` in the package docs), which
+is how a compiler resolves a pipeline's objects.
+
+Each resolved snapshot (live
+and saved) keeps the objects it was computed from (``ResolutionSources``): the global
+config instance of the thread that resolved it and the object of every state
+registered above. Every resolved read (``get_resolved_value``,
+``get_saved_resolved_value``, ``get_provenance``, ``to_resolved_object``,
+``state.fields``, ``dirty_fields``) first compares those objects with the ones the state would be given
+now. When they are the same objects the read answers from the snapshot. When one is
+another object, the two are compared field by field, the way field resolution reads a
+context layer, and only the fields of the state that are unset and can inherit a
+differing ``(config type, field)`` are resolved again. When other scopes have a
+registered state than before, every field is.
+
+So no caller announces a change. Registering, unregistering or replacing an ancestor,
+editing, saving, restoring, undoing or redoing an ancestor's value, and replacing the
+global config with ``set_live_global_config`` / ``set_saved_global_config`` all reach
+a state on its next read, whether the state is registered or not. A registered state
+is also told at once, so its subscribers hear of the change without a read; a state
+that is not registered is referenced by nothing and tells its subscribers on its next
+read.
+
+Limits:
+
+- Objects are compared by identity. A source that is changed in place is not seen.
+  ``ObjectState.to_object`` returns the same function object for a state that wraps a
+  plain function, so states registered below a function-backed state follow its edits
+  only through the registry (that is, when they are registered themselves).
+- The global config is stored per thread. A snapshot follows the global config of the
+  thread that resolved it; a read from another thread answers from the snapshot and
+  does not resolve it again for that thread's global config.
+
+The state of the global config
+------------------------------
+
+The global config is stored per thread, once as edited (live) and once as saved. A
+state whose object is a global config writes that store when its own object changes:
+``update_parameter`` applies the edit to the live global config,
+``mark_saved`` stores the saved object as the saved global config, ``restore_saved``
+stores the saved object as the live one again, ``update_object_instance`` and time
+travel store both. Each is stored before any descendant resolves again, so saving the
+global state is one call: its registered descendants resolve their saved values
+against the object just saved and are told at once.
+
+``set_live_global_config``, ``set_saved_global_config`` and
+``ensure_global_config_context`` (both at once) store a global config where no state
+does it: at startup before a state exists, and in a thread or process that resolves
+plain lazy objects without a registry, such as a compile worker. Calling one with the
+values the global state has just stored, before or after ``mark_saved``, changes
+nothing. A setter tells no state; states find the replaced object on their next read.
+

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

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

{objectstate-3.0.2 → objectstate-3.0.4}/src/objectstate/context_manager.py

@@ -585,13 +585,20 @@ def build_context_stack(
     use_live: bool = True,
 ):
     """
-    Enter every context layer needed to resolve ``object_instance``; leave them on exit.
+    Enter the complete layer stack that resolves ``object_instance``; leave it on exit.
+
+    The stack is built from the arguments and the global config alone. A context the
+    caller has entered is set aside for the duration of the block and is active again
+    after it: none of its layers is below, between or above the layers entered here.
+    This is how an ``ObjectState`` resolves, so a state's resolved values depend on
+    its object, the states registered above it and the global config, and never on
+    where the read was made. A lazy object that no state owns is resolved by plain
+    attribute access against whatever ``config_context`` is entered.
 
     Layers, outermost first:
-    1. The global config, under scope ``""``. ``config_context`` puts it below the
-       first layer entered while no context is active. When ``object_instance`` is
-       itself a global config, a fresh instance of its type holding the declared
-       defaults is entered above it, also under scope ``""``, and masks it.
+    1. The global config, under scope ``""``. When ``object_instance`` is itself a
+       global config, a fresh instance of its type holding the declared defaults is
+       entered above it, also under scope ``""``, and masks it.
     2. Each ancestor, under its own scope id. Global-config ancestors are left out
        because layer 1 already stands for them.
     3. ``object_instance``, under ``current_scope_id``.
@@ -613,6 +620,14 @@ def build_context_stack(
         )
 
     with ExitStack() as stack:
+        # With no context active, the first layer entered starts from the global config.
+        for variable, no_context in (
+            (current_temp_global, None),
+            (context_type_stack, ()),
+            (context_layer_stack, NO_LAYERS),
+        ):
+            stack.callback(variable.reset, variable.set(no_context))
+
         if isinstance(object_instance, GlobalConfigBase):
             enter(stack, type(object_instance)(), "", mask=True)
 

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

@@ -173,16 +173,13 @@ Global config uses thread-local storage for stability:
    _global_config_storage: Dict[Type, threading.local] = {}
    
    def ensure_global_config_context(config_type: Type, config_instance: Any):
-       """Establish global config as base context."""
-       # Store in thread-local
+       """Store the instance as both the live and the saved global config of this thread."""
        set_global_config_for_editing(config_type, config_instance)
-       
-       # Also inject into contextvars base
-       with config_context(config_instance):
-           # Global context now available
-           pass
 
-This hybrid approach uses thread-local for the global base and contextvars for dynamic stacking.
+The global config is the base in thread-local storage; contextvars hold the layers
+stacked on it. When a registered ``ObjectState`` holds the global config, that state
+writes this storage on edit, save and restore (``docs/state_propagation.rst``, "The
+state of the global config").
 
 Resolution Integration
 ---------------------
@@ -268,8 +265,13 @@ No manual cleanup needed - Python's context manager protocol handles it.
 Framework-Agnostic Context Stack Building
 -----------------------------------------
 
-``build_context_stack()`` is a context manager that enters every layer needed to
-resolve one object, and leaves them again when the block ends:
+``build_context_stack()`` is a context manager that enters the complete layer stack
+that resolves one object, and leaves it again when the block ends. It is how an
+``ObjectState`` resolves. The stack is built from the arguments and the global config
+alone: a context the caller has entered is set aside for the duration of the block and
+is active again after it. ``docs/state_propagation.rst`` ("What a resolved value is
+computed from") states the rule this implements; plain attribute access on a lazy
+object, everywhere else on this page, reads the entered context.
 
 .. code-block:: python
 
@@ -292,5 +294,6 @@ Layers are entered outermost first:
 
 Every layer carries a scope id, so ``resolve_with_provenance()`` can name the scope
 that supplied a value. The global layer is the one ``config_context()`` puts below the
-first layer entered while no context is active. Nothing is set until the ``with`` block is entered. A layer
-that cannot be built raises; the block never runs with a layer missing.
+first layer entered while no context is active, which is always the case inside this
+block. Nothing is set until the ``with`` block is entered. A layer that cannot be built
+raises; the block never runs with a layer missing.