objectstate 3.0.3__tar.gz → 4.0.0__tar.gz

{objectstate-3.0.3 → objectstate-4.0.0}/.github/badges/coverage.svg

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

objectstate-4.0.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 4.0.0
+
+The global config has one holder (#56). While a state whose object is of the
+global config type is registered at the global scope (`scope_id=""`), that state
+holds the global config: the live global config is the object its parameters
+describe and the saved one is the object it last saved. While no such state is
+registered, the object given to `set_global_config` is both. The global config is
+one value per process; threads no longer each have their own.
+
+Removed, and what to call instead:
+
+- `ensure_global_config_context(config_type, config)` (also
+  `objectstate.lazy_factory.ensure_global_config_context`): call
+  `set_global_config(config_type, config)`. Not needed at all beside a registered
+  global state: registering the state makes its object the global config.
+- `set_global_config_for_editing(config_type, config)`: call
+  `set_global_config(config_type, config)`.
+- `set_live_global_config(config_type, config)`: with a registered global state,
+  edit the state (`state.update_parameter(path, value)`); the live global config
+  follows. Without one there is no separate live value; call `set_global_config`.
+- `set_saved_global_config(config_type, config)`: with a registered global state,
+  save it (`state.mark_saved()`); to replace the object, live and saved, call
+  `state.update_object_instance(config)` or `set_global_config`. Without one, call
+  `set_global_config`.
+- `get_current_global_config(config_type, use_live=...)`: call
+  `get_live_global_config(config_type)` or `get_saved_global_config(config_type)`.
+- `clear_current_temp_global()`: nothing; no library code leaves the caller's
+  entered context any more. Leave a `config_context` block to leave its context.
+- `objectstate.global_config.GlobalContextValues`: with a registered global state,
+  checkpoint the state (`ObjectStateTransactionCheckpoint.capture(state)` /
+  `.restore(state)`). Without one, keep `get_live_global_config(config_type)` and
+  put it back with `set_global_config`, or `forget_stored_global_config` when it
+  was `None`.
+- `ObjectState.prepare_history_global_context()`: nothing; read
+  `get_live_global_config` / `get_saved_global_config`.
+- `objectstate.lazy_factory.rebuild_lazy_config_with_new_global_reference(...)`:
+  nothing (it had no caller; it copied a lazy config and stored a global config as
+  a side effect).
+- `ObjectStateRegistry._resolve_again_below` is now `resolve_again_below`.
+
+Added: `set_global_config`, `forget_stored_global_config(config_type)` (a session
+reset or a test that must leave nothing stored), `ObjectStateRegistry.global_config_state(config_type)`;
+`get_live_global_config` and `get_saved_global_config` are exported from
+`objectstate`.
+
+Behaviour changes:
+
+- `set_global_config` while a global state is registered replaces that state's
+  object (`update_object_instance`): unsaved edits of the global state are dropped
+  and its descendants are told at once. A call that only repeated what the state
+  already held must be deleted, not kept.
+- `set_global_config` without a global state tells registered states at once (the
+  setters used to tell nobody until the next read).
+- Registering a global state makes its object the global config at once, also when
+  nothing was stored before. Unregistering it makes the global config what
+  `set_global_config` last stored while no state held it (or the declared defaults).
+- Every thread reads the same global config. A thread that used to see the declared
+  defaults because nothing was stored in it now sees the process's global config.
+- Editing, replacing, restoring or time-travelling the global state no longer
+  leaves the caller's entered `config_context`: a block entered before the change
+  keeps the layers it was entered with until it is left.
+- A global state that is not registered no longer changes the global config when it
+  is edited, saved, restored or given another object.
+- `get_live_global_config` returns the object the registered global state builds
+  from its parameters (one object until the next change), not the instance the
+  application first passed in. Compare values, not identity.

{objectstate-3.0.3 → objectstate-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objectstate
-Version: 3.0.3
+Version: 4.0.0
 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
@@ -53,7 +53,7 @@ Description-Content-Type: text/markdown
   - Y-Axis: Sibling inheritance within same context
 - **Contextvars-Based**: Uses Python's `contextvars` for clean context management
 - **UI Integration**: Placeholder text generation for configuration forms
-- **Thread-Safe**: Thread-local global configuration storage
+- **One global config**: held by the registered global state, or stored where no state exists
 - **100% Generic**: No application-specific dependencies
 - **Small dependency surface**: Uses ``python-introspect`` for callable and
   dataclass analysis
@@ -112,7 +112,7 @@ resolution state.
 When using the decorator pattern with `auto_create_decorator`, you need to establish the global configuration context for lazy resolution:
 
 ```python
-from objectstate import ensure_global_config_context
+from objectstate import set_global_config
 
 # After creating your global config instance
 global_config = GlobalPipelineConfig(
@@ -121,15 +121,15 @@ global_config = GlobalPipelineConfig(
 )
 
 # REQUIRED: Establish global config context for lazy resolution
-ensure_global_config_context(GlobalPipelineConfig, global_config)
+set_global_config(GlobalPipelineConfig, global_config)
 
 # Now lazy configs can resolve from the global context
 ```
 
 **Key differences:**
 - `set_base_config_type(MyConfig)`: Sets the **type** (class) for the framework
-- `ensure_global_config_context(GlobalConfig, instance)`: Sets the **instance** (concrete values) for resolution
-- Call `ensure_global_config_context()` at application startup (GUI) or before pipeline execution
+- `set_global_config(GlobalConfig, instance)`: Sets the **instance** (concrete values) for resolution
+- Call `set_global_config()` at application startup (GUI) or before pipeline execution
 
 ## Installation
 

{objectstate-3.0.3 → objectstate-4.0.0}/README.md

@@ -16,7 +16,7 @@
   - Y-Axis: Sibling inheritance within same context
 - **Contextvars-Based**: Uses Python's `contextvars` for clean context management
 - **UI Integration**: Placeholder text generation for configuration forms
-- **Thread-Safe**: Thread-local global configuration storage
+- **One global config**: held by the registered global state, or stored where no state exists
 - **100% Generic**: No application-specific dependencies
 - **Small dependency surface**: Uses ``python-introspect`` for callable and
   dataclass analysis
@@ -75,7 +75,7 @@ resolution state.
 When using the decorator pattern with `auto_create_decorator`, you need to establish the global configuration context for lazy resolution:
 
 ```python
-from objectstate import ensure_global_config_context
+from objectstate import set_global_config
 
 # After creating your global config instance
 global_config = GlobalPipelineConfig(
@@ -84,15 +84,15 @@ global_config = GlobalPipelineConfig(
 )
 
 # REQUIRED: Establish global config context for lazy resolution
-ensure_global_config_context(GlobalPipelineConfig, global_config)
+set_global_config(GlobalPipelineConfig, global_config)
 
 # Now lazy configs can resolve from the global context
 ```
 
 **Key differences:**
 - `set_base_config_type(MyConfig)`: Sets the **type** (class) for the framework
-- `ensure_global_config_context(GlobalConfig, instance)`: Sets the **instance** (concrete values) for resolution
-- Call `ensure_global_config_context()` at application startup (GUI) or before pipeline execution
+- `set_global_config(GlobalConfig, instance)`: Sets the **instance** (concrete values) for resolution
+- Call `set_global_config()` at application startup (GUI) or before pipeline execution
 
 ## Installation
 

{objectstate-3.0.3 → objectstate-4.0.0}/docs/api/modules.rst

@@ -12,7 +12,7 @@ Configuration and lazy types
    Builds an application-specific configuration decorator and related lazy
    types.
 
-``config_context`` and ``ensure_global_config_context``
+``config_context`` and ``set_global_config``
    Install concrete configuration used during resolution.
 
 ``set_base_config_type``

{objectstate-3.0.3 → objectstate-4.0.0}/docs/architecture.rst

@@ -487,8 +487,8 @@ How It Works
 Global Configuration Context
 -----------------------------
 
-Understanding set_base_config_type vs ensure_global_config_context
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Understanding set_base_config_type vs set_global_config
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The framework provides two related but distinct functions:
 
@@ -507,26 +507,27 @@ Sets the **type** (class) for the framework:
 * Required for type validation and registry
 * Does not set any concrete values
 
-**ensure_global_config_context(config_type: Type, instance: Any)**
+**set_global_config(config_type: Type, instance: Any)**
 
 Sets the **instance** (concrete values) for resolution:
 
 .. code-block:: python
 
-   from objectstate import ensure_global_config_context
+   from objectstate import set_global_config
 
    global_config = GlobalPipelineConfig(
        num_workers=8,
        output_dir="/data"
    )
 
-   ensure_global_config_context(GlobalPipelineConfig, global_config)
+   set_global_config(GlobalPipelineConfig, global_config)
 
-* Call after creating global config instance
-* Uses thread-local storage for thread safety
-* Required for lazy resolution to work
-* Internally calls ``set_global_config_for_editing()``
-* Should be called at application startup (GUI) or before pipeline execution
+* Call after creating global config instance, in a process that registers no
+  ``ObjectState`` for it (a script, a compile worker, an execution server)
+* One value per process: every thread reads it
+* Not needed when an ``ObjectState`` of the global config is registered at scope
+  ``""``: that state's object is the global config, live and saved
+  (see :doc:`state_propagation`). Calling it then replaces that state's object.
 
 **Key Differences:**
 
@@ -536,7 +537,7 @@ Sets the **instance** (concrete values) for resolution:
 
    * - Aspect
      - set_base_config_type
-     - ensure_global_config_context
+     - set_global_config
    * - What it sets
      - Type (class)
      - Instance (concrete values)
@@ -546,17 +547,18 @@ Sets the **instance** (concrete values) for resolution:
    * - Purpose
      - Type registration
      - Enable lazy resolution
-   * - Thread safety
-     - Global registry
-     - Thread-local storage
+   * - Scope
+     - One per process
+     - One per process
 
 Thread Safety
 -------------
 
-The framework is fully thread-safe through:
+Threads see:
 
-1. **Thread-local storage** for global configs
+1. **One global config per process**, read by every thread
 2. **ContextVars** for temporary contexts
 3. **Immutable frozen dataclasses** (when using ``frozen=True``)
 
-This makes it safe to use in multi-threaded applications, including web servers and async applications.
+Entered contexts are per thread or task. The global config and the registry are shared
+and not synchronised: keep edits in one thread.

{objectstate-3.0.3 → objectstate-4.0.0}/docs/examples/basic.rst

@@ -174,7 +174,7 @@ Using the decorator pattern for automatic field injection and lazy class generat
 .. code-block:: python
 
    from dataclasses import dataclass
-   from objectstate import auto_create_decorator, ensure_global_config_context
+   from objectstate import auto_create_decorator, set_global_config
 
    # Create global config with auto_create_decorator
    @auto_create_decorator
@@ -213,7 +213,7 @@ Using the decorator pattern for automatic field injection and lazy class generat
    )
 
    # REQUIRED: Establish global context for lazy resolution
-   ensure_global_config_context(GlobalPipelineConfig, global_config)
+   set_global_config(GlobalPipelineConfig, global_config)
 
    # Now you can access injected configs
    print(f"Database: {global_config.database_config.host}:{global_config.database_config.port}")

{objectstate-3.0.3 → objectstate-4.0.0}/docs/index.rst

@@ -19,7 +19,7 @@ Key Features
 
 * **Contextvars-Based**: Uses Python's ``contextvars`` for clean context management
 * **UI Integration**: Placeholder text generation for configuration forms
-* **Thread-Safe**: Thread-local global configuration storage
+* **One global config**: held by the registered global state, or stored where no state exists
 * **100% Generic**: No application-specific dependencies
 * **Small dependency surface**: Uses ``python-introspect`` for signature and
   dataclass analysis

{objectstate-3.0.3 → objectstate-4.0.0}/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.3 → objectstate-4.0.0}/docs/quickstart.rst

