objectstate 4.0.0__tar.gz → 5.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. {objectstate-4.0.0 → objectstate-5.0.0}/.github/badges/coverage.svg +1 -1
  2. objectstate-5.0.0/.verification/lazy-field-read/delivery.md +3 -0
  3. objectstate-5.0.0/.verification/lazy-field-read/fix.plan.json +31 -0
  4. {objectstate-4.0.0 → objectstate-5.0.0}/CHANGELOG.md +15 -0
  5. {objectstate-4.0.0 → objectstate-5.0.0}/PKG-INFO +3 -3
  6. {objectstate-4.0.0 → objectstate-5.0.0}/README.md +1 -1
  7. objectstate-5.0.0/paper.md +159 -0
  8. {objectstate-4.0.0 → objectstate-5.0.0}/pyproject.toml +1 -1
  9. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/__init__.py +1 -1
  10. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/context_manager.py +29 -50
  11. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/field_access.py +20 -5
  12. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/inspection.py +4 -3
  13. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/lazy_factory.py +25 -42
  14. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/object_state.py +68 -161
  15. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/object_state_registry.py +1 -1
  16. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/parameter_structure.py +24 -0
  17. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/transaction_checkpoint.py +2 -2
  18. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_callable_baseline.py +1 -1
  19. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_construction_history.py +3 -3
  20. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_context_manager.py +37 -0
  21. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_field_access.py +37 -0
  22. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_lazy_counterpart_registry.py +1 -1
  23. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_lazy_factory.py +2 -8
  24. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_object_state_update_instance.py +12 -0
  25. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_resolved_values_follow_registered_ancestors.py +4 -0
  26. objectstate-4.0.0/paper.md +0 -177
  27. {objectstate-4.0.0 → objectstate-5.0.0}/.github/workflows/ci.yml +0 -0
  28. {objectstate-4.0.0 → objectstate-5.0.0}/.github/workflows/coverage-pages.yml +0 -0
  29. {objectstate-4.0.0 → objectstate-5.0.0}/.github/workflows/publish.yml +0 -0
  30. {objectstate-4.0.0 → objectstate-5.0.0}/.gitignore +0 -0
  31. {objectstate-4.0.0 → objectstate-5.0.0}/.readthedocs.yaml +0 -0
  32. {objectstate-4.0.0 → objectstate-5.0.0}/BADGE_SETUP.md +0 -0
  33. {objectstate-4.0.0 → objectstate-5.0.0}/LICENSE +0 -0
  34. {objectstate-4.0.0 → objectstate-5.0.0}/docs/.gitignore +0 -0
  35. {objectstate-4.0.0 → objectstate-5.0.0}/docs/Makefile +0 -0
  36. {objectstate-4.0.0 → objectstate-5.0.0}/docs/api/modules.rst +0 -0
  37. {objectstate-4.0.0 → objectstate-5.0.0}/docs/architectural_fixes.rst +0 -0
  38. {objectstate-4.0.0 → objectstate-5.0.0}/docs/architecture.rst +0 -0
  39. {objectstate-4.0.0 → objectstate-5.0.0}/docs/archive/DOCUMENTATION_AUDIT.md +0 -0
  40. {objectstate-4.0.0 → objectstate-5.0.0}/docs/archive/DOCUMENTATION_FIXES.md +0 -0
  41. {objectstate-4.0.0 → objectstate-5.0.0}/docs/archive/README.md +0 -0
  42. {objectstate-4.0.0 → objectstate-5.0.0}/docs/conf.py +0 -0
  43. {objectstate-4.0.0 → objectstate-5.0.0}/docs/examples/atomic_operations.rst +0 -0
  44. {objectstate-4.0.0 → objectstate-5.0.0}/docs/examples/basic.rst +0 -0
  45. {objectstate-4.0.0 → objectstate-5.0.0}/docs/examples/dual_axis.rst +0 -0
  46. {objectstate-4.0.0 → objectstate-5.0.0}/docs/examples/index.rst +0 -0
  47. {objectstate-4.0.0 → objectstate-5.0.0}/docs/examples/ui.rst +0 -0
  48. {objectstate-4.0.0 → objectstate-5.0.0}/docs/index.rst +0 -0
  49. {objectstate-4.0.0 → objectstate-5.0.0}/docs/make.bat +0 -0
  50. {objectstate-4.0.0 → objectstate-5.0.0}/docs/performance/canonical-context-type-resolution-20261005.json +0 -0
  51. {objectstate-4.0.0 → objectstate-5.0.0}/docs/provenance.rst +0 -0
  52. {objectstate-4.0.0 → objectstate-5.0.0}/docs/quickstart.rst +0 -0
  53. {objectstate-4.0.0 → objectstate-5.0.0}/docs/state_management.rst +0 -0
  54. {objectstate-4.0.0 → objectstate-5.0.0}/docs/state_propagation.rst +0 -0
  55. {objectstate-4.0.0 → objectstate-5.0.0}/docs/undo_redo.rst +0 -0
  56. {objectstate-4.0.0 → objectstate-5.0.0}/paper.bib +0 -0
  57. {objectstate-4.0.0 → objectstate-5.0.0}/plans/n_dimensional_inheritance.md +0 -0
  58. {objectstate-4.0.0 → objectstate-5.0.0}/scripts/check_ruff_added_lines.py +0 -0
  59. {objectstate-4.0.0 → objectstate-5.0.0}/scripts/release.py +0 -0
  60. {objectstate-4.0.0 → objectstate-5.0.0}/scripts/update_and_release.py +0 -0
  61. {objectstate-4.0.0 → objectstate-5.0.0}/scripts/update_version.py +0 -0
  62. {objectstate-4.0.0 → objectstate-5.0.0}/scripts/verify_release_ready.py +0 -0
  63. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/codegen.py +0 -0
  64. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/collection_containers.py +0 -0
  65. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/config.py +0 -0
  66. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/construction_binding.py +0 -0
  67. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/docs/configuration_framework.rst +0 -0
  68. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/docs/context_system.rst +0 -0
  69. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/docs/object_state_lifecycle.rst +0 -0
  70. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/dual_axis_resolver.py +0 -0
  71. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/edit_session.py +0 -0
  72. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/global_config.py +0 -0
  73. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/live_context_resolver.py +0 -0
  74. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/object_state_metadata.py +0 -0
  75. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/parameter_owner.py +0 -0
  76. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/parametric_axes.py +0 -0
  77. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/placeholder.py +0 -0
  78. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/reified_generics.py +0 -0
  79. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/resolution_sources.py +0 -0
  80. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/scope_key.py +0 -0
  81. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/snapshot_model.py +0 -0
  82. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/subfield_semantics.py +0 -0
  83. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/time_travel_profile.py +0 -0
  84. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/token_cache.py +0 -0
  85. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/ui_visibility.py +0 -0
  86. {objectstate-4.0.0 → objectstate-5.0.0}/src/objectstate/value_semantics.py +0 -0
  87. {objectstate-4.0.0 → objectstate-5.0.0}/tests/__init__.py +0 -0
  88. {objectstate-4.0.0 → objectstate-5.0.0}/tests/conftest.py +0 -0
  89. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_atomic_block_context.py +0 -0
  90. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_authored_paths.py +0 -0
  91. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_codegen.py +0 -0
  92. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_config.py +0 -0
  93. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_context_failures_surface.py +0 -0
  94. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_global_config.py +0 -0
  95. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_history_persistence.py +0 -0
  96. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_inspection.py +0 -0
  97. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_integration.py +0 -0
  98. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_live_context_resolver_answers.py +0 -0
  99. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_object_state_metadata_contracts.py +0 -0
  100. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_object_state_restore.py +0 -0
  101. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_one_field_resolution.py +0 -0
  102. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_one_holder_of_the_global_config.py +0 -0
  103. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_parameter_owner.py +0 -0
  104. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_parametric_axes.py +0 -0
  105. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_placeholder.py +0 -0
  106. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_registry_subscription.py +0 -0
  107. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_reified_generics.py +0 -0
  108. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_release_readiness.py +0 -0
  109. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_resolution_precedence_order.py +0 -0
  110. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_resolved_change_notifications.py +0 -0
  111. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_scope_key.py +0 -0
  112. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_scopeless_state_resolution.py +0 -0
  113. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_subfield_semantics.py +0 -0
  114. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_timeline_projection.py +0 -0
  115. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_transaction_checkpoint.py +0 -0
  116. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_ui_visible_field_projection.py +0 -0
  117. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_undo_redo_cascade.py +0 -0
  118. {objectstate-4.0.0 → objectstate-5.0.0}/tests/test_value_semantics.py +0 -0
@@ -1 +1 @@
1
- <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>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 83.56%"><title>coverage: 83.56%</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">83.56%</text><text x="865" y="150" fill-opacity=".3" textLength="430">83.56%</text></g><text x="865" y="140" textLength="430">83.56%</text></g></g></svg>
@@ -0,0 +1,3 @@
1
+ FieldProxy follows ParameterStructure's existing admitted paths instead of re-reading dataclass annotations during each attribute access. Containers remain proxies; only leaves resolve through ObjectState. get_resolved_value uses the same extracted child topology instead of scanning every resolved key. No extra value cache.
2
+
3
+ Native application succeeded. One direct native ObjectState control read a nested leaf, edited it through update_parameter, then read its updated value. First attempt omitted set_base_config_type and failed during setup; corrected application initialization passed. No suite, profile, or speed measurement. Toad must consume state.fields instead of reconstructing an object.
@@ -0,0 +1,31 @@
1
+ {
2
+ "recipes": [
3
+ {
4
+ "recipe_id": "read-extracted-field-topology",
5
+ "operations": [
6
+ {
7
+ "operation": "patch_target",
8
+ "file_path": "/home/ts/wt/codex-live--P192--objectstate/src/objectstate/object_state.py",
9
+ "target_qualname": "FieldProxy.__getattr__",
10
+ "replacements": [
11
+ {
12
+ "old_source": " def __getattr__(self, name: str) -> Any:\n \"\"\"Get field value or nested FieldProxy.\n\n Args:\n name: Field name to access\n\n Returns:\n FieldProxy for nested dataclass fields, or resolved value for leaf fields\n \"\"\"\n new_path = f'{self._path}.{name}' if self._path else name\n\n # Get field info from the type\n if not is_dataclass(self._type):\n type_name = getattr(self._type, '__name__', str(self._type))\n raise AttributeError(f\"{type_name} is not a dataclass\")\n\n field_info = None\n for f in dataclass_fields(self._type):\n if f.name == name:\n field_info = f\n break\n\n if field_info is None:\n type_name = getattr(self._type, '__name__', str(self._type))\n raise AttributeError(f\"{type_name} has no field '{name}'\")\n\n # Check if field is a nested dataclass\n field_type = field_info.type\n\n # Handle Optional[DataclassType]\n from typing import Union, get_args, get_origin\n origin = get_origin(field_type)\n if origin is Union:\n args = get_args(field_type)\n if len(args) == 2 and type(None) in args:\n inner_type = next(arg for arg in args if arg is not type(None))\n if is_dataclass(inner_type) and isinstance(inner_type, type):\n return FieldProxy(self._state, new_path, inner_type)\n\n # Handle direct dataclass type\n if isinstance(field_type, type) and is_dataclass(field_type):\n return FieldProxy(self._state, new_path, field_type)\n\n # Leaf field - get resolved value\n return self._state.get_resolved_value(new_path)",
13
+ "new_source": " def __getattr__(self, name: str) -> Any:\n \"\"\"Follow the state's extracted paths; resolve only the requested leaf.\"\"\"\n new_path = f'{self._path}.{name}' if self._path else name\n if new_path not in self._state.parameters:\n raise AttributeError(f\"ObjectState has no field {new_path!r}\")\n structure = self._state.parameter_structure\n if structure.direct_paths.get(DottedFieldPath(new_path)):\n return FieldProxy(self._state, new_path, structure.owner_paths[new_path])\n return self._state.get_resolved_value(new_path)"
14
+ }
15
+ ]
16
+ },
17
+ {
18
+ "operation": "patch_target",
19
+ "file_path": "/home/ts/wt/codex-live--P192--objectstate/src/objectstate/object_state.py",
20
+ "target_qualname": "ObjectState.get_resolved_value",
21
+ "replacements": [
22
+ {
23
+ "old_source": "prefix = f\"{param_name}.\"\n has_subfields = any(key.startswith(prefix) for key in self._live_resolved.keys())",
24
+ "new_source": "has_subfields = bool(self.parameter_structure.direct_paths.get(DottedFieldPath(param_name)))"
25
+ }
26
+ ]
27
+ }
28
+ ]
29
+ }
30
+ ]
31
+ }
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 5.0.0
4
+
5
+ Field addresses own their structure (#61). `DottedFieldPath` gains `parent` and
6
+ `lineage`; `ParameterStructure` gains `path`, `leaf_paths` and `ancestors`.
7
+ Readers that split dotted strings for the parent or leaf name now use these.
8
+
9
+ Removed: `ObjectState.signature_default`. Read the default from the admitted
10
+ declaration in `parameter_structure.declarations` instead.
11
+
12
+ ## 4.0.1
13
+
14
+ Requires `python-introspect>=0.3.0,<0.4` (was `<0.3`). ObjectState does not call
15
+ python-introspect's JSON codec (`to_jsonable`, `dataclass_from_mapping`), so nothing
16
+ it stores or sends changes form.
17
+
3
18
  ## 4.0.0
4
19
 
5
20
  The global config has one holder (#56). While a state whose object is of the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: objectstate
3
- Version: 4.0.0
3
+ Version: 5.0.0
4
4
  Summary: Generic lazy dataclass configuration framework with dual-axis inheritance and contextvars-based resolution
5
5
  Project-URL: Homepage, https://github.com/OpenHCSDev/objectstate
6
6
  Project-URL: Documentation, https://objectstate.readthedocs.io
@@ -22,7 +22,7 @@ Classifier: Topic :: Utilities
22
22
  Requires-Python: >=3.11
23
23
  Requires-Dist: dill>=0.4.0
24
24
  Requires-Dist: pycodify<0.3,>=0.2.0
25
- Requires-Dist: python-introspect<0.3,>=0.2.0
25
+ Requires-Dist: python-introspect<0.4,>=0.3.0
26
26
  Provides-Extra: dev
27
27
  Requires-Dist: black==26.5.1; extra == 'dev'
28
28
  Requires-Dist: mypy==2.3.0; extra == 'dev'
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
37
37
 
38
38
  # objectstate
39
39
 
40
- **Generic lazy dataclass configuration framework with dual-axis inheritance**
40
+ **Editable, resolvable state for any object (dataclasses, callables and other parameterized objects), with lazy resolution and dual-axis inheritance**
41
41
 
42
42
  [![PyPI version](https://badge.fury.io/py/objectstate.svg)](https://badge.fury.io/py/objectstate)
43
43
  [![Documentation Status](https://readthedocs.org/projects/objectstate/badge/?version=latest)](https://objectstate.readthedocs.io/en/latest/?badge=latest)
@@ -1,6 +1,6 @@
1
1
  # objectstate
2
2
 
3
- **Generic lazy dataclass configuration framework with dual-axis inheritance**
3
+ **Editable, resolvable state for any object (dataclasses, callables and other parameterized objects), with lazy resolution and dual-axis inheritance**
4
4
 
5
5
  [![PyPI version](https://badge.fury.io/py/objectstate.svg)](https://badge.fury.io/py/objectstate)
6
6
  [![Documentation Status](https://readthedocs.org/projects/objectstate/badge/?version=latest)](https://objectstate.readthedocs.io/en/latest/?badge=latest)
@@ -0,0 +1,159 @@
1
+ ---
2
+ title: 'ObjectState: A Generic Framework for Hierarchical Configuration Management with Dual-Axis Inheritance and State Tracking'
3
+ tags:
4
+ - Python
5
+ - configuration management
6
+ - dataclasses
7
+ - hierarchical configuration
8
+ - state management
9
+ - undo-redo
10
+ - lazy evaluation
11
+ authors:
12
+ - name: Tristan Simas
13
+ orcid: 0000-0002-6526-3149
14
+ equal-contrib: true
15
+ affiliation: 1
16
+ affiliations:
17
+ - name: McGill University, Montreal, Canada
18
+ index: 1
19
+ date: 13 January 2026
20
+ bibliography: paper.bib
21
+ repository-code: https://github.com/OpenHCSDev/ObjectState
22
+ url: https://objectstate.readthedocs.io
23
+ ---
24
+
25
+ # Summary
26
+
27
+ `ObjectState` manages hierarchical configuration held in Python dataclasses. A field left as `None` is inherited, and its value is resolved along two axes: the scope hierarchy (step, plate, global) and the class hierarchy of the config type (specialized to base). One resolver computes every inherited value and returns it together with its source, the scope and the class that supplied it. On top of that the library keeps an editable state per object with a saved baseline, dirty fields, and an undo/redo history with branches. It needs Python 3.11 or later and three packages (`dill`, `pycodify`, `python-introspect`).
28
+
29
+ # Statement of Need
30
+
31
+ Scientific workflows often require hundreds of parameters shared across nested execution contexts [@Wilson2014]. Traditional approaches either thread parameters explicitly through every call (brittle) or use global state (untestable) [@Martin2008].
32
+
33
+ An interactive editor of such configuration must answer two questions for every field: what value applies here, and which object supplied it. If several code paths answer them (attribute access, a preview, a dirty check, a compiler), the answers can drift apart. ObjectState gives each fact one owner and derives the rest:
34
+
35
+ 1. **Dual-axis inheritance in one stated order**: class first, then scope
36
+ 2. **A source for every resolved value**: the resolver returns the value with the scope and class that supplied it
37
+ 3. **One holder of the global config**: the state registered at the global scope
38
+ 4. **Saved and live state**: a saved baseline per state, with dirty fields derived from it [@Fowler2002]
39
+ 5. **History**: undo/redo over snapshots of all registered states, with branches
40
+ 6. **Lazy dataclasses**: generated dataclasses whose `None` fields resolve on attribute access [@Claessen2000]
41
+
42
+ # State of the Field
43
+
44
+ Hydra [@Yadan2019] composes a hierarchical configuration from files and command-line overrides. pydantic-settings [@Colvin2023] loads and validates settings. Sacred [@Greff2017] configures an experiment, injects parameters into its functions, and records the configuration of each run. MobX [@MobX2023] derives values from observable application state in JavaScript.
45
+
46
+ ObjectState addresses a different part of the problem: configuration that a user edits while the application runs, where a field of one object inherits from objects in enclosing scopes and from fields of base classes, and where the user interface has to show the inherited value, where it comes from, and whether it differs from what was last saved.
47
+
48
+ # Software Design
49
+
50
+ **Lazy dataclass factory**: `LazyDataclassFactory.make_lazy_simple` generates a dataclass whose `__getattribute__` resolves a `None` field in the active context.
51
+
52
+ **One resolver**: `resolve_with_provenance(type, field)` is the one resolution of a field; a single function behind it walks scopes and classes. It returns `ResolvedField(value, source_scope, source_type)`. Attribute access on a lazy dataclass takes `.value` from this result, and `ObjectState` stores the value and the source from the same call. The active context is a stack of layers held in a `contextvars` variable [@Selivanov2017]; each layer is one object and the scope id it was entered under.
53
+
54
+ **Class-first precedence**: for each class in the MRO of the type being read, most specific first, every layer is asked from the innermost scope to the outermost, and the first value that is not `None` wins. A value on a more specific class in an outer scope therefore beats a value on a base class in an inner scope. The repository's tests check this order for every subset of nine (class, scope) sites.
55
+
56
+ **State and registry**: an `ObjectState` holds the flat, editable parameters of one object (nested dataclass fields use dotted paths), a saved baseline, and resolved snapshots of both. `ObjectStateRegistry` maps scope ids such as `"plate::step"` to states and records history.
57
+
58
+ **Resolved values depend on the registry only**: a state resolves against a layer stack built from the global config and the objects of the states registered at the scopes above it. A `config_context` the caller has entered is set aside for that resolution. Each resolved snapshot keeps the objects it was computed from (`ResolutionSources`); every resolved read compares them, by identity, with the objects the state would be given now, and, while the same scopes are registered, resolves again only the unset fields that can inherit a field stored differently. No caller announces a change. A lazy object that no state owns is the other route: plain attribute access on it reads the entered `config_context`.
59
+
60
+ **One holder of the global config**: while a state whose object is of the global config type is registered at scope `""`, 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; editing, saving, restoring, or undoing that state is that change of the global config. Without such a state, the object given to `set_global_config` is both. `set_global_config` is the one call that replaces it from outside; while a state holds it, the call replaces that state's object. There is one global config per config type per process, and the library does no locking.
61
+
62
+ ## Beyond Dataclasses: Callable Support
63
+
64
+ An `ObjectState` can also wrap a function. Its parameters and defaults are read from the signature by `python-introspect`:
65
+
66
+ ```python
67
+ def threshold_image(image=None, threshold: float = 1.0):
68
+ return image
69
+
70
+ state = ObjectState(threshold_image, scope_id="plate::step::function_0")
71
+ state.get_resolved_value("threshold") # 1.0
72
+ state.type_for_path("threshold") # threshold_image
73
+ ```
74
+
75
+ A function's parameters are held in the same flat store and saved baseline as dataclass fields. They do not inherit: a function parameter left as `None` stays `None`. Inheritance applies to fields of lazy dataclasses.
76
+
77
+ ## Provenance Tracking
78
+
79
+ For a field the state does not set itself, `get_provenance` returns the source the resolver reported:
80
+
81
+ ```python
82
+ step.get_provenance("settings.value")
83
+ # ("plate", Settings): the state at scope "plate", read from class Settings
84
+ ```
85
+
86
+ It returns `None` when the state sets the field itself. The scope is `""` for the global config. The sources are stored in a dictionary beside the resolved values and written in the same pass, so a user interface can display an inherited value with its origin and navigate to it.
87
+
88
+ ## Example
89
+
90
+ ```python
91
+ from dataclasses import dataclass, field
92
+ from objectstate import (
93
+ LazyDataclassFactory, ObjectState, ObjectStateRegistry,
94
+ mark_global_config_type, set_base_config_type, set_global_config,
95
+ )
96
+
97
+ @dataclass
98
+ class Settings:
99
+ value: str | None = None # None = inherit
100
+
101
+ @dataclass
102
+ class GlobalConfig:
103
+ settings: Settings = field(default_factory=Settings)
104
+
105
+ mark_global_config_type(GlobalConfig)
106
+ set_base_config_type(GlobalConfig)
107
+ LazySettings = LazyDataclassFactory.make_lazy_simple(Settings)
108
+
109
+ @dataclass
110
+ class Holder: # a plate or a step
111
+ settings: LazySettings = field(default_factory=LazySettings)
112
+
113
+ set_global_config(GlobalConfig, GlobalConfig(settings=Settings(value="global")))
114
+ plate = ObjectState(Holder(settings=LazySettings(value="plate")), scope_id="plate")
115
+ ObjectStateRegistry.register(plate)
116
+ step = ObjectState(Holder(), scope_id="plate::step")
117
+
118
+ step.get_resolved_value("settings.value") # "plate"
119
+ step.get_provenance("settings.value") # ("plate", Settings)
120
+
121
+ for value in ("first", "second"):
122
+ with ObjectStateRegistry.atomic("edit plate", scope_id="plate"):
123
+ plate.update_parameter("settings.value", value)
124
+ step.get_resolved_value("settings.value") # "second"
125
+ step.dirty_fields # {"settings.value"}
126
+
127
+ ObjectStateRegistry.time_travel_back()
128
+ step.get_resolved_value("settings.value") # "first"
129
+ ```
130
+
131
+ The step state is never told that the plate changed. It finds out on its next read.
132
+
133
+ ## Design Principle: None as Sentinel
134
+
135
+ `None` means "inherit":
136
+
137
+ - **Data**: a `None` field of a lazy dataclass is resolved through the scopes and the class MRO
138
+ - **UI**: `LazyDefaultPlaceholderService` formats the inherited value as placeholder text for an empty field
139
+ - **User**: clear a field to inherit; enter a value to override
140
+
141
+ # Research Application
142
+
143
+ ObjectState was developed for OpenHCS (Open High-Content Screening), an open-source platform for automated microscopy image analysis. OpenHCS registers one state for its global pipeline configuration at scope `""`, and states for each plate, pipeline, step, and step function at scopes below it. A step that leaves a field unset inherits it from the states registered above it and then from the global configuration, without the value being passed through the calls in between.
144
+
145
+ **Interactive parameter tuning**: when a user clears a field, the form shows the inherited value as a placeholder, and the help control of the field reads `get_provenance` to find the source.
146
+
147
+ **Undo and branches**: undo and redo call the registry's `time_travel_back` and `time_travel_forward`. An edit made after travelling back keeps the abandoned future as an automatically named branch, so an earlier configuration can be revisited.
148
+
149
+ **Dirty tracking**: a field is dirty when its live and saved resolved values differ, so a step is also marked when an unsaved edit of its plate changes what the step inherits.
150
+
151
+ # Acknowledgments
152
+
153
+ This work was supported in part by the Fournier lab at the Montreal Neurological Institute, McGill University. ObjectState was developed within the OpenHCS project before being extracted as a standalone package.
154
+
155
+ # AI Usage Disclosure
156
+
157
+ This paper was drafted with assistance from Claude (Anthropic, claude-sonnet-4-5), which was used to structure the manuscript, synthesize information from the codebase and documentation, generate citations, and format content according to JOSS guidelines. The manuscript was revised for release 4.0.0 with Claude (claude-opus-5-5), which checked each statement against the source. Commits in the repository carry `Co-Authored-By: Claude` trailers where a Claude model assisted with the code, including the commits that introduced the resolution and global-config design described here. Technical content, architectural decisions, and research contributions are the work of the human author.
158
+
159
+ # References
@@ -26,7 +26,7 @@ keywords = ["configuration", "dataclass", "lazy", "inheritance", "contextvars",
26
26
  dependencies = [
27
27
  "dill>=0.4.0",
28
28
  "pycodify>=0.2.0,<0.3",
29
- "python-introspect>=0.2.0,<0.3",
29
+ "python-introspect>=0.3.0,<0.4",
30
30
  ]
31
31
 
32
32
  [project.optional-dependencies]
@@ -206,7 +206,7 @@ __all__ = [
206
206
  'ObjectStateEditSession',
207
207
  ]
208
208
 
209
- __version__ = "4.0.0"
209
+ __version__ = "5.0.0"
210
210
  __author__ = 'OpenHCS Team'
211
211
  __description__ = 'Generic configuration framework for lazy dataclass resolution'
212
212
 
@@ -20,6 +20,7 @@ import contextvars
20
20
  import functools
21
21
  import logging
22
22
  import threading
23
+ from collections import deque
23
24
  from collections.abc import Sequence
24
25
  from contextlib import ExitStack, contextmanager
25
26
  from typing import Any, Dict, get_type_hints
@@ -755,59 +756,37 @@ def _declared_config_fields(dataclass_type: type) -> tuple[tuple[str, type], ...
755
756
 
756
757
 
757
758
  def extract_all_configs(context_obj) -> Dict[type, Any]:
758
- """
759
- Extract all config instances from a context object using type-driven approach.
760
-
761
- A context layer keeps its own result (``ContextLayer.configs``); this function
762
- itself keeps nothing.
763
-
764
- This function leverages dataclass field type annotations to efficiently extract
765
- config instances, avoiding string matching and runtime attribute scanning.
766
-
767
- Args:
768
- context_obj: Object to extract configs from (orchestrator, merged config, etc.)
759
+ """Read every declared nested configuration, retaining its nominal identity.
769
760
 
770
- Returns:
771
- Dict mapping nominal config types to config instances.
761
+ Each stored object is visited once. Repeated paths to the same object are
762
+ shared; different objects claiming the same config type still refuse.
763
+ Stored values are read without invoking lazy resolution in the layer being built.
772
764
  """
773
- if context_obj is None:
774
- return {}
775
-
776
765
  configs: Dict[type, Any] = {}
777
-
778
- # Include the context object itself if it's a dataclass
779
- if is_dataclass(context_obj):
780
- _record_config_instance(configs, context_obj, source="context object")
781
-
782
- # Type-driven extraction: Use dataclass field annotations to find config fields
783
- if is_dataclass(type(context_obj)):
784
- for field_name, declared_type in _declared_config_fields(type(context_obj)):
785
- # Read the stored value: a None field holds no config in this object,
786
- # and resolving it here would ask the context that is being read.
787
- field_value = object.__getattribute__(context_obj, field_name)
788
- if field_value is None:
789
- continue
790
- if not _is_compatible_config_type(field_value, declared_type):
791
- raise TypeError(
792
- f"{type(context_obj).__name__}.{field_name} declares "
793
- f"{declared_type.__name__}, got {type(field_value).__name__}."
794
- )
795
- _record_config_instance(
796
- configs,
797
- field_value,
798
- source=f"{type(context_obj).__name__}.{field_name}",
799
- )
800
-
801
- # For non-dataclass objects (orchestrators, etc.), extract dataclass attributes
802
- else:
803
- _extract_from_object_attributes_typed(context_obj, configs)
804
-
805
- if logger.isEnabledFor(logging.DEBUG):
806
- logger.debug(
807
- "Extracted %d configs: %s",
808
- len(configs),
809
- [config_type.__name__ for config_type in configs],
810
- )
766
+ pending = deque([(context_obj, "context object")])
767
+ visited: set[int] = set()
768
+ while pending:
769
+ current, source = pending.popleft()
770
+ if current is None or id(current) in visited:
771
+ continue
772
+ visited.add(id(current))
773
+ if is_dataclass(current):
774
+ _record_config_instance(configs, current, source=source)
775
+ for field_name, declared_type in _declared_config_fields(type(current)):
776
+ value = object.__getattribute__(current, field_name)
777
+ if value is None:
778
+ continue
779
+ if not _is_compatible_config_type(value, declared_type):
780
+ raise TypeError(
781
+ f"{type(current).__name__}.{field_name} declares "
782
+ f"{declared_type.__name__}, got {type(value).__name__}."
783
+ )
784
+ pending.append((value, f"{source}.{field_name}"))
785
+ else:
786
+ children: Dict[type, Any] = {}
787
+ _extract_from_object_attributes_typed(current, children)
788
+ pending.extend((child, f"{source}.{kind.__name__}")
789
+ for kind, child in children.items())
811
790
  return configs
812
791
 
813
792
 
@@ -29,6 +29,23 @@ class DottedFieldPath:
29
29
 
30
30
  return self.parts[-1] if self.parts else ""
31
31
 
32
+ @property
33
+ def parent(self) -> "DottedFieldPath":
34
+ """The immediate container; a root field and the root both have an empty parent."""
35
+
36
+ return DottedFieldPath(self.value.rpartition(".")[0])
37
+
38
+ @property
39
+ def lineage(self) -> tuple["DottedFieldPath", ...]:
40
+ """This field followed by its parents, nearest first, excluding the empty root."""
41
+
42
+ paths = []
43
+ path = self
44
+ while path.value:
45
+ paths.append(path)
46
+ path = path.parent
47
+ return tuple(paths)
48
+
32
49
  def child(self, field_name: str) -> "DottedFieldPath":
33
50
  if self.value == "":
34
51
  return DottedFieldPath(field_name)
@@ -59,12 +76,10 @@ class DottedFieldPath:
59
76
  """Return the direct dotted child field owned by this path, when one exists."""
60
77
 
61
78
  candidate_value = candidate.value if isinstance(candidate, DottedFieldPath) else candidate
62
- if candidate_value == self.value or not self.contains_path(candidate_value):
63
- return None
64
- remainder = candidate_value[len(self.value):]
65
- if not remainder.startswith("."):
79
+ prefix = f"{self.value}." if self.value else ""
80
+ if not candidate_value.startswith(prefix):
66
81
  return None
67
- child_remainder = remainder[1:]
82
+ child_remainder = candidate_value[len(prefix):]
68
83
  child_name = child_remainder.split(".", 1)[0].split("[", 1)[0]
69
84
  return child_name or None
70
85
 
@@ -6,6 +6,7 @@ import logging
6
6
  from collections.abc import Callable
7
7
  from dataclasses import dataclass
8
8
 
9
+ from objectstate.field_access import DottedFieldPath
9
10
  from objectstate.object_state import ObjectState
10
11
  from objectstate.object_state_registry import ObjectStateRegistry
11
12
 
@@ -96,7 +97,7 @@ class FieldInspection:
96
97
  provenance = FieldProvenance(
97
98
  source_scope_id=source_scope_id,
98
99
  source_type=source_type,
99
- field_name=field_path.rsplit(".", 1)[-1],
100
+ field_name=DottedFieldPath(field_path).field_name,
100
101
  )
101
102
  return cls(
102
103
  state=state,
@@ -141,11 +142,11 @@ class FieldInspection:
141
142
 
142
143
  @property
143
144
  def field_name(self) -> str:
144
- return self.field_path.rsplit(".", 1)[-1]
145
+ return DottedFieldPath(self.field_path).field_name
145
146
 
146
147
  @property
147
148
  def container_path(self) -> str:
148
- return self.field_path.rsplit(".", 1)[0] if "." in self.field_path else ""
149
+ return DottedFieldPath(self.field_path).parent.value
149
150
 
150
151
  @property
151
152
  def raw_value_type(self) -> str:
@@ -1210,8 +1210,23 @@ def create_dataclass_for_editing(dataclass_type: Type[T], source_config: Any, pr
1210
1210
  # Naming configuration
1211
1211
  GLOBAL_CONFIG_PREFIX = "Global"
1212
1212
 
1213
- # Registry to accumulate all decorations before injection
1214
- _pending_injections = {}
1213
+ @dataclass(frozen=True)
1214
+ class ConfigInjection:
1215
+ """An injected config owns its annotation, default and dataclass field tuple."""
1216
+
1217
+ config_class: Type
1218
+ field_name: str
1219
+ nullable: bool = False
1220
+ ui_hidden: bool = False
1221
+
1222
+ def field_tuple(self) -> Tuple[str, object, dataclasses.Field]:
1223
+ metadata = {'ui_hidden': self.ui_hidden}
1224
+ if self.nullable:
1225
+ return self.field_name, Optional[self.config_class], field(default=None, metadata=metadata)
1226
+ return self.field_name, self.config_class, field(default_factory=self.config_class, metadata=metadata)
1227
+
1228
+
1229
+ _pending_injections: Dict[Type, List[ConfigInjection]] = {}
1215
1230
 
1216
1231
  # Preview label registry: Type -> label string
1217
1232
  # Used by UI to auto-discover which configs should appear in list item previews
@@ -1359,12 +1374,7 @@ def create_global_default_decorator(target_config_class: Type):
1359
1374
  The decorator accumulates all decorations, then injects all fields at once
1360
1375
  when the module finishes loading. Also creates lazy versions of all decorated configs.
1361
1376
  """
1362
- target_class_name = target_config_class.__name__
1363
- if target_class_name not in _pending_injections:
1364
- _pending_injections[target_class_name] = {
1365
- 'target_class': target_config_class,
1366
- 'configs_to_inject': []
1367
- }
1377
+ _pending_injections.setdefault(target_config_class, [])
1368
1378
 
1369
1379
  def global_default_decorator(cls=None, *, optional: bool = False, inherit_as_none: bool = True, ui_hidden: bool = False, preview_label: Optional[str] = None, abbreviation: Optional[str] = None, field_abbreviations: Optional[Dict[str, str]] = None, always_viewable_fields: Optional[List[str]] = None):
1370
1380
  """
@@ -1439,13 +1449,8 @@ def create_global_default_decorator(target_config_class: Type):
1439
1449
  # Skip injection for abstract classes (they can't be instantiated)
1440
1450
  # For concrete classes: inject even if ui_hidden (needed for lazy resolution context)
1441
1451
  if not is_abstract:
1442
- _pending_injections[target_class_name]['configs_to_inject'].append({
1443
- 'config_class': actual_cls,
1444
- 'field_name': field_name,
1445
- 'optional': optional, # Store the optional flag
1446
- 'inherit_as_none': inherit_as_none, # Store the inherit_as_none flag
1447
- 'ui_hidden': ui_hidden # Store the ui_hidden flag for field metadata
1448
- })
1452
+ _pending_injections[target_config_class].append(
1453
+ ConfigInjection(actual_cls, field_name, nullable=optional, ui_hidden=ui_hidden))
1449
1454
 
1450
1455
  # Immediately create lazy version of this config (not dependent on injection)
1451
1456
 
@@ -1494,10 +1499,7 @@ def create_global_default_decorator(target_config_class: Type):
1494
1499
 
1495
1500
  def _inject_all_pending_fields():
1496
1501
  """Inject all accumulated fields at once."""
1497
- for target_name, injection_data in _pending_injections.items():
1498
- target_class = injection_data['target_class']
1499
- configs = injection_data['configs_to_inject']
1500
-
1502
+ for target_class, configs in _pending_injections.items():
1501
1503
  if configs: # Only inject if there are configs to inject
1502
1504
  _inject_multiple_fields_into_dataclass(target_class, configs)
1503
1505
 
@@ -1506,7 +1508,7 @@ def _camel_to_snake(name: str) -> str:
1506
1508
  s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
1507
1509
  return re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
1508
1510
 
1509
- def _inject_multiple_fields_into_dataclass(target_class: Type, configs: List[Dict]) -> None:
1511
+ def _inject_multiple_fields_into_dataclass(target_class: Type, configs: List[ConfigInjection]) -> None:
1510
1512
  """Mathematical simplification: Batch field injection with direct dataclass recreation."""
1511
1513
  # Imports moved to top-level
1512
1514
 
@@ -1516,26 +1518,7 @@ def _inject_multiple_fields_into_dataclass(target_class: Type, configs: List[Dic
1516
1518
  for f in fields(target_class)
1517
1519
  ]
1518
1520
 
1519
- # Mathematical simplification: Unified field construction with algebraic common factors
1520
- def create_field_definition(config):
1521
- """Create field definition with optional and inherit_as_none support."""
1522
- field_type = config['config_class']
1523
- is_optional = config.get('optional', False)
1524
- is_ui_hidden = config.get('ui_hidden', False)
1525
-
1526
- # Algebraic simplification: factor out common default_value logic
1527
- if is_optional:
1528
- field_type = Union[field_type, type(None)]
1529
- default_value = None
1530
- else:
1531
- # CRITICAL: GlobalPipelineConfig needs default_factory to create instances with defaults
1532
- # PipelineConfig (created by make_lazy_simple) automatically gets default=None
1533
- # So we use default_factory here for GlobalPipelineConfig fields
1534
- default_value = field(default_factory=field_type, metadata={'ui_hidden': is_ui_hidden})
1535
-
1536
- return (config['field_name'], field_type, default_value)
1537
-
1538
- all_fields = existing_fields + [create_field_definition(config) for config in configs]
1521
+ all_fields = existing_fields + [config.field_tuple() for config in configs]
1539
1522
 
1540
1523
  # Direct dataclass recreation - fail-loud
1541
1524
  new_class = make_dataclass(
@@ -1570,8 +1553,8 @@ def _inject_multiple_fields_into_dataclass(target_class: Type, configs: List[Dic
1570
1553
 
1571
1554
  # Create lazy classes and recreate PipelineConfig inline
1572
1555
  for config in configs:
1573
- lazy_class = LazyDataclassFactory.make_lazy_simple(config['config_class'])
1574
- _register_lazy_class(lazy_class, lazy_class.__name__, config['config_class'].__module__)
1556
+ lazy_class = LazyDataclassFactory.make_lazy_simple(config.config_class)
1557
+ _register_lazy_class(lazy_class, lazy_class.__name__, config.config_class.__module__)
1575
1558
 
1576
1559
  # Create lazy version of the updated global config itself with proper naming
1577
1560
  # Global configs must start with GLOBAL_CONFIG_PREFIX - fail-loud if not