objectstate 1.1.4__tar.gz → 1.1.6__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 (91) hide show
  1. {objectstate-1.1.4 → objectstate-1.1.6}/.github/badges/coverage.svg +1 -1
  2. {objectstate-1.1.4 → objectstate-1.1.6}/PKG-INFO +1 -1
  3. {objectstate-1.1.4 → objectstate-1.1.6}/pyproject.toml +4 -1
  4. {objectstate-1.1.4 → objectstate-1.1.6}/scripts/update_version.py +1 -11
  5. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/__init__.py +1 -1
  6. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/object_state.py +23 -24
  7. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/object_state_registry.py +99 -40
  8. objectstate-1.1.6/tests/test_registry_subscription.py +89 -0
  9. objectstate-1.1.6/tests/test_resolved_change_notifications.py +69 -0
  10. {objectstate-1.1.4 → objectstate-1.1.6}/.github/workflows/ci.yml +0 -0
  11. {objectstate-1.1.4 → objectstate-1.1.6}/.github/workflows/coverage-pages.yml +0 -0
  12. {objectstate-1.1.4 → objectstate-1.1.6}/.github/workflows/publish.yml +0 -0
  13. {objectstate-1.1.4 → objectstate-1.1.6}/.gitignore +0 -0
  14. {objectstate-1.1.4 → objectstate-1.1.6}/.readthedocs.yaml +0 -0
  15. {objectstate-1.1.4 → objectstate-1.1.6}/BADGE_SETUP.md +0 -0
  16. {objectstate-1.1.4 → objectstate-1.1.6}/LICENSE +0 -0
  17. {objectstate-1.1.4 → objectstate-1.1.6}/README.md +0 -0
  18. {objectstate-1.1.4 → objectstate-1.1.6}/docs/.gitignore +0 -0
  19. {objectstate-1.1.4 → objectstate-1.1.6}/docs/Makefile +0 -0
  20. {objectstate-1.1.4 → objectstate-1.1.6}/docs/api/modules.rst +0 -0
  21. {objectstate-1.1.4 → objectstate-1.1.6}/docs/architectural_fixes.rst +0 -0
  22. {objectstate-1.1.4 → objectstate-1.1.6}/docs/architecture.rst +0 -0
  23. {objectstate-1.1.4 → objectstate-1.1.6}/docs/archive/DOCUMENTATION_AUDIT.md +0 -0
  24. {objectstate-1.1.4 → objectstate-1.1.6}/docs/archive/DOCUMENTATION_FIXES.md +0 -0
  25. {objectstate-1.1.4 → objectstate-1.1.6}/docs/archive/README.md +0 -0
  26. {objectstate-1.1.4 → objectstate-1.1.6}/docs/conf.py +0 -0
  27. {objectstate-1.1.4 → objectstate-1.1.6}/docs/examples/atomic_operations.rst +0 -0
  28. {objectstate-1.1.4 → objectstate-1.1.6}/docs/examples/basic.rst +0 -0
  29. {objectstate-1.1.4 → objectstate-1.1.6}/docs/examples/dual_axis.rst +0 -0
  30. {objectstate-1.1.4 → objectstate-1.1.6}/docs/examples/index.rst +0 -0
  31. {objectstate-1.1.4 → objectstate-1.1.6}/docs/examples/ui.rst +0 -0
  32. {objectstate-1.1.4 → objectstate-1.1.6}/docs/index.rst +0 -0
  33. {objectstate-1.1.4 → objectstate-1.1.6}/docs/make.bat +0 -0
  34. {objectstate-1.1.4 → objectstate-1.1.6}/docs/provenance.rst +0 -0
  35. {objectstate-1.1.4 → objectstate-1.1.6}/docs/quickstart.rst +0 -0
  36. {objectstate-1.1.4 → objectstate-1.1.6}/docs/state_management.rst +0 -0
  37. {objectstate-1.1.4 → objectstate-1.1.6}/docs/state_propagation.rst +0 -0
  38. {objectstate-1.1.4 → objectstate-1.1.6}/docs/undo_redo.rst +0 -0
  39. {objectstate-1.1.4 → objectstate-1.1.6}/paper.bib +0 -0
  40. {objectstate-1.1.4 → objectstate-1.1.6}/paper.md +0 -0
  41. {objectstate-1.1.4 → objectstate-1.1.6}/plans/n_dimensional_inheritance.md +0 -0
  42. {objectstate-1.1.4 → objectstate-1.1.6}/scripts/check_ruff_added_lines.py +0 -0
  43. {objectstate-1.1.4 → objectstate-1.1.6}/scripts/release.py +0 -0
  44. {objectstate-1.1.4 → objectstate-1.1.6}/scripts/update_and_release.py +0 -0
  45. {objectstate-1.1.4 → objectstate-1.1.6}/scripts/verify_release_ready.py +0 -0
  46. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/collection_containers.py +0 -0
  47. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/config.py +0 -0
  48. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/context_manager.py +0 -0
  49. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/docs/configuration_framework.rst +0 -0
  50. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/docs/context_system.rst +0 -0
  51. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/docs/object_state_lifecycle.rst +0 -0
  52. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/dual_axis_resolver.py +0 -0
  53. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/edit_session.py +0 -0
  54. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/field_access.py +0 -0
  55. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/global_config.py +0 -0
  56. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/lazy_factory.py +0 -0
  57. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/live_context_resolver.py +0 -0
  58. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/object_state_metadata.py +0 -0
  59. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/parameter_owner.py +0 -0
  60. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/parametric_axes.py +0 -0
  61. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/placeholder.py +0 -0
  62. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/reified_generics.py +0 -0
  63. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/snapshot_model.py +0 -0
  64. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/subfield_semantics.py +0 -0
  65. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/time_travel_profile.py +0 -0
  66. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/token_cache.py +0 -0
  67. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/transaction_checkpoint.py +0 -0
  68. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/ui_visibility.py +0 -0
  69. {objectstate-1.1.4 → objectstate-1.1.6}/src/objectstate/value_semantics.py +0 -0
  70. {objectstate-1.1.4 → objectstate-1.1.6}/tests/__init__.py +0 -0
  71. {objectstate-1.1.4 → objectstate-1.1.6}/tests/conftest.py +0 -0
  72. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_callable_baseline.py +0 -0
  73. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_config.py +0 -0
  74. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_context_manager.py +0 -0
  75. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_field_access.py +0 -0
  76. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_global_config.py +0 -0
  77. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_history_persistence.py +0 -0
  78. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_integration.py +0 -0
  79. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_lazy_factory.py +0 -0
  80. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_object_state_metadata_contracts.py +0 -0
  81. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_object_state_restore.py +0 -0
  82. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_object_state_update_instance.py +0 -0
  83. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_parameter_owner.py +0 -0
  84. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_parametric_axes.py +0 -0
  85. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_placeholder.py +0 -0
  86. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_reified_generics.py +0 -0
  87. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_subfield_semantics.py +0 -0
  88. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_transaction_checkpoint.py +0 -0
  89. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_ui_visible_field_projection.py +0 -0
  90. {objectstate-1.1.4 → objectstate-1.1.6}/tests/test_undo_redo_cascade.py +0 -0
  91. {objectstate-1.1.4 → objectstate-1.1.6}/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: 70.55%"><title>coverage: 70.55%</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="#ea7233"/><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">70.55%</text><text x="865" y="150" fill-opacity=".3" textLength="430">70.55%</text></g><text x="865" y="140" textLength="430">70.55%</text></g></g></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 71.13%"><title>coverage: 71.13%</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="#ea7233"/><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">71.13%</text><text x="865" y="150" fill-opacity=".3" textLength="430">71.13%</text></g><text x="865" y="140" textLength="430">71.13%</text></g></g></svg>
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: objectstate
3
- Version: 1.1.4
3
+ Version: 1.1.6
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
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "objectstate"
7
- version = "1.1.4"
7
+ dynamic = ["version"]
8
8
  description = "Generic lazy dataclass configuration framework with dual-axis inheritance and contextvars-based resolution"
