Coverage for src/objectstate/__init__.py: 100%

1""" 

2Generic configuration framework for lazy dataclass resolution. 

3 

4This framework provides a complete system for hierarchical configuration management 

5with lazy resolution, dual-axis inheritance, and UI integration. 

6 

7Key Features: 

8- Lazy dataclass factory with dynamic field resolution 

9- Dual-axis inheritance (context hierarchy + sibling inheritance) 

10- Contextvars-based context management 

11- Placeholder text generation for UI 

12- One global config per process, held by the registered global state 

13 

14Quick Start: 

15 >>> from objectstate import ( 

16 ... set_base_config_type, 

17 ... LazyDataclassFactory, 

18 ... config_context, 

19 ... ) 

20 >>> from myapp.config import GlobalConfig 

21 >>>  

22 >>> # Initialize framework 

23 >>> set_base_config_type(GlobalConfig) 

24 >>>  

25 >>> # Create lazy dataclass 

26 >>> LazyStepConfig = LazyDataclassFactory.make_lazy_simple(StepConfig) 

27 >>>  

28 >>> # Use with context 

29 >>> with config_context(pipeline_config): 

30 ... step = LazyStepConfig() 

31 ... # Fields resolve from pipeline_config context 

32 

33Architecture: 

34 The framework uses a dual-axis resolution system: 

35  

36 X-Axis (Context Hierarchy): 

37 Step context → Pipeline context → Global context → Static defaults 

38  

39 Y-Axis (Sibling Inheritance): 

40 Fields within the same context inherit from sibling dataclasses 

41  

42 This enables sophisticated configuration patterns where fields can inherit 

43 from both parent contexts and sibling configurations. 

44 

45Modules: 

46 - lazy_factory: Lazy dataclass factory and decorator system 

47 - dual_axis_resolver: Dual-axis inheritance resolver 

48 - context_manager: Contextvars-based context management 

49 - placeholder: Placeholder text generation for UI 

50 - global_config: The global config and the one thing that holds it 

51 - config: Framework configuration (pluggable types and behaviors) 

52""" 

53 

54# Factory 

55from objectstate.lazy_factory import ( 

56 LazyDataclassFactory, 

57 auto_create_decorator, 

58 register_lazy_type_mapping, 

59 get_base_type_for_lazy, 

60 get_lazy_type_for_base, 

61 # Constructor patching for code execution 

62 patch_lazy_constructors, 

63 # Global config type checking 

64 GlobalConfigBase, 

65 GlobalConfigMeta, 

66 LazyResolutionDataclass, 

67 has_lazy_resolution, 

68 mark_global_config_type, 

69 # Abbreviation decorator for config classes and fields 

70 abbreviation, 

71 is_global_config_type, 

72 is_global_config_instance, 

73 # Raw-value-preserving utilities 

74 replace_raw, 

75 retain_only_authored_paths, 

76) 

77 

78# Resolver 

79from objectstate.dual_axis_resolver import ( 

80 ResolvedField, 

81 resolve_with_provenance, 

82) 

83 

84# Context 

85from objectstate.context_manager import ( 

86 config_context, 

87 get_current_temp_global, 

88 merge_configs, 

89 extract_all_configs, 

90 get_base_global_config, 

91 # Context hierarchy utilities 

92 get_context_type_stack, 

93 get_normalized_stack, 

94 get_types_before_in_stack, 

95 is_ancestor_in_context, 

96 is_same_type_in_context, 

97 # Hierarchy registry (populated by form managers) 

98 register_hierarchy_relationship, 

99 unregister_hierarchy_relationship, 

100 get_ancestors_from_hierarchy, 

101 # Context stack building (framework-agnostic) 

102 build_context_stack, 

103 # Threading utility for context propagation 

104 spawn_thread_with_context, 

105) 

106 

107# Placeholder 

108from objectstate.placeholder import LazyDefaultPlaceholderService 

109 

110# Global config 

111from objectstate.global_config import ( 

112 set_global_config, 

113 forget_stored_global_config, 

114 get_saved_global_config, 

115 get_live_global_config, 

116) 

117 

118# Configuration 

119from objectstate.config import ( 

120 set_base_config_type, 

121 get_base_config_type, 

122) 

123 

124# Live context resolver 

125from objectstate.live_context_resolver import LiveContextResolver 

126 

127# Token cache 

128from objectstate.token_cache import TokenCache, SingleValueTokenCache, CacheKey 

129 

130# Field access authority 

131from objectstate.field_access import DataclassFieldAccess, DottedFieldPath, FieldAccessError 

132from objectstate.parameter_owner import ParameterOwner 

133from objectstate.subfield_semantics import ( 

134 MISSING, 

135 MissingValue, 

136 ObjectStateSubfieldSemantic, 

137 ObjectStateSubfieldSemanticIndex, 

138 StructuralFieldPath, 

139 StructuralPathSegment, 

140 StructuralSegmentKind, 

141 StructuralValuePath, 

142) 

143 

144# ObjectState edit boundary 

145from objectstate.edit_session import ObjectStateEditSession 

146 

147__all__ = [ 

148 # Factory 

149 'LazyDataclassFactory', 

150 'auto_create_decorator', 

151 'register_lazy_type_mapping', 

152 'get_base_type_for_lazy', 

153 'get_lazy_type_for_base', 

154 # Constructor patching for code execution 

155 'patch_lazy_constructors', 

156 # Global config type checking 

157 'GlobalConfigBase', 

158 'GlobalConfigMeta', 

159 'LazyResolutionDataclass', 

160 'has_lazy_resolution', 

161 'mark_global_config_type', 

162 'is_global_config_type', 

163 'is_global_config_instance', 

164 # Resolver 

165 'ResolvedField', 

166 'resolve_with_provenance', 

167 # Context 

168 'config_context', 

169 'get_current_temp_global', 

170 'merge_configs', 

171 'extract_all_configs', 

172 'get_base_global_config', 

173 'get_context_type_stack', 

174 'build_context_stack', 

175 'spawn_thread_with_context', 

176 # Placeholder 

177 'LazyDefaultPlaceholderService', 

178 # Global config 

179 'set_global_config', 

180 'forget_stored_global_config', 

181 'get_live_global_config', 

182 'get_saved_global_config', 

183 # Configuration 

184 'set_base_config_type', 

185 'get_base_config_type', 

186 # Live context resolver 

187 'LiveContextResolver', 

188 # Token cache 

189 'TokenCache', 

190 'SingleValueTokenCache', 

191 'CacheKey', 

192 # Field access authority 

193 'DataclassFieldAccess', 

194 'DottedFieldPath', 

195 'FieldAccessError', 

196 'ParameterOwner', 

197 'MISSING', 

198 'MissingValue', 

199 'ObjectStateSubfieldSemantic', 

200 'ObjectStateSubfieldSemanticIndex', 

201 'StructuralFieldPath', 

202 'StructuralPathSegment', 

203 'StructuralSegmentKind', 

204 'StructuralValuePath', 

205 # ObjectState edit boundary 

206 'ObjectStateEditSession', 

207] 

208 

209__version__ = "5.0.0" 

210__author__ = 'OpenHCS Team' 

211__description__ = 'Generic configuration framework for lazy dataclass resolution' 

212 

213 

214# Object state management 

215from objectstate.object_state_registry import ObjectStateRegistry 

216from objectstate.scope_key import ScopeKey 

217from objectstate.object_state import ObjectState 

218from objectstate.object_state_metadata import ( 

219 ObjectStateMetadataContract, 

220 ObjectStateMetadataContractRegistry, 

221 ObjectStateMetadataStore, 

222) 

223 

224from objectstate.ui_visibility import ( 

225 UIParameterVisibilityPolicy, 

226 UIParameterVisibilityRequest, 

227 UISpecialFieldRegistry, 

228 UIVisibilityRegistry, 

229 has_ui_special_field, 

230 is_ui_hidden_config_candidate, 

231 is_ui_hidden_config_type, 

232 mark_ui_special_fields, 

233 mark_ui_hidden_config, 

234 should_hide_ui_parameter, 

235) 

236from objectstate.value_semantics import semantic_values_equal 

237 

238# Snapshot model for time-travel 

239from objectstate.snapshot_model import Snapshot, StateSnapshot, Timeline 

240from objectstate.transaction_checkpoint import ObjectStateTransactionCheckpoint 

241 

242# Parametric axes 

243from objectstate.parametric_axes import axes_type, get_axes 

244 

245# Reified generics 

246from objectstate.reified_generics import List, Dict, Set, Tuple, Optional 

247 

248# Update __all__ 

249__all__ += [ 

250 # Object state 

251 'ObjectState', 

252 'ObjectStateRegistry', 

253 'ScopeKey', 

254 'retain_only_authored_paths', 

255 'ObjectStateMetadataContract', 

256 'ObjectStateMetadataContractRegistry', 

257 'ObjectStateMetadataStore', 

258 'UIParameterVisibilityPolicy', 

259 'UIParameterVisibilityRequest', 

260 'UISpecialFieldRegistry', 

261 'UIVisibilityRegistry', 

262 'has_ui_special_field', 

263 'is_ui_hidden_config_candidate', 

264 'is_ui_hidden_config_type', 

265 'mark_ui_special_fields', 

266 'mark_ui_hidden_config', 

267 'should_hide_ui_parameter', 

268 'semantic_values_equal', 

269 # Snapshot model 

270 'Snapshot', 

271 'StateSnapshot', 

272 'ObjectStateTransactionCheckpoint', 

273 'Timeline', 

274 # Parametric axes 

275 'axes_type', 

276 'get_axes', 

277 # Reified generics 

278 'List', 

279 'Dict', 

280 'Set', 

281 'Tuple', 

282 'Optional', 

283]