@@ -174,7 +174,7 @@ When using the decorator pattern with ``auto_create_decorator``, you need to est
 
    from objectstate import (
        auto_create_decorator,
-       ensure_global_config_context,
+       set_global_config,
    )
    from dataclasses import dataclass
 
@@ -192,7 +192,7 @@ When using the decorator pattern with ``auto_create_decorator``, you need to est
    )
 
    # REQUIRED: Establish global config context
-   ensure_global_config_context(GlobalPipelineConfig, global_config)
+   set_global_config(GlobalPipelineConfig, global_config)
 
    # Now lazy configs can resolve from the global context
 
@@ -200,8 +200,8 @@ Understanding the Difference
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * ``set_base_config_type(MyConfig)``: Sets the **type** (class) for the framework
-* ``ensure_global_config_context(GlobalConfig, instance)``: Sets the **instance** (concrete values) for resolution
-* Call ``ensure_global_config_context()`` at application startup (GUI) or before pipeline execution
+* ``set_global_config(GlobalConfig, instance)``: Sets the **instance** (concrete values) for resolution
+* Call ``set_global_config()`` at application startup (GUI) or before pipeline execution
 
 Complete Example
 ----------------

{objectstate-3.0.3 → objectstate-4.0.0}/docs/state_propagation.rst

@@ -95,17 +95,35 @@ Use parent forwarding when all of the following are true:
 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 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. Each resolved snapshot (live
+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``) first compares those objects with the ones the state would be given
+``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
@@ -114,7 +132,7 @@ 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
+global config with ``set_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
@@ -126,10 +144,47 @@ Limits:
   ``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.
-- A state built or resolved inside a ``config_context`` the caller entered takes that
-  context's layers into its snapshot and keeps them after the block
-  (`issue #53 <https://github.com/OpenHCSDev/ObjectState/issues/53>`_).
+- Nothing is synchronised. Every thread reads the same registry and the same global
+  config, so a thread that edits while another reads must be kept apart by the
+  application (in a GUI: edit in the GUI thread).
+
+The state of the global config
+------------------------------
+
+The global config is the value every resolution starts from. There is one per config
+type per process, read as edited (live) and as saved, and one thing holds it
+(``objectstate.global_config``):
+
+- The state registered at the global scope (``scope_id=""``) whose object is of that
+  type. The live global config is the object its parameters describe
+  (``object_for_resolution()``) and the saved global config is the object it last
+  saved. Nothing copies them anywhere: ``get_live_global_config``,
+  ``get_saved_global_config``, ``config_context`` and every state's resolution ask the
+  registered state. So an edit, a save, a restore, a replaced object, an undo or a
+  redo of that state is that change of the global config, and its registered
+  descendants are told at once.
+- While no such state is registered: the object given to ``set_global_config``. Nothing
+  edits it, so the live and the saved read are the same object. A process without
+  states (a compile worker, an execution server, a script) uses only this.
+
+Registering the global state is all it takes to make its object the global config; no
+``set_global_config`` call is needed beside it. Unregistering it (or travelling to a
+point in history where it was not registered) ends that at once: the global config is
+then again what ``set_global_config`` last stored while no state held it, or the
+declared defaults.
+
+``set_global_config(config_type, config)`` is the one way to replace the global config
+from outside. While a state holds the global config the call is
+``state.update_object_instance(config)``: the state takes the new object as its live
+and saved value (unsaved edits are dropped) and its descendants and their subscribers
+follow. A stored object that disagrees with a registered global state cannot be made.
+
+Threads play no part. The registry is one per process and so is the stored object, so
+a worker thread reads the global config the GUI thread edits, with or without
+``spawn_thread_with_context`` (which copies the entered ``config_context`` layers, not
+the global config, into the new thread).
+
+A ``config_context`` block entered before the global config changes keeps the layers
+it was entered with until it is left.
+
 

{objectstate-3.0.3 → objectstate-4.0.0}/src/objectstate/__init__.py

@@ -9,7 +9,7 @@ Key Features:
 - Dual-axis inheritance (context hierarchy + sibling inheritance)
 - Contextvars-based context management
 - Placeholder text generation for UI
-- Thread-local global configuration storage
+- One global config per process, held by the registered global state
 
 Quick Start:
     >>> from objectstate import (
@@ -47,7 +47,7 @@ Modules:
     - dual_axis_resolver: Dual-axis inheritance resolver
     - context_manager: Contextvars-based context management
     - placeholder: Placeholder text generation for UI
-    - global_config: Thread-local global configuration storage
+    - global_config: The global config and the one thing that holds it
     - config: Framework configuration (pluggable types and behaviors)
 """
 
@@ -58,7 +58,6 @@ from objectstate.lazy_factory import (
     register_lazy_type_mapping,
     get_base_type_for_lazy,
     get_lazy_type_for_base,
-    ensure_global_config_context,
     # Constructor patching for code execution
     patch_lazy_constructors,
     # Global config type checking
@@ -86,7 +85,6 @@ from objectstate.dual_axis_resolver import (
 from objectstate.context_manager import (
     config_context,
     get_current_temp_global,
-    clear_current_temp_global,
     merge_configs,
     extract_all_configs,
     get_base_global_config,
@@ -111,10 +109,8 @@ from objectstate.placeholder import LazyDefaultPlaceholderService
 
 # Global config
 from objectstate.global_config import (
-    get_current_global_config,
-    set_global_config_for_editing,
-    set_saved_global_config,
-    set_live_global_config,
+    set_global_config,
+    forget_stored_global_config,
     get_saved_global_config,
     get_live_global_config,
 )
@@ -155,7 +151,6 @@ __all__ = [
     'register_lazy_type_mapping',
     'get_base_type_for_lazy',
     'get_lazy_type_for_base',
-    'ensure_global_config_context',
     # Constructor patching for code execution
     'patch_lazy_constructors',
     # Global config type checking
@@ -172,7 +167,6 @@ __all__ = [
     # Context
     'config_context',
     'get_current_temp_global',
-    'clear_current_temp_global',
     'merge_configs',
     'extract_all_configs',
     'get_base_global_config',
@@ -182,8 +176,10 @@ __all__ = [
     # Placeholder
     'LazyDefaultPlaceholderService',
     # Global config
-    'get_current_global_config',
-    'set_global_config_for_editing',
+    'set_global_config',
+    'forget_stored_global_config',
+    'get_live_global_config',
+    'get_saved_global_config',
     # Configuration
     'set_base_config_type',
     'get_base_config_type',
@@ -210,7 +206,7 @@ __all__ = [
     'ObjectStateEditSession',
 ]
 
-__version__ = "3.0.3"
+__version__ = "4.0.0"
 __author__ = 'OpenHCS Team'
 __description__ = 'Generic configuration framework for lazy dataclass resolution'
 

{objectstate-3.0.3 → objectstate-4.0.0}/src/objectstate/context_manager.py

@@ -182,7 +182,7 @@ def config_context(
         mask_with_none: If True, None values override/mask base config values, and
                        field resolution does not look at any layer outside this one.
                        If False (default), None values are ignored (normal inheritance).
-                       Use True when editing GlobalPipelineConfig to mask thread-local
+                       Use True when editing GlobalPipelineConfig to mask the
                        loaded instance with static class defaults.
         use_live_global: If True (default), use LIVE global config (UI sees unsaved edits).
                         If False, use SAVED global config (compiler sees saved values).
@@ -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)
 
@@ -650,20 +665,21 @@ def get_base_global_config(use_live: bool = True):
     """
     Get the global config a context starts from when none is active.
 
-    This is the config set with ensure_global_config_context(), or an instance of the
-    base config type holding its declared defaults when none was set. Raises when no
-    base config type is set or its defaults cannot be constructed.
+    This is the global config of the base config type (see ``objectstate.global_config``),
+    or an instance of that type holding its declared defaults when there is none.
+    Raises when no base config type is set or its defaults cannot be constructed.
 
     Args:
         use_live: If True (default), return LIVE config (UI sees unsaved edits).
                  If False, return SAVED config (compiler sees saved values).
     """
     from objectstate.config import get_base_config_type
-    from objectstate.global_config import get_current_global_config
+    from objectstate.global_config import get_live_global_config, get_saved_global_config
 
     base_config_type = get_base_config_type()
 
-    current_global = get_current_global_config(base_config_type, use_live=use_live)
+    read = get_live_global_config if use_live else get_saved_global_config
+    current_global = read(base_config_type)
     if current_global is not None:
         return current_global
 
@@ -683,17 +699,6 @@ def get_current_temp_global():
     return current_temp_global.get(None)
 
 
-def clear_current_temp_global():
-    """
-    Leave the active context without restoring an outer one.
-
-    After this no context is active: lazy fields fall back to their declared
-    defaults until the next ``config_context`` is entered.
-    """
-    current_temp_global.set(None)
-    context_layer_stack.set(NO_LAYERS)
-
-
 # Utility functions for debugging and introspection
 
 def get_context_info() -> Dict[str, Any]:
@@ -884,12 +889,10 @@ def spawn_thread_with_context(
 ):
     """Spawn a thread with current context propagated.
 
-    This ensures thread-local context (like GlobalPipelineConfig from
-    config framework) is accessible in spawned thread.
-
-    Python's threading module creates isolated thread-local storage, so contextvars
-    don't automatically propagate to spawned threads. This utility wraps
-    threading.Thread to propagate the current context using contextvars.copy_context().
+    A new thread starts with no ``config_context`` entered. This starts one with the
+    layers the caller has entered (``contextvars.copy_context()``), so plain lazy
+    objects read in it what they read in the caller. The global config and the
+    registry are one per process and need no copying.
 
     Args:
         target: The function to run in thread