9
9
  authors = [{name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}]
10
10
  license = {text = "MIT"}
@@ -55,6 +55,9 @@ core-metadata-version = "2.4"
55
55
  [tool.hatch.build.targets.sdist]
56
56
  core-metadata-version = "2.4"
57
57
 
58
+ [tool.hatch.version]
59
+ path = "src/objectstate/__init__.py"
60
+
58
61
  [tool.pytest.ini_options]
59
62
  testpaths = ["tests"]
60
63
  python_files = ["test_*.py"]
@@ -74,18 +74,8 @@ def update_version(new_version=None):
74
74
  )
75
75
  init_file.write_text(new_content)
76
76
 
77
- # Update version in pyproject.toml
78
- pyproject_file = Path("pyproject.toml")
79
- content = pyproject_file.read_text()
80
- new_content = re.sub(
81
- r'(version\s*=\s*[\'"])[^\'"]+([\'"])',
82
- rf'\g<1>{new_version}\2',
83
- content
84
- )
85
- pyproject_file.write_text(new_content)
86
-
87
77
  # Commit and push changes
88
- subprocess.run(['git', 'add', 'src/objectstate/__init__.py', 'pyproject.toml'], check=True)
78
+ subprocess.run(['git', 'add', 'src/objectstate/__init__.py'], check=True)
89
79
  subprocess.run(['git', 'commit', '-m', f'bump version to {new_version}'], check=True)
90
80
  subprocess.run(['git', 'push', 'origin', 'main'], check=True)
91
81
 
@@ -216,7 +216,7 @@ __all__ = [
216
216
  'ObjectStateEditSession',
217
217
  ]
218
218
 
219
- __version__ = "1.1.4"
219
+ __version__ = "1.1.6"
220
220
  __author__ = 'OpenHCS Team'
221
221
  __description__ = 'Generic configuration framework for lazy dataclass resolution'
222
222
 
@@ -959,10 +959,9 @@ class ObjectState:
959
959
  changed_semantic_params,
960
960
  pending_parameters,
961
961
  )
962
- value_change_notification_fields = self.notification_fields_for_value_changes(
963
- changed_param_values,
964
- )
965
-
962
+ # Establish the pre-mutation resolved authority even for a state that
963
+ # has not yet been displayed. Raw edits can preserve the resolved value.
964
+ self._ensure_live_resolved(notify_flash=False)
966
965
  ObjectStateRegistry.ensure_baseline_snapshot()
967
966
 
968
967
  # Update state directly (no type conversion - that's VIEW responsibility)
@@ -1063,14 +1062,11 @@ class ObjectState:
1063
1062
  # Increment global token for LiveContextService.collect() cache invalidation
1064
1063
  ObjectStateRegistry.increment_token(notify=False)
1065
1064
 
1066
- # Recompute live cache, then notify once from the materialized sync layer.
1067
- # First-populate states have no prior resolved cache to diff against, so
1068
- # raw changed child paths are the notification/navigation authority for
1069
- # inline dataclass editors.
1065
+ # Raw edits own history/navigation; the resolved delta owns value flashes.
1070
1066
  self._set_last_changed_values(changed_param_values)
1071
1067
  # Sync materialized state (single point for dirty/sig_diff update + notification)
1072
1068
  self._sync_materialized_state(
1073
- changed_value_fields=changed_paths | value_change_notification_fields
1069
+ changed_value_fields=changed_paths
1074
1070
  )
1075
1071
 
1076
1072
  # Record snapshot for time-travel (registry-level for coherent system history)
@@ -1091,7 +1087,7 @@ class ObjectState:
1091
1087
  if snapshot_field:
1092
1088
  ObjectStateRegistry.record_snapshot(f"edit {snapshot_field}", self.scope_id)
1093
1089
 
1094
- return changed_paths | value_change_notification_fields
1090
+ return changed_paths
1095
1091
 
1096
1092
  def get_resolved_value(self, param_name: str) -> Any:
1097
1093
  """Get resolved value for a field from the bulk snapshot.
@@ -1952,13 +1948,12 @@ class ObjectState:
1952
1948
  return changed_fields
1953
1949
  return set()
1954
1950
 
1955
- def _update_signature_diff_fields(self) -> bool:
1956
- """Recompute _signature_diff_fields, return True if changed."""
1951
+ def _update_signature_diff_fields(self) -> set[str]:
1952
+ """Recompute signature differences and retain the changed field paths."""
1957
1953
  new_sig_diff = self._compute_signature_diff_fields()
1958
- if new_sig_diff != self._signature_diff_fields:
1959
- self._signature_diff_fields = new_sig_diff
1960
- return True
1961
- return False
1954
+ changed_fields = new_sig_diff ^ self._signature_diff_fields
1955
+ self._signature_diff_fields = new_sig_diff
1956
+ return changed_fields
1962
1957
 
1963
1958
  def _sync_materialized_state(
1964
1959
  self,
@@ -1975,25 +1970,29 @@ class ObjectState:
1975
1970
 
1976
1971
  Correctness guarantee: All mutation paths call this ONE method.
1977
1972
 
1978
- Flash behavior: Fires on_resolved_changed for fields that changed value
1979
- and fields that changed dirty status. This ensures flash animation
1980
- triggers for edits within an already-dirty value, not just clean/dirty
1981
- transitions.
1973
+ Resolved-value subscribers receive only value changes. Materialized
1974
+ state subscribers also receive dirty/signature transitions, including
1975
+ saving or changing explicitness without changing the resolved value.
1982
1976
  """
1983
1977
  raw_dirty_changed = self._update_raw_dirty()
1984
1978
  dirty_status_changed_fields = self._update_dirty_fields()
1985
- sig_diff_changed = self._update_signature_diff_fields()
1979
+ signature_changed_fields = self._update_signature_diff_fields()
1980
+ value_notification_fields = self._most_specific_notification_fields(
1981
+ changed_value_fields or set()
1982
+ )
1986
1983
  notification_fields = self._most_specific_notification_fields(
1987
- dirty_status_changed_fields | (changed_value_fields or set())
1984
+ dirty_status_changed_fields
1985
+ | signature_changed_fields
1986
+ | value_notification_fields
1988
1987
  )
1989
1988
 
1990
- materialized_changed = raw_dirty_changed or bool(notification_fields) or sig_diff_changed
1989
+ materialized_changed = raw_dirty_changed or bool(notification_fields)
1991
1990
  if materialized_changed:
1992
1991
  ObjectStateRegistry.mark_snapshot_dirty_scope(self.scope_id)
1993
1992
 
1994
1993
  if emit_notifications:
1995
1994
  self._notify_resolved_changed(
1996
- notification_fields,
1995
+ value_notification_fields,
1997
1996
  context="_sync_materialized_state",
1998
1997
  )
1999
1998
 
@@ -18,9 +18,26 @@ if TYPE_CHECKING:
18
18
 
19
19
  TimeTravelStateEntry: TypeAlias = Tuple[str, 'ObjectState']
20
20
  TimeTravelCompleteCallback: TypeAlias = Callable[[List[TimeTravelStateEntry], Optional[str]], None]
21
+ RegistryCallback: TypeAlias = Callable[..., None]
21
22
  logger = logging.getLogger(__name__)
22
23
 
23
24
 
25
+ class ObjectStateRegistrySubscription:
26
+ """Idempotent ownership handle for one registry callback registration."""
27
+
28
+ def __init__(self, release: Callable[[], bool] | None) -> None:
29
+ self._release = release
30
+
31
+ def release(self) -> bool:
32
+ """Release this registration once, returning whether it was active."""
33
+
34
+ release = self._release
35
+ if release is None:
36
+ return False
37
+ self._release = None
38
+ return release()
39
+
40
+
24
41
  @dataclass(frozen=True)
25
42
  class TimeTravelTransaction:
26
43
  """Nominal request to move the registry to one snapshot."""
@@ -139,57 +156,96 @@ class ObjectStateRegistry:
139
156
  _on_history_changed_callbacks: List[Callable[[], None]] = []
140
157
 
141
158
  @classmethod
142
- def add_register_callback(cls, callback: Callable[[str, 'ObjectState'], None]) -> None:
143
- """Subscribe to ObjectState registration events."""
144
- if callback not in cls._on_register_callbacks:
145
- cls._on_register_callbacks.append(callback)
159
+ def add_register_callback(
160
+ cls,
161
+ callback: Callable[[str, 'ObjectState'], None],
162
+ ) -> ObjectStateRegistrySubscription:
163
+ """Subscribe to registration events and return its ownership handle."""
164
+ return cls._subscribe_callback(cls._on_register_callbacks, callback)
146
165
 
147
166
  @classmethod
148
- def remove_register_callback(cls, callback: Callable[[str, 'ObjectState'], None]) -> None:
167
+ def remove_register_callback(
168
+ cls,
169
+ callback: Callable[[str, 'ObjectState'], None],
170
+ ) -> bool:
149
171
  """Unsubscribe from ObjectState registration events."""
150
- if callback in cls._on_register_callbacks:
151
- cls._on_register_callbacks.remove(callback)
172
+ return cls._remove_callback(cls._on_register_callbacks, callback)
152
173
 
153
174
  @classmethod
154
- def add_unregister_callback(cls, callback: Callable[[str, 'ObjectState'], None]) -> None:
155
- """Subscribe to ObjectState unregistration events."""
156
- if callback not in cls._on_unregister_callbacks:
157
- cls._on_unregister_callbacks.append(callback)
175
+ def add_unregister_callback(
176
+ cls,
177
+ callback: Callable[[str, 'ObjectState'], None],
178
+ ) -> ObjectStateRegistrySubscription:
179
+ """Subscribe to unregistration events and return its ownership handle."""
180
+ return cls._subscribe_callback(cls._on_unregister_callbacks, callback)
158
181
 
159
182
  @classmethod
160
- def remove_unregister_callback(cls, callback: Callable[[str, 'ObjectState'], None]) -> None:
183
+ def remove_unregister_callback(
184
+ cls,
185
+ callback: Callable[[str, 'ObjectState'], None],
186
+ ) -> bool:
161
187
  """Unsubscribe from ObjectState unregistration events."""
162
- if callback in cls._on_unregister_callbacks:
163
- cls._on_unregister_callbacks.remove(callback)
188
+ return cls._remove_callback(cls._on_unregister_callbacks, callback)
164
189
 
165
190
  @classmethod
166
- def add_time_travel_complete_callback(cls, callback: TimeTravelCompleteCallback) -> None:
191
+ def add_time_travel_complete_callback(
192
+ cls,
193
+ callback: TimeTravelCompleteCallback,
194
+ ) -> ObjectStateRegistrySubscription:
167
195
  """Subscribe to time-travel completion events.
168
196
 
169
197
  Callback receives (dirty_states, triggering_scope) where:
170
198
  - dirty_states: list of (scope_id, ObjectState) tuples with unsaved changes
171
199
  - triggering_scope: scope_id that triggered the snapshot (may be None)
172
200
  """
173
- if callback not in cls._on_time_travel_complete_callbacks:
174
- cls._on_time_travel_complete_callbacks.append(callback)
201
+ return cls._subscribe_callback(
202
+ cls._on_time_travel_complete_callbacks,
203
+ callback,
204
+ )
175
205
 
176
206
  @classmethod
177
- def remove_time_travel_complete_callback(cls, callback: TimeTravelCompleteCallback) -> None:
207
+ def remove_time_travel_complete_callback(
208
+ cls,
209
+ callback: TimeTravelCompleteCallback,
210
+ ) -> bool:
178
211
  """Unsubscribe from time-travel completion events."""
179
- if callback in cls._on_time_travel_complete_callbacks:
180
- cls._on_time_travel_complete_callbacks.remove(callback)
212
+ return cls._remove_callback(cls._on_time_travel_complete_callbacks, callback)
181
213
 
182
214
  @classmethod
183
- def add_history_changed_callback(cls, callback: Callable[[], None]) -> None:
184
- """Subscribe to history change events (snapshot added or time-travel)."""
185
- if callback not in cls._on_history_changed_callbacks:
186
- cls._on_history_changed_callbacks.append(callback)
215
+ def add_history_changed_callback(
216
+ cls,
217
+ callback: Callable[[], None],
218
+ ) -> ObjectStateRegistrySubscription:
219
+ """Subscribe to history changes and return its ownership handle."""
220
+ return cls._subscribe_callback(cls._on_history_changed_callbacks, callback)
187
221
 
188
222
  @classmethod
189
- def remove_history_changed_callback(cls, callback: Callable[[], None]) -> None:
223
+ def remove_history_changed_callback(cls, callback: Callable[[], None]) -> bool:
190
224
  """Unsubscribe from history change events."""
191
- if callback in cls._on_history_changed_callbacks:
192
- cls._on_history_changed_callbacks.remove(callback)
225
+ return cls._remove_callback(cls._on_history_changed_callbacks, callback)
226
+
227
+ @classmethod
228
+ def _subscribe_callback(
229
+ cls,
230
+ callbacks: list[RegistryCallback],
231
+ callback: RegistryCallback,
232
+ ) -> ObjectStateRegistrySubscription:
233
+ if callback in callbacks:
234
+ return ObjectStateRegistrySubscription(None)
235
+ callbacks.append(callback)
236
+ return ObjectStateRegistrySubscription(
237
+ lambda: cls._remove_callback(callbacks, callback)
238
+ )
239
+
240
+ @staticmethod
241
+ def _remove_callback(
242
+ callbacks: list[RegistryCallback],
243
+ callback: RegistryCallback,
244
+ ) -> bool:
245
+ if callback not in callbacks:
246
+ return False
247
+ callbacks.remove(callback)
248
+ return True
193
249
 
194
250
  @classmethod
195
251
  def _fire_history_changed_callbacks(cls) -> None:
@@ -474,39 +530,42 @@ class ObjectStateRegistry:
474
530
  cls._change_callbacks.remove(cb)
475
531
 
476
532
  @classmethod
477
- def connect_listener(cls, callback: Callable[[], None]) -> None:
533
+ def connect_listener(
534
+ cls,
535
+ callback: Callable[[], None],
536
+ ) -> ObjectStateRegistrySubscription:
478
537
  """Connect a listener callback that's called on any change.
479
538
 
480
539
  The callback should debounce and call collect() to get fresh values.
481
540
  """
482
- if callback not in cls._change_callbacks:
483
- cls._change_callbacks.append(callback)
541
+ subscription = cls._subscribe_callback(cls._change_callbacks, callback)
542
+ if callback in cls._change_callbacks:
484
543
  logger.debug(f"Connected change listener: {callback}")
544
+ return subscription
485
545
 
486
546
  @classmethod
487
- def disconnect_listener(cls, callback: Callable[[], None]) -> None:
547
+ def disconnect_listener(cls, callback: Callable[[], None]) -> bool:
488
548
  """Disconnect a change listener."""
489
- if callback in cls._change_callbacks:
490
- cls._change_callbacks.remove(callback)
549
+ removed = cls._remove_callback(cls._change_callbacks, callback)
550
+ if removed:
491
551
  logger.debug(f"Disconnected change listener: {callback}")
552
+ return removed
492
553
 
493
554
  @classmethod
494
555
  def add_resolved_changed_callback(
495
556
  cls,
496
557
  callback: Callable[[str, Set[str]], None],
497
- ) -> None:
498
- """Subscribe to resolved-value changes from any registered ObjectState."""
499
- if callback not in cls._resolved_changed_callbacks:
500
- cls._resolved_changed_callbacks.append(callback)
558
+ ) -> ObjectStateRegistrySubscription:
559
+ """Subscribe to resolved changes and return its ownership handle."""
560
+ return cls._subscribe_callback(cls._resolved_changed_callbacks, callback)
501
561
 
502
562
  @classmethod
503
563
  def remove_resolved_changed_callback(
504
564
  cls,
505
565
  callback: Callable[[str, Set[str]], None],
506
- ) -> None:
566
+ ) -> bool:
507
567
  """Unsubscribe from registry-wide resolved-value changes."""
508
- if callback in cls._resolved_changed_callbacks:
509
- cls._resolved_changed_callbacks.remove(callback)
568
+ return cls._remove_callback(cls._resolved_changed_callbacks, callback)
510
569
 
511
570
  @classmethod
512
571
  def notify_resolved_changed(
@@ -0,0 +1,89 @@
1
+ """Ownership contracts for ObjectState registry callback subscriptions."""
2
+
3
+ import pytest
4
+
5
+ from objectstate import ObjectStateRegistry
6
+ from objectstate.object_state_registry import ObjectStateRegistrySubscription
7
+
8
+
9
+ @pytest.mark.parametrize(
10
+ ("add", "remove", "callback"),
11
+ (
12
+ (
13
+ ObjectStateRegistry.add_register_callback,
14
+ ObjectStateRegistry.remove_register_callback,
15
+ lambda _scope, _state: None,
16
+ ),
17
+ (
18
+ ObjectStateRegistry.add_unregister_callback,
19
+ ObjectStateRegistry.remove_unregister_callback,
20
+ lambda _scope, _state: None,
21
+ ),
22
+ (
23
+ ObjectStateRegistry.add_time_travel_complete_callback,
24
+ ObjectStateRegistry.remove_time_travel_complete_callback,
25
+ lambda _states, _scope: None,
26
+ ),
27
+ (
28
+ ObjectStateRegistry.add_history_changed_callback,
29
+ ObjectStateRegistry.remove_history_changed_callback,
30
+ lambda: None,
31
+ ),
32
+ (
33
+ ObjectStateRegistry.add_resolved_changed_callback,
34
+ ObjectStateRegistry.remove_resolved_changed_callback,
35
+ lambda _scope, _paths: None,
36
+ ),
37
+ (
38
+ ObjectStateRegistry.connect_listener,
39
+ ObjectStateRegistry.disconnect_listener,
40
+ lambda: None,
41
+ ),
42
+ ),
43
+ )
44
+ def test_registry_callback_axes_return_one_release_handle(
45
+ add,
46
+ remove,
47
+ callback,
48
+ ) -> None:
49
+ subscription = add(callback)
50
+ try:
51
+ assert isinstance(subscription, ObjectStateRegistrySubscription)
52
+ assert subscription.release()
53
+ assert not subscription.release()
54
+ finally:
55
+ remove(callback)
56
+
57
+
58
+ def test_history_callback_subscription_releases_exact_registration() -> None:
59
+ observed = []
60
+
61
+ def observe() -> None:
62
+ observed.append(True)
63
+
64
+ subscription = ObjectStateRegistry.add_history_changed_callback(observe)
65
+ try:
66
+ assert isinstance(subscription, ObjectStateRegistrySubscription)
67
+ ObjectStateRegistry._fire_history_changed_callbacks()
68
+ assert observed == [True]
69
+
70
+ assert subscription.release()
71
+ assert not subscription.release()
72
+ ObjectStateRegistry._fire_history_changed_callbacks()
73
+ assert observed == [True]
74
+ finally:
75
+ ObjectStateRegistry.remove_history_changed_callback(observe)
76
+
77
+
78
+ def test_duplicate_registration_does_not_transfer_existing_ownership() -> None:
79
+ def observe() -> None:
80
+ pass
81
+
82
+ owner = ObjectStateRegistry.add_history_changed_callback(observe)
83
+ duplicate = ObjectStateRegistry.add_history_changed_callback(observe)
84
+ try:
85
+ assert not duplicate.release()
86
+ ObjectStateRegistry._fire_history_changed_callbacks()
87
+ assert owner.release()
88
+ finally:
89
+ ObjectStateRegistry.remove_history_changed_callback(observe)
@@ -0,0 +1,69 @@
1
+ """Resolved-value notifications exclude storage and save-baseline-only changes."""
2
+
3
+ from dataclasses import dataclass
4
+
5
+ import pytest
6
+
7
+ from objectstate import LazyDataclassFactory, ObjectState, ObjectStateRegistry
8
+
9
+
10
+ @dataclass
11
+ class NotificationValues:
12
+ number: int = 3
13
+ maybe: int | None = None
14
+
15
+
16
+ LazyNotificationValues = LazyDataclassFactory.make_lazy_simple(NotificationValues)
17
+
18
+
19
+ @pytest.fixture(autouse=True)
20
+ def registry():
21
+ ObjectStateRegistry.clear()
22
+ yield
23
+ ObjectStateRegistry.clear()
24
+
25
+
26
+ def test_same_resolved_default_changes_storage_without_value_notification():
27
+ state = ObjectState(LazyNotificationValues())
28
+ assert state.get_resolved_value("number") == 3
29
+ values = []
30
+ chrome = []
31
+ chrome_paths = []
32
+ state.on_resolved_changed(lambda paths: values.append(set(paths)))
33
+ state.on_state_changed(lambda paths: chrome.append(state.is_raw_dirty))
34
+ state.on_state_changed(lambda paths: chrome_paths.append(set(paths)))
35
+ assert state.update_parameter("number", 3) == set()
36
+ assert state.parameters["number"] == 3
37
+ state.reset_parameter("number")
38
+ assert state.parameters["number"] is None
39
+ assert state.get_resolved_value("number") == 3
40
+ assert values == []
41
+ assert chrome == [True, False]
42
+ assert chrome_paths == [{"number"}, {"number"}]
43
+
44
+
45
+ @pytest.mark.parametrize("warm", (False, True))
46
+ def test_real_value_change_has_one_notification_even_without_prior_cache_read(warm):
47
+ state = ObjectState(NotificationValues())
48
+ if warm:
49
+ assert state.get_resolved_value("number") == 3
50
+ values = []
51
+ state.on_resolved_changed(lambda paths: values.append(set(paths)))
52
+ assert state.update_parameter("number", 8) == {"number"}
53
+ assert values == [{"number"}]
54
+ assert state.get_resolved_value("number") == 8
55
+
56
+
57
+ def test_mark_saved_updates_dirty_chrome_without_value_notification():
58
+ state = ObjectState(NotificationValues())
59
+ state.update_parameter("number", 8)
60
+ assert state.dirty_fields == {"number"}
61
+ values = []
62
+ chrome = []
63
+ state.on_resolved_changed(lambda paths: values.append(set(paths)))
64
+ state.on_state_changed(lambda paths: chrome.append(set(paths)))
65
+ state.mark_saved()
66
+ assert state.dirty_fields == set()
67
+ assert state.get_resolved_value("number") == 8
68
+ assert values == []
69
+ assert chrome == [{"number"}]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes