simplibs-object 0.1.0__py3-none-any.whl

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 (580) hide show
  1. simplibs/object/SimpleBase.py +115 -0
  2. simplibs/object/SimpleConstant.py +271 -0
  3. simplibs/object/SimpleObject.py +293 -0
  4. simplibs/object/__init__.py +7 -0
  5. simplibs/object/_core/__init__.py +66 -0
  6. simplibs/object/_core/logic/__init__.py +0 -0
  7. simplibs/object/_core/logic/constant_methods/__init__.py +22 -0
  8. simplibs/object/_core/logic/constant_methods/bool_or_raise_validate_error.py +76 -0
  9. simplibs/object/_core/logic/constant_methods/normalize.py +92 -0
  10. simplibs/object/_core/logic/constant_methods/validate.py +99 -0
  11. simplibs/object/_core/logic/constant_methods/validate_type.py +48 -0
  12. simplibs/object/_core/logic/constant_methods/validations/__init__.py +22 -0
  13. simplibs/object/_core/logic/constant_methods/validations/_extract_clean_code_lines.py +86 -0
  14. simplibs/object/_core/logic/constant_methods/validations/raise_missing_value_error.py +71 -0
  15. simplibs/object/_core/logic/constant_methods/validations/raise_type_error.py +59 -0
  16. simplibs/object/_core/logic/constant_methods/validations/raise_unexpected_validation_error.py +66 -0
  17. simplibs/object/_core/logic/constant_methods/validations/raise_validation_error.py +78 -0
  18. simplibs/object/_core/logic/object_methods/__init__.py +18 -0
  19. simplibs/object/_core/logic/object_methods/_process_calculate_value_params.py +108 -0
  20. simplibs/object/_core/logic/object_methods/calculate_value.py +81 -0
  21. simplibs/object/_core/logic/object_methods/decompose_value.py +91 -0
  22. simplibs/object/_core/logic/object_methods/validations/__init__.py +22 -0
  23. simplibs/object/_core/logic/object_methods/validations/raise_class_not_decomposeable.py +82 -0
  24. simplibs/object/_core/logic/object_methods/validations/raise_duplicate_argument_error.py +77 -0
  25. simplibs/object/_core/logic/object_methods/validations/raise_too_many_positional_args_error.py +81 -0
  26. simplibs/object/_core/logic/object_methods/validations/raise_unknown_parameter_error.py +77 -0
  27. simplibs/object/_core/logic/property_builders/__init__.py +20 -0
  28. simplibs/object/_core/logic/property_builders/create_instance_property.py +66 -0
  29. simplibs/object/_core/logic/property_builders/create_properties_for_inner.py +97 -0
  30. simplibs/object/_core/logic/property_builders/create_value_property.py +98 -0
  31. simplibs/object/_core/logic/property_builders/value_helpers/__init__.py +18 -0
  32. simplibs/object/_core/logic/property_builders/value_helpers/create_value_getter.py +52 -0
  33. simplibs/object/_core/logic/property_builders/value_helpers/create_value_setter.py +95 -0
  34. simplibs/object/_core/logic/property_builders/value_helpers/validations/__init__.py +16 -0
  35. simplibs/object/_core/logic/property_builders/value_helpers/validations/raise_locked_value_error.py +103 -0
  36. simplibs/object/_core/metadata/SimpleBaseMetadata.py +139 -0
  37. simplibs/object/_core/metadata/SimpleConstantMetadata.py +108 -0
  38. simplibs/object/_core/metadata/SimpleMeta.py +214 -0
  39. simplibs/object/_core/metadata/SimpleObjectMetadata.py +165 -0
  40. simplibs/object/_core/metadata/__init__.py +16 -0
  41. simplibs/object/_core/metadata/constants/BASE_CLASS_NAMES.py +23 -0
  42. simplibs/object/_core/metadata/constants/__init__.py +16 -0
  43. simplibs/object/_core/metadata/init_processors/__init__.py +47 -0
  44. simplibs/object/_core/metadata/init_processors/blueprint_path/__init__.py +15 -0
  45. simplibs/object/_core/metadata/init_processors/blueprint_path/calculate_blueprint_path.py +81 -0
  46. simplibs/object/_core/metadata/init_processors/default/__init__.py +17 -0
  47. simplibs/object/_core/metadata/init_processors/default/process_default_for_constant.py +71 -0
  48. simplibs/object/_core/metadata/init_processors/default/validations/__init__.py +19 -0
  49. simplibs/object/_core/metadata/init_processors/default/validations/_exception_info_for_default.py +66 -0
  50. simplibs/object/_core/metadata/init_processors/default/validations/raise_default_is_defined_in_composition.py +78 -0
  51. simplibs/object/_core/metadata/init_processors/default/validations/validate_default_is_defined.py +77 -0
  52. simplibs/object/_core/metadata/init_processors/default/validations/validate_default_matches_annotation.py +93 -0
  53. simplibs/object/_core/metadata/init_processors/inners/__init__.py +15 -0
  54. simplibs/object/_core/metadata/init_processors/inners/process_inners.py +143 -0
  55. simplibs/object/_core/metadata/init_processors/inners/validations/__init__.py +33 -0
  56. simplibs/object/_core/metadata/init_processors/inners/validations/_exception_info_for_inners.py +43 -0
  57. simplibs/object/_core/metadata/init_processors/inners/validations/_get_collision_path.py +45 -0
  58. simplibs/object/_core/metadata/init_processors/inners/validations/validate_collision_within_inners.py +78 -0
  59. simplibs/object/_core/metadata/init_processors/inners/validations/validate_if_collision_with_owner_class.py +66 -0
  60. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inner_is_class.py +58 -0
  61. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inner_is_not_simple_class.py +60 -0
  62. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inner_is_simple_subclass.py +61 -0
  63. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inners_is_defined.py +56 -0
  64. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inners_is_not_empty.py +57 -0
  65. simplibs/object/_core/metadata/init_processors/inners/validations/validate_inners_is_tuple.py +57 -0
  66. simplibs/object/_core/metadata/init_processors/methods/__init__.py +15 -0
  67. simplibs/object/_core/metadata/init_processors/methods/process_classmethod.py +130 -0
  68. simplibs/object/_core/metadata/init_processors/methods/verifiers/__init__.py +16 -0
  69. simplibs/object/_core/metadata/init_processors/methods/verifiers/_exceptions_helpers/__init__.py +17 -0
  70. simplibs/object/_core/metadata/init_processors/methods/verifiers/_exceptions_helpers/exception_info_for_classmethod.py +52 -0
  71. simplibs/object/_core/metadata/init_processors/methods/verifiers/_exceptions_helpers/expected_structure_for_classmethod.py +80 -0
  72. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/__init__.py +15 -0
  73. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/validations/__init__.py +19 -0
  74. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/validations/_convert_annotation_to_type_set.py +38 -0
  75. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/validations/validate_annotations.py +84 -0
  76. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/validations/validate_args_defaults.py +76 -0
  77. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/validations/validate_kwargs_defaults.py +74 -0
  78. simplibs/object/_core/metadata/init_processors/methods/verifiers/annotations_and_defaults/verify_annotations_and_defaults.py +100 -0
  79. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/__init__.py +15 -0
  80. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/__init__.py +15 -0
  81. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/validations/__init__.py +19 -0
  82. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/validations/raise_decompose_unvalide_outcome_length.py +64 -0
  83. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/validations/validate_decompose_unvalide_item_type.py +77 -0
  84. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/validations/validate_decompose_unvalide_item_value.py +72 -0
  85. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/decompose_method/verify_decompose_outcome.py +87 -0
  86. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/validations/__init__.py +17 -0
  87. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/validations/raise_method_raised_exceptions.py +56 -0
  88. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/validations/raise_method_return_unvalide_outcome_type.py +80 -0
  89. simplibs/object/_core/metadata/init_processors/methods/verifiers/calculation/verify_calculation.py +89 -0
  90. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/__init__.py +15 -0
  91. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/_clone_classmethod.py +81 -0
  92. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/validations/__init__.py +19 -0
  93. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/validations/validate_method_is_callable.py +60 -0
  94. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/validations/validate_method_is_classmethod.py +60 -0
  95. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/validations/validate_method_is_defined.py +67 -0
  96. simplibs/object/_core/metadata/init_processors/methods/verifiers/classmethod/verify_classmethod.py +117 -0
  97. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/__init__.py +15 -0
  98. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/validations/__init__.py +19 -0
  99. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/validations/validate_method_has_exact_args_count.py +59 -0
  100. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/validations/validate_method_not_use_param_placeholders.py +66 -0
  101. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/validations/validate_method_param_match_expected.py +61 -0
  102. simplibs/object/_core/metadata/init_processors/methods/verifiers/params/verify_params.py +123 -0
  103. simplibs/object/_core/metadata/init_processors/names/__init__.py +15 -0
  104. simplibs/object/_core/metadata/init_processors/names/_class_name_splitter.py +242 -0
  105. simplibs/object/_core/metadata/init_processors/names/create_names.py +119 -0
  106. simplibs/object/_core/metadata/init_processors/names/validations/__init__.py +19 -0
  107. simplibs/object/_core/metadata/init_processors/names/validations/validate_class_name_has_no_underscores.py +94 -0
  108. simplibs/object/_core/metadata/init_processors/names/validations/validate_class_name_is_ascii.py +95 -0
  109. simplibs/object/_core/metadata/init_processors/names/validations/validate_class_name_is_identifier.py +83 -0
  110. simplibs/object/_core/metadata/init_processors/type/__init__.py +15 -0
  111. simplibs/object/_core/metadata/init_processors/type/process_type.py +117 -0
  112. simplibs/object/_core/metadata/init_processors/type/validations/__init__.py +29 -0
  113. simplibs/object/_core/metadata/init_processors/type/validations/_exception_info_for_type.py +88 -0
  114. simplibs/object/_core/metadata/init_processors/type/validations/raise_union_type_contain_none.py +70 -0
  115. simplibs/object/_core/metadata/init_processors/type/validations/raise_validate_type_is_not_valid.py +92 -0
  116. simplibs/object/_core/metadata/init_processors/type/validations/validate_type_from_tuple_is_not_none.py +94 -0
  117. simplibs/object/_core/metadata/init_processors/type/validations/validate_type_is_defined.py +85 -0
  118. simplibs/object/_core/metadata/init_processors/type/validations/validate_type_is_not_empty.py +93 -0
  119. simplibs/object/_core/metadata/init_processors/type/validations/validate_type_is_not_none.py +87 -0
  120. simplibs/object/_core/metadata/init_processors/type/validations/validate_type_tuple_is_not_nested.py +92 -0
  121. simplibs/object/_core/metadata/instance_builders/__init__.py +55 -0
  122. simplibs/object/_core/metadata/instance_builders/atom_class/InstanceBase.py +77 -0
  123. simplibs/object/_core/metadata/instance_builders/atom_class/__init__.py +16 -0
  124. simplibs/object/_core/metadata/instance_builders/atom_class/helpers/__init__.py +16 -0
  125. simplibs/object/_core/metadata/instance_builders/atom_class/helpers/create_atom_init.py +51 -0
  126. simplibs/object/_core/metadata/instance_builders/atom_class/helpers/create_root_value_setter.py +67 -0
  127. simplibs/object/_core/metadata/instance_builders/atom_class/make_atom_class.py +101 -0
  128. simplibs/object/_core/metadata/instance_builders/composite_class/__init__.py +14 -0
  129. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/__init__.py +20 -0
  130. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/_get_inner_instance_class.py +51 -0
  131. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/create_composite_init.py +74 -0
  132. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/create_properties_for_inners.py +50 -0
  133. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/create_recalculate_inners.py +57 -0
  134. simplibs/object/_core/metadata/instance_builders/composite_class/helpers/create_recalculate_self.py +69 -0
  135. simplibs/object/_core/metadata/instance_builders/composite_class/make_composite_class.py +93 -0
  136. simplibs/object/_core/metadata/instance_builders/instance/__init__.py +17 -0
  137. simplibs/object/_core/metadata/instance_builders/instance/create_instance.py +107 -0
  138. simplibs/object/_core/metadata/instance_builders/instance/helpers/__init__.py +25 -0
  139. simplibs/object/_core/metadata/instance_builders/instance/helpers/_build_combined_init_mixins.py +40 -0
  140. simplibs/object/_core/metadata/instance_builders/instance/helpers/_build_instance_class_dict.py +127 -0
  141. simplibs/object/_core/metadata/instance_builders/instance/helpers/_extend_instance_class.py +59 -0
  142. simplibs/object/_core/metadata/instance_builders/instance/helpers/_resolve_flat_mixins.py +74 -0
  143. simplibs/object/_core/metadata/instance_builders/instance/helpers/_verify_mixin_compatibility.py +83 -0
  144. simplibs/object/_core/metadata/instance_builders/instance/helpers/create_instance_class.py +76 -0
  145. simplibs/object/_core/metadata/instance_builders/instance/helpers/get_base_class.py +53 -0
  146. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/__init__.py +20 -0
  147. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/__init__.py +29 -0
  148. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/raise_mixin_not_allowed_for_composite.py +61 -0
  149. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/raise_mixin_not_allowed_for_constant.py +61 -0
  150. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/raise_mixin_not_allowed_for_immutable.py +61 -0
  151. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/raise_mixin_not_allowed_for_mutable.py +60 -0
  152. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/raise_mixin_not_support_default_value_type.py +66 -0
  153. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/validate_mixin_is_class.py +56 -0
  154. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/mixins_validations/validate_mixin_is_simple_base_subclass.py +60 -0
  155. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/raise_invalide_extend_instance_class_definition.py +62 -0
  156. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/raise_mixin_slot_collision.py +56 -0
  157. simplibs/object/_core/metadata/instance_builders/instance/helpers/validations/raise_mixin_slot_collision_with_base_class.py +56 -0
  158. simplibs/object/_core/metadata/instance_builders/instance/validations/__init__.py +21 -0
  159. simplibs/object/_core/metadata/instance_builders/instance/validations/validate_class_is_not_base_class.py +54 -0
  160. simplibs/object/_core/metadata/instance_builders/instance/validations/validate_hashing_for_immutable_value.py +66 -0
  161. simplibs/object/_core/metadata/instance_builders/instance/validations/validate_param_is_bool.py +47 -0
  162. simplibs/object/_core/metadata/validations/__init__.py +18 -0
  163. simplibs/object/_core/metadata/validations/raise_attribut_allready_set.py +57 -0
  164. simplibs/object/_core/metadata/validations/raise_metadata_is_immutable.py +73 -0
  165. simplibs/object/_core/protocols/__init__.py +118 -0
  166. simplibs/object/_core/protocols/alias_typings/__init__.py +137 -0
  167. simplibs/object/_core/protocols/alias_typings/changes/ChangeTuple.py +5 -0
  168. simplibs/object/_core/protocols/alias_typings/changes/ChangesDict.py +5 -0
  169. simplibs/object/_core/protocols/alias_typings/changes/ChangesTuple.py +8 -0
  170. simplibs/object/_core/protocols/alias_typings/changes/__init__.py +18 -0
  171. simplibs/object/_core/protocols/alias_typings/history/HistoryDict.py +5 -0
  172. simplibs/object/_core/protocols/alias_typings/history/HistoryEntry.py +10 -0
  173. simplibs/object/_core/protocols/alias_typings/history/__init__.py +16 -0
  174. simplibs/object/_core/protocols/alias_typings/inners/InnersMap.py +8 -0
  175. simplibs/object/_core/protocols/alias_typings/inners/InnersTuple.py +8 -0
  176. simplibs/object/_core/protocols/alias_typings/inners/__init__.py +16 -0
  177. simplibs/object/_core/protocols/alias_typings/mixins/MixinsTuple.py +8 -0
  178. simplibs/object/_core/protocols/alias_typings/mixins/__init__.py +14 -0
  179. simplibs/object/_core/protocols/alias_typings/names/NamesSet.py +5 -0
  180. simplibs/object/_core/protocols/alias_typings/names/NamesTuple.py +5 -0
  181. simplibs/object/_core/protocols/alias_typings/names/__init__.py +16 -0
  182. simplibs/object/_core/protocols/alias_typings/nodes/NodeItem.py +9 -0
  183. simplibs/object/_core/protocols/alias_typings/nodes/NodesDict.py +9 -0
  184. simplibs/object/_core/protocols/alias_typings/nodes/NodesIndexMap.py +6 -0
  185. simplibs/object/_core/protocols/alias_typings/nodes/NodesInstanceDict.py +9 -0
  186. simplibs/object/_core/protocols/alias_typings/nodes/NodesPathDict.py +9 -0
  187. simplibs/object/_core/protocols/alias_typings/nodes/NodesTuple.py +8 -0
  188. simplibs/object/_core/protocols/alias_typings/nodes/__init__.py +24 -0
  189. simplibs/object/_core/protocols/alias_typings/paths/PathDict.py +8 -0
  190. simplibs/object/_core/protocols/alias_typings/paths/PathTuple.py +5 -0
  191. simplibs/object/_core/protocols/alias_typings/paths/__init__.py +16 -0
  192. simplibs/object/_core/protocols/alias_typings/snapshots/SnapshotDict.py +5 -0
  193. simplibs/object/_core/protocols/alias_typings/snapshots/SnapshotDiffItem.py +5 -0
  194. simplibs/object/_core/protocols/alias_typings/snapshots/SnapshotDiffTuple.py +8 -0
  195. simplibs/object/_core/protocols/alias_typings/snapshots/SnapshotTuple.py +5 -0
  196. simplibs/object/_core/protocols/alias_typings/snapshots/__init__.py +20 -0
  197. simplibs/object/_core/protocols/alias_typings/state/StateDict.py +5 -0
  198. simplibs/object/_core/protocols/alias_typings/state/__init__.py +14 -0
  199. simplibs/object/_core/protocols/alias_typings/types/ValidTypes.py +6 -0
  200. simplibs/object/_core/protocols/alias_typings/types/__init__.py +14 -0
  201. simplibs/object/_core/protocols/classes/SimpleBaseProtocol.py +25 -0
  202. simplibs/object/_core/protocols/classes/SimpleConstantProtocol.py +54 -0
  203. simplibs/object/_core/protocols/classes/SimpleObjectProtocol.py +50 -0
  204. simplibs/object/_core/protocols/classes/__init__.py +26 -0
  205. simplibs/object/_core/protocols/instance/SimpleConstantInstanceProtocol.py +13 -0
  206. simplibs/object/_core/protocols/instance/SimpleInstanceBaseProtocol.py +24 -0
  207. simplibs/object/_core/protocols/instance/SimpleObjectInstanceProtocol.py +13 -0
  208. simplibs/object/_core/protocols/instance/__init__.py +29 -0
  209. simplibs/object/_core/protocols/instance/core_classes/AtomInstanceProtocol.py +46 -0
  210. simplibs/object/_core/protocols/instance/core_classes/CompositeInstanceProtocol.py +37 -0
  211. simplibs/object/_core/protocols/instance/core_classes/InstanceBaseProtocol.py +28 -0
  212. simplibs/object/_core/protocols/instance/core_classes/__init__.py +19 -0
  213. simplibs/object/_core/protocols/metadata/SimpleBaseMetadataProtocol.py +37 -0
  214. simplibs/object/_core/protocols/metadata/SimpleConstantMetadataProtocol.py +45 -0
  215. simplibs/object/_core/protocols/metadata/SimpleMetaProtocol.py +39 -0
  216. simplibs/object/_core/protocols/metadata/SimpleObjectMetadataProtocol.py +49 -0
  217. simplibs/object/_core/protocols/metadata/__init__.py +28 -0
  218. simplibs/object/_core/protocols/methods/ClassMethodProtocol.py +29 -0
  219. simplibs/object/_core/protocols/methods/LogicSignature.py +20 -0
  220. simplibs/object/_core/protocols/methods/__init__.py +18 -0
  221. simplibs/object/_core/protocols/mixins/__init__.py +120 -0
  222. simplibs/object/_core/protocols/mixins/base_class/SimpleMixinProtocol.py +46 -0
  223. simplibs/object/_core/protocols/mixins/base_class/__init__.py +18 -0
  224. simplibs/object/_core/protocols/mixins/core_mixins/InfrastructureProtocol.py +16 -0
  225. simplibs/object/_core/protocols/mixins/core_mixins/NodesDictsProtocol.py +38 -0
  226. simplibs/object/_core/protocols/mixins/core_mixins/NodesTupleProtocol.py +30 -0
  227. simplibs/object/_core/protocols/mixins/core_mixins/SerializationProtocol.py +55 -0
  228. simplibs/object/_core/protocols/mixins/core_mixins/SnapshotProtocol.py +42 -0
  229. simplibs/object/_core/protocols/mixins/core_mixins/__init__.py +27 -0
  230. simplibs/object/_core/protocols/mixins/dunders/__init__.py +123 -0
  231. simplibs/object/_core/protocols/mixins/dunders/collections/CollectionBaseProtocol.py +37 -0
  232. simplibs/object/_core/protocols/mixins/dunders/collections/CollectionProtocol.py +20 -0
  233. simplibs/object/_core/protocols/mixins/dunders/collections/IterableProtocol.py +37 -0
  234. simplibs/object/_core/protocols/mixins/dunders/collections/MappingProtocol.py +52 -0
  235. simplibs/object/_core/protocols/mixins/dunders/collections/__init__.py +21 -0
  236. simplibs/object/_core/protocols/mixins/dunders/comparison/EqualityProtocol.py +31 -0
  237. simplibs/object/_core/protocols/mixins/dunders/comparison/OrderingProtocol.py +32 -0
  238. simplibs/object/_core/protocols/mixins/dunders/comparison/__init__.py +16 -0
  239. simplibs/object/_core/protocols/mixins/dunders/generics/ClassGetItemProtocol.py +23 -0
  240. simplibs/object/_core/protocols/mixins/dunders/generics/__init__.py +14 -0
  241. simplibs/object/_core/protocols/mixins/dunders/interfaces/CallProtocol.py +26 -0
  242. simplibs/object/_core/protocols/mixins/dunders/interfaces/ContextProtocol.py +38 -0
  243. simplibs/object/_core/protocols/mixins/dunders/interfaces/__init__.py +16 -0
  244. simplibs/object/_core/protocols/mixins/dunders/lifecycles/CopyableProtocol.py +33 -0
  245. simplibs/object/_core/protocols/mixins/dunders/lifecycles/LifecycleProtocol.py +21 -0
  246. simplibs/object/_core/protocols/mixins/dunders/lifecycles/PickleReduceProtocol.py +30 -0
  247. simplibs/object/_core/protocols/mixins/dunders/lifecycles/PickleStateProtocol.py +42 -0
  248. simplibs/object/_core/protocols/mixins/dunders/lifecycles/__init__.py +20 -0
  249. simplibs/object/_core/protocols/mixins/dunders/lifecycles/internal_types/PicklePlan.py +5 -0
  250. simplibs/object/_core/protocols/mixins/dunders/lifecycles/internal_types/__init__.py +14 -0
  251. simplibs/object/_core/protocols/mixins/dunders/numeric/ArithmeticProtocol.py +95 -0
  252. simplibs/object/_core/protocols/mixins/dunders/numeric/BitwiseProtocol.py +79 -0
  253. simplibs/object/_core/protocols/mixins/dunders/numeric/ConversionProtocol.py +57 -0
  254. simplibs/object/_core/protocols/mixins/dunders/numeric/InplaceProtocol.py +66 -0
  255. simplibs/object/_core/protocols/mixins/dunders/numeric/UnaryProtocol.py +35 -0
  256. simplibs/object/_core/protocols/mixins/dunders/numeric/__init__.py +22 -0
  257. simplibs/object/_core/protocols/mixins/dunders/numeric/internal_types/Operator.py +5 -0
  258. simplibs/object/_core/protocols/mixins/dunders/numeric/internal_types/UnaryOperator.py +5 -0
  259. simplibs/object/_core/protocols/mixins/dunders/numeric/internal_types/__init__.py +16 -0
  260. simplibs/object/_core/protocols/mixins/dunders/representation/ValueDisplayProtocol.py +30 -0
  261. simplibs/object/_core/protocols/mixins/dunders/representation/ValueFormattingProtocol.py +42 -0
  262. simplibs/object/_core/protocols/mixins/dunders/representation/__init__.py +16 -0
  263. simplibs/object/_core/protocols/mixins/immutable/ImmutableMethodsProtocol.py +69 -0
  264. simplibs/object/_core/protocols/mixins/immutable/ImmutableMethodsWithInnersProtocol.py +27 -0
  265. simplibs/object/_core/protocols/mixins/immutable/__init__.py +18 -0
  266. simplibs/object/_core/protocols/mixins/numerical/EqualizerProtocol.py +37 -0
  267. simplibs/object/_core/protocols/mixins/numerical/VolumeProtocol.py +32 -0
  268. simplibs/object/_core/protocols/mixins/numerical/__init__.py +17 -0
  269. simplibs/object/_core/protocols/mixins/numerical/internal_types/SteppersMap.py +8 -0
  270. simplibs/object/_core/protocols/mixins/numerical/internal_types/__init__.py +14 -0
  271. simplibs/object/_core/protocols/mixins/numerical/stepper/StepperProtocol.py +95 -0
  272. simplibs/object/_core/protocols/mixins/numerical/stepper/__init__.py +14 -0
  273. simplibs/object/_core/protocols/mixins/numerical/stepper/internal_types/LimitAction.py +5 -0
  274. simplibs/object/_core/protocols/mixins/numerical/stepper/internal_types/StepValue.py +6 -0
  275. simplibs/object/_core/protocols/mixins/numerical/stepper/internal_types/__init__.py +16 -0
  276. simplibs/object/_core/protocols/mixins/properties/InnersPropertyProtocol.py +31 -0
  277. simplibs/object/_core/protocols/mixins/properties/MetaShortcutsProtocol.py +49 -0
  278. simplibs/object/_core/protocols/mixins/properties/__init__.py +17 -0
  279. simplibs/object/_core/protocols/mixins/state/DefaultStateProtocol.py +41 -0
  280. simplibs/object/_core/protocols/mixins/state/DirtyTrackingProtocol.py +61 -0
  281. simplibs/object/_core/protocols/mixins/state/HistoryProtocol.py +112 -0
  282. simplibs/object/_core/protocols/mixins/state/PermissionProtocol.py +35 -0
  283. simplibs/object/_core/protocols/mixins/state/__init__.py +22 -0
  284. simplibs/object/exceptions/SimpleDefinitionError.py +45 -0
  285. simplibs/object/exceptions/SimpleInitializationError.py +43 -0
  286. simplibs/object/exceptions/SimpleRuntimeError.py +50 -0
  287. simplibs/object/exceptions/__init__.py +62 -0
  288. simplibs/object/exceptions/base_exception/SimpleObjectError.py +107 -0
  289. simplibs/object/exceptions/base_exception/__init__.py +19 -0
  290. simplibs/object/mixins/__init__.py +99 -0
  291. simplibs/object/mixins/_common_logic/__init__.py +41 -0
  292. simplibs/object/mixins/_common_logic/constants/__init__.py +27 -0
  293. simplibs/object/mixins/_common_logic/constants/names/HISTORY.py +14 -0
  294. simplibs/object/mixins/_common_logic/constants/names/OWNER_CLASS.py +14 -0
  295. simplibs/object/mixins/_common_logic/constants/names/STEPPER.py +14 -0
  296. simplibs/object/mixins/_common_logic/constants/names/VALUE.py +14 -0
  297. simplibs/object/mixins/_common_logic/constants/names/__init__.py +28 -0
  298. simplibs/object/mixins/_common_logic/constants/sets/FORBIDDEN_NAMES.py +27 -0
  299. simplibs/object/mixins/_common_logic/constants/sets/RESTRICTION_FLAGS.py +18 -0
  300. simplibs/object/mixins/_common_logic/constants/sets/__init__.py +22 -0
  301. simplibs/object/mixins/_common_logic/immutability/__init__.py +28 -0
  302. simplibs/object/mixins/_common_logic/immutability/with_any/__init__.py +17 -0
  303. simplibs/object/mixins/_common_logic/immutability/with_any/utils/__init__.py +22 -0
  304. simplibs/object/mixins/_common_logic/immutability/with_any/utils/get_top_composite_paths.py +142 -0
  305. simplibs/object/mixins/_common_logic/immutability/with_any/utils/process_single_change.py +143 -0
  306. simplibs/object/mixins/_common_logic/immutability/with_any/utils/split_changes.py +142 -0
  307. simplibs/object/mixins/_common_logic/immutability/with_any/utils/split_constants_paths.py +147 -0
  308. simplibs/object/mixins/_common_logic/immutability/with_any/utils/split_constants_paths2.py +142 -0
  309. simplibs/object/mixins/_common_logic/immutability/with_any/utils/validations/__init__.py +23 -0
  310. simplibs/object/mixins/_common_logic/immutability/with_any/utils/validations/raise_split_changes_unknown_name.py +107 -0
  311. simplibs/object/mixins/_common_logic/immutability/with_any/utils/validations/raise_with_any_unknown_name.py +71 -0
  312. simplibs/object/mixins/_common_logic/immutability/with_any/vaidations/__init__.py +24 -0
  313. simplibs/object/mixins/_common_logic/immutability/with_any/vaidations/raise_with_any_changes_is_not_tuple.py +65 -0
  314. simplibs/object/mixins/_common_logic/immutability/with_any/vaidations/raise_with_any_child_composite_mismatch.py +68 -0
  315. simplibs/object/mixins/_common_logic/immutability/with_any/vaidations/raise_with_any_contained_constant_mismatch.py +67 -0
  316. simplibs/object/mixins/_common_logic/immutability/with_any/with_any.py +238 -0
  317. simplibs/object/mixins/_common_logic/immutability/with_composite/__init__.py +17 -0
  318. simplibs/object/mixins/_common_logic/immutability/with_composite/utils/__init__.py +15 -0
  319. simplibs/object/mixins/_common_logic/immutability/with_composite/utils/reacalculate_inners.py +112 -0
  320. simplibs/object/mixins/_common_logic/immutability/with_composite/vaidations/__init__.py +21 -0
  321. simplibs/object/mixins/_common_logic/immutability/with_composite/vaidations/validate_composite_is_decomposeable.py +71 -0
  322. simplibs/object/mixins/_common_logic/immutability/with_composite/vaidations/validate_composite_name_exists.py +71 -0
  323. simplibs/object/mixins/_common_logic/immutability/with_composite/with_composite.py +176 -0
  324. simplibs/object/mixins/_common_logic/immutability/with_constant/__init__.py +17 -0
  325. simplibs/object/mixins/_common_logic/immutability/with_constant/utils/__init__.py +20 -0
  326. simplibs/object/mixins/_common_logic/immutability/with_constant/utils/create_new_instance.py +130 -0
  327. simplibs/object/mixins/_common_logic/immutability/with_constant/utils/create_snapshot_dict.py +83 -0
  328. simplibs/object/mixins/_common_logic/immutability/with_constant/utils/reacalculate_owner_value.py +131 -0
  329. simplibs/object/mixins/_common_logic/immutability/with_constant/vaidations/__init__.py +16 -0
  330. simplibs/object/mixins/_common_logic/immutability/with_constant/vaidations/raise_immutability_constant_not_found.py +93 -0
  331. simplibs/object/mixins/_common_logic/immutability/with_constant/with_constant.py +147 -0
  332. simplibs/object/mixins/_common_logic/immutability/with_constants/__init__.py +17 -0
  333. simplibs/object/mixins/_common_logic/immutability/with_constants/utils/__init__.py +15 -0
  334. simplibs/object/mixins/_common_logic/immutability/with_constants/utils/find_longest_keys.py +112 -0
  335. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/__init__.py +25 -0
  336. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/raise_immutability_batch_constant_not_found.py +94 -0
  337. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/raise_immutability_constants_changes_not_tuple.py +94 -0
  338. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/validate_inner_tuple_has_length_two.py +91 -0
  339. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/validate_inner_tuple_is_tuple.py +99 -0
  340. simplibs/object/mixins/_common_logic/immutability/with_constants/vaidations/validate_inner_tuple_name_is_str.py +90 -0
  341. simplibs/object/mixins/_common_logic/immutability/with_constants/with_constants.py +193 -0
  342. simplibs/object/mixins/base_class/SimpleMixin.py +118 -0
  343. simplibs/object/mixins/base_class/__init__.py +17 -0
  344. simplibs/object/mixins/base_class/_meta/SimpleMixinMeta.py +59 -0
  345. simplibs/object/mixins/base_class/_meta/__init__.py +21 -0
  346. simplibs/object/mixins/base_class/_meta/_verify_mixin_definition.py +161 -0
  347. simplibs/object/mixins/base_class/_meta/validations/__init__.py +34 -0
  348. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_dict_contains_forbidden_attributes.py +101 -0
  349. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_flag_is_not_bool.py +122 -0
  350. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_init_mixins_contains_super_call.py +75 -0
  351. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_only_types_invalid.py +107 -0
  352. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_slots_contain_unvalid_type.py +85 -0
  353. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_slots_contains_forbidden_slot_names.py +102 -0
  354. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_slots_is_not_defined.py +79 -0
  355. simplibs/object/mixins/base_class/_meta/validations/raise_mixin_slots_unsuport_type.py +88 -0
  356. simplibs/object/mixins/core_mixins/Infrastructure.py +49 -0
  357. simplibs/object/mixins/core_mixins/NodesDicts.py +104 -0
  358. simplibs/object/mixins/core_mixins/NodesTuple.py +86 -0
  359. simplibs/object/mixins/core_mixins/Serialization.py +120 -0
  360. simplibs/object/mixins/core_mixins/Snapshot.py +104 -0
  361. simplibs/object/mixins/core_mixins/__init__.py +32 -0
  362. simplibs/object/mixins/core_mixins/_utils/__init__.py +49 -0
  363. simplibs/object/mixins/core_mixins/_utils/nodes_tuple/__init__.py +17 -0
  364. simplibs/object/mixins/core_mixins/_utils/nodes_tuple/_collect_nodes_data.py +131 -0
  365. simplibs/object/mixins/core_mixins/_utils/nodes_tuple/build_nodes_tuple.py +104 -0
  366. simplibs/object/mixins/core_mixins/_utils/serialization/__init__.py +20 -0
  367. simplibs/object/mixins/core_mixins/_utils/serialization/from_dict.py +190 -0
  368. simplibs/object/mixins/core_mixins/_utils/serialization/from_dict_constants.py +151 -0
  369. simplibs/object/mixins/core_mixins/_utils/serialization/to_dict.py +158 -0
  370. simplibs/object/mixins/core_mixins/_utils/serialization/validations/__init__.py +30 -0
  371. simplibs/object/mixins/core_mixins/_utils/serialization/validations/raise_invalid_composite_structure.py +65 -0
  372. simplibs/object/mixins/core_mixins/_utils/serialization/validations/raise_missing_composite_key.py +64 -0
  373. simplibs/object/mixins/core_mixins/_utils/serialization/validations/raise_missing_value_key.py +66 -0
  374. simplibs/object/mixins/core_mixins/_utils/serialization/validations/raise_unvalid_owner_class_mismatch_for_state_dict.py +77 -0
  375. simplibs/object/mixins/core_mixins/_utils/serialization/validations/raise_unvalid_state_dict_input.py +67 -0
  376. simplibs/object/mixins/core_mixins/_utils/snapshot/__init__.py +15 -0
  377. simplibs/object/mixins/core_mixins/_utils/snapshot/compare_snapshots.py +102 -0
  378. simplibs/object/mixins/core_mixins/_utils/snapshot/validations/__init__.py +16 -0
  379. simplibs/object/mixins/core_mixins/_utils/snapshot/validations/raise_snapshot_incompatible_error.py +101 -0
  380. simplibs/object/mixins/dunders/__init__.py +61 -0
  381. simplibs/object/mixins/dunders/collections/CollectionBase.py +129 -0
  382. simplibs/object/mixins/dunders/collections/Iterable.py +81 -0
  383. simplibs/object/mixins/dunders/collections/Mapping.py +131 -0
  384. simplibs/object/mixins/dunders/collections/__init__.py +29 -0
  385. simplibs/object/mixins/dunders/collections/main/Collection.py +47 -0
  386. simplibs/object/mixins/dunders/collections/main/__init__.py +20 -0
  387. simplibs/object/mixins/dunders/comparison/Equality.py +128 -0
  388. simplibs/object/mixins/dunders/comparison/Ordering.py +130 -0
  389. simplibs/object/mixins/dunders/comparison/__init__.py +25 -0
  390. simplibs/object/mixins/dunders/generics/ClassGetItem.py +105 -0
  391. simplibs/object/mixins/dunders/generics/__init__.py +20 -0
  392. simplibs/object/mixins/dunders/interfaces/Call.py +101 -0
  393. simplibs/object/mixins/dunders/interfaces/Context.py +100 -0
  394. simplibs/object/mixins/dunders/interfaces/__init__.py +23 -0
  395. simplibs/object/mixins/dunders/lifecycles/Copyable.py +103 -0
  396. simplibs/object/mixins/dunders/lifecycles/PickleReduce.py +88 -0
  397. simplibs/object/mixins/dunders/lifecycles/PickleState.py +104 -0
  398. simplibs/object/mixins/dunders/lifecycles/__init__.py +29 -0
  399. simplibs/object/mixins/dunders/lifecycles/_utils/__init__.py +20 -0
  400. simplibs/object/mixins/dunders/lifecycles/_utils/rebuild_simple_instance.py +51 -0
  401. simplibs/object/mixins/dunders/lifecycles/main/Lifecycle.py +45 -0
  402. simplibs/object/mixins/dunders/lifecycles/main/__init__.py +20 -0
  403. simplibs/object/mixins/dunders/numeric/Arithmetic.py +195 -0
  404. simplibs/object/mixins/dunders/numeric/Bitwise.py +172 -0
  405. simplibs/object/mixins/dunders/numeric/Conversion.py +149 -0
  406. simplibs/object/mixins/dunders/numeric/Inplace.py +124 -0
  407. simplibs/object/mixins/dunders/numeric/Unary.py +89 -0
  408. simplibs/object/mixins/dunders/numeric/__init__.py +31 -0
  409. simplibs/object/mixins/dunders/numeric/_utils/__init__.py +41 -0
  410. simplibs/object/mixins/dunders/numeric/_utils/_align_operand_type.py +111 -0
  411. simplibs/object/mixins/dunders/numeric/_utils/execute_arithmetic_op.py +157 -0
  412. simplibs/object/mixins/dunders/numeric/_utils/execute_bitwise_op.py +116 -0
  413. simplibs/object/mixins/dunders/numeric/_utils/execute_conversion.py +107 -0
  414. simplibs/object/mixins/dunders/numeric/_utils/execute_inplace_op.py +139 -0
  415. simplibs/object/mixins/dunders/numeric/_utils/execute_unary_op.py +121 -0
  416. simplibs/object/mixins/dunders/representation/ValueDisplay.py +96 -0
  417. simplibs/object/mixins/dunders/representation/ValueFormatting.py +144 -0
  418. simplibs/object/mixins/dunders/representation/__init__.py +24 -0
  419. simplibs/object/mixins/others/__init__.py +48 -0
  420. simplibs/object/mixins/others/immutable/ImmutableMethods.py +142 -0
  421. simplibs/object/mixins/others/immutable/ImmutableMethodsWithInners.py +111 -0
  422. simplibs/object/mixins/others/immutable/__init__.py +24 -0
  423. simplibs/object/mixins/others/immutable/_validations/__init__.py +19 -0
  424. simplibs/object/mixins/others/immutable/_validations/raise_with_changes_input_not_dict.py +60 -0
  425. simplibs/object/mixins/others/numerical/Equalizer.py +129 -0
  426. simplibs/object/mixins/others/numerical/Volume.py +100 -0
  427. simplibs/object/mixins/others/numerical/__init__.py +25 -0
  428. simplibs/object/mixins/others/numerical/_stepper_class/Stepper.py +227 -0
  429. simplibs/object/mixins/others/numerical/_stepper_class/__init__.py +31 -0
  430. simplibs/object/mixins/others/numerical/_stepper_class/methods/__init__.py +35 -0
  431. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/__init__.py +33 -0
  432. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/process_step_value.py +114 -0
  433. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/validations/__init__.py +29 -0
  434. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/validations/raise_stepper_down_limit_reached.py +115 -0
  435. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/validations/raise_stepper_up_limit_reached.py +110 -0
  436. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/verify_down_limit.py +141 -0
  437. simplibs/object/mixins/others/numerical/_stepper_class/methods/processors/verify_up_limit.py +141 -0
  438. simplibs/object/mixins/others/numerical/_stepper_class/methods/set_value.py +163 -0
  439. simplibs/object/mixins/others/numerical/_stepper_class/methods/step_down.py +154 -0
  440. simplibs/object/mixins/others/numerical/_stepper_class/methods/step_up.py +154 -0
  441. simplibs/object/mixins/others/numerical/_stepper_class/processors/__init__.py +38 -0
  442. simplibs/object/mixins/others/numerical/_stepper_class/processors/process_down_limit_value.py +143 -0
  443. simplibs/object/mixins/others/numerical/_stepper_class/processors/process_limit_action.py +118 -0
  444. simplibs/object/mixins/others/numerical/_stepper_class/processors/process_up_limit_value.py +143 -0
  445. simplibs/object/mixins/others/numerical/_stepper_class/processors/process_value.py +142 -0
  446. simplibs/object/mixins/others/numerical/_stepper_class/processors/validate_instance.py +138 -0
  447. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/__init__.py +39 -0
  448. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/raise_stepper_invalid_action.py +118 -0
  449. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/raise_stepper_invalid_down_limit.py +125 -0
  450. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/raise_stepper_invalid_instance.py +117 -0
  451. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/raise_stepper_invalid_up_limit.py +125 -0
  452. simplibs/object/mixins/others/numerical/_stepper_class/processors/validations/raise_stepper_non_numeric_value.py +122 -0
  453. simplibs/object/mixins/others/properties/InnersProperty.py +91 -0
  454. simplibs/object/mixins/others/properties/MetaShortcuts.py +113 -0
  455. simplibs/object/mixins/others/properties/__init__.py +24 -0
  456. simplibs/object/mixins/others/properties/_inners_property_utils/__init__.py +23 -0
  457. simplibs/object/mixins/others/properties/_inners_property_utils/_collect_nested_inner_properties.py +134 -0
  458. simplibs/object/mixins/others/properties/_inners_property_utils/collect_all_nested_properties.py +132 -0
  459. simplibs/object/mixins/others/state/DefaultState.py +119 -0
  460. simplibs/object/mixins/others/state/DirtyTracking.py +144 -0
  461. simplibs/object/mixins/others/state/History.py +248 -0
  462. simplibs/object/mixins/others/state/Permission.py +102 -0
  463. simplibs/object/mixins/others/state/__init__.py +31 -0
  464. simplibs/object/mixins/others/state/_history_utils/__init__.py +50 -0
  465. simplibs/object/mixins/others/state/_history_utils/core/__init__.py +32 -0
  466. simplibs/object/mixins/others/state/_history_utils/core/find_snapshot.py +142 -0
  467. simplibs/object/mixins/others/state/_history_utils/core/record_state.py +130 -0
  468. simplibs/object/mixins/others/state/_history_utils/core/set_history_limit.py +114 -0
  469. simplibs/object/mixins/others/state/_history_utils/core/validations/__init__.py +31 -0
  470. simplibs/object/mixins/others/state/_history_utils/core/validations/raise_history_limit_not_positive_integer.py +65 -0
  471. simplibs/object/mixins/others/state/_history_utils/core/validations/raise_unvalide_snapshot_index.py +67 -0
  472. simplibs/object/mixins/others/state/_history_utils/core/validations/raise_unvalide_snopshot_reference.py +67 -0
  473. simplibs/object/mixins/others/state/_history_utils/core/validations/raise_unvalide_snopshot_timestamp.py +66 -0
  474. simplibs/object/mixins/others/state/_history_utils/core/validations/raise_unvalide_timestamp.py +63 -0
  475. simplibs/object/mixins/others/state/_history_utils/navigations/__init__.py +38 -0
  476. simplibs/object/mixins/others/state/_history_utils/navigations/go_to_history_on_index.py +103 -0
  477. simplibs/object/mixins/others/state/_history_utils/navigations/go_to_history_on_timestamp.py +115 -0
  478. simplibs/object/mixins/others/state/_history_utils/navigations/go_to_last_history.py +103 -0
  479. simplibs/object/mixins/others/state/_history_utils/navigations/history_redo.py +103 -0
  480. simplibs/object/mixins/others/state/_history_utils/navigations/history_undo.py +104 -0
  481. simplibs/object/mixins/others/state/_history_utils/transfer/__init__.py +31 -0
  482. simplibs/object/mixins/others/state/_history_utils/transfer/export_history_to_dict.py +110 -0
  483. simplibs/object/mixins/others/state/_history_utils/transfer/import_history_from_dict.py +169 -0
  484. simplibs/object/mixins/others/state/_history_utils/transfer/validations/__init__.py +24 -0
  485. simplibs/object/mixins/others/state/_history_utils/transfer/validations/raise_unvalide_history_import_file.py +66 -0
  486. simplibs/object/mixins/others/state/_history_utils/transfer/validations/raise_unvalide_owner_class_mismatch.py +69 -0
  487. simplibs/object/settings/__init__.py +90 -0
  488. simplibs/object/settings/logging.py +138 -0
  489. simplibs/object/testing/__init__.py +90 -0
  490. simplibs/object/testing/assert_simple_mixin.py +150 -0
  491. simplibs/object/testing/assert_simple_object.py +219 -0
  492. simplibs/object/testing/asserts/__init__.py +53 -0
  493. simplibs/object/testing/asserts/base/__init__.py +22 -0
  494. simplibs/object/testing/asserts/base/assert_class_inheritance.py +75 -0
  495. simplibs/object/testing/asserts/base/assert_instance_creation.py +119 -0
  496. simplibs/object/testing/asserts/base/assert_user_instance_creation.py +97 -0
  497. simplibs/object/testing/asserts/base/assert_value_change.py +142 -0
  498. simplibs/object/testing/asserts/methods/__init__.py +20 -0
  499. simplibs/object/testing/asserts/methods/assert_calculate_value_method.py +113 -0
  500. simplibs/object/testing/asserts/methods/assert_decompose_value_method.py +109 -0
  501. simplibs/object/testing/asserts/methods/assert_validate_method.py +111 -0
  502. simplibs/object/testing/asserts/mixins/__init__.py +22 -0
  503. simplibs/object/testing/asserts/mixins/assert_instance_hasattr.py +94 -0
  504. simplibs/object/testing/asserts/mixins/assert_mixin_inheritance.py +72 -0
  505. simplibs/object/testing/asserts/mixins/assert_mixin_instance_creation.py +142 -0
  506. simplibs/object/testing/asserts/mixins/assert_mixins_slots_values.py +126 -0
  507. simplibs/object/testing/asserts/mutability/__init__.py +18 -0
  508. simplibs/object/testing/asserts/mutability/assert_immutable_behavior.py +118 -0
  509. simplibs/object/testing/asserts/mutability/assert_mutable_behavior.py +108 -0
  510. simplibs/object/testing/asserts/reactivity/__init__.py +17 -0
  511. simplibs/object/testing/asserts/reactivity/assert_reactivity_downward.py +141 -0
  512. simplibs/object/testing/asserts/reactivity/assert_reactivity_upward.py +109 -0
  513. simplibs/object/testing/bulk_test.py +150 -0
  514. simplibs/object/testing/containers/InnerValue.py +102 -0
  515. simplibs/object/testing/containers/MixinCase.py +89 -0
  516. simplibs/object/testing/containers/ObjectCase.py +101 -0
  517. simplibs/object/testing/containers/TestMixin.py +122 -0
  518. simplibs/object/testing/containers/__init__.py +20 -0
  519. simplibs/object/testing/containers/_validations/__init__.py +18 -0
  520. simplibs/object/testing/containers/_validations/raise_inner_value_empty_path.py +39 -0
  521. simplibs/object/testing/containers/_validations/raise_inner_value_invalid_path_type.py +44 -0
  522. simplibs/object/tools/__init__.py +0 -0
  523. simplibs/object/tools/automate_creators/__init__.py +0 -0
  524. simplibs/object/tools/automate_creators/_helpers/__init__.py +5 -0
  525. simplibs/object/tools/automate_creators/_helpers/_is_lambda.py +34 -0
  526. simplibs/object/tools/automate_creators/_helpers/_validations/__init__.py +3 -0
  527. simplibs/object/tools/automate_creators/_helpers/_validations/raise_calculate_default_failed.py +51 -0
  528. simplibs/object/tools/automate_creators/_helpers/_validations/raise_inner_is_not_simple_constant_subclass.py +44 -0
  529. simplibs/object/tools/automate_creators/_helpers/_validations/raise_inners_is_not_tuple.py +41 -0
  530. simplibs/object/tools/automate_creators/_helpers/calculate_default.py +51 -0
  531. simplibs/object/tools/automate_creators/_helpers/load_parameters_from_inners.py +72 -0
  532. simplibs/object/tools/automate_creators/_helpers/process_decompose.py +47 -0
  533. simplibs/object/tools/automate_creators/_helpers/process_logic.py +57 -0
  534. simplibs/object/tools/automate_creators/_helpers/process_validate.py +48 -0
  535. simplibs/object/tools/automate_creators/_validations/__init__.py +7 -0
  536. simplibs/object/tools/automate_creators/_validations/validate_class_name_is_str.py +36 -0
  537. simplibs/object/tools/automate_creators/_validations/validate_composite_has_inners.py +43 -0
  538. simplibs/object/tools/automate_creators/_validations/validate_composite_has_logic.py +44 -0
  539. simplibs/object/tools/automate_creators/_validations/validate_composite_has_not_default.py +37 -0
  540. simplibs/object/tools/automate_creators/_validations/validate_constant_has_default.py +48 -0
  541. simplibs/object/tools/automate_creators/_validations/validate_constant_has_not_decompose.py +37 -0
  542. simplibs/object/tools/automate_creators/_validations/validate_constant_has_not_logic.py +37 -0
  543. simplibs/object/tools/automate_creators/bulk/BulkCase.py +100 -0
  544. simplibs/object/tools/automate_creators/bulk/__init__.py +0 -0
  545. simplibs/object/tools/automate_creators/bulk/create_simple_object_bulk.py +77 -0
  546. simplibs/object/tools/automate_creators/bulk/specific_bulks/__init__.py +0 -0
  547. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/__init__.py +8 -0
  548. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_csv_callable_not_supported.py +26 -0
  549. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_data_not_list.py +28 -0
  550. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_decode_failed.py +29 -0
  551. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_input_not_sequence.py +27 -0
  552. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_input_not_str.py +28 -0
  553. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_item_is_not_bulk_dict.py +39 -0
  554. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_table_row_not_sequence.py +26 -0
  555. simplibs/object/tools/automate_creators/bulk/specific_bulks/_validations/raise_bulk_yaml_import_failed.py +22 -0
  556. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_bulk_case_class.py +57 -0
  557. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_csv.py +68 -0
  558. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_dicts.py +19 -0
  559. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_json.py +24 -0
  560. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_table.py +43 -0
  561. simplibs/object/tools/automate_creators/bulk/specific_bulks/create_simple_object_bulk_from_yaml.py +29 -0
  562. simplibs/object/tools/automate_creators/create_constant_class.py +84 -0
  563. simplibs/object/tools/automate_creators/create_object_class.py +110 -0
  564. simplibs/object/tools/automate_creators/create_simple_object.py +97 -0
  565. simplibs/object/tools/randomize/__init__.py +18 -0
  566. simplibs/object/tools/randomize/_validations/__init__.py +28 -0
  567. simplibs/object/tools/randomize/_validations/raise_random_data_filler_exhausted.py +55 -0
  568. simplibs/object/tools/randomize/_validations/validate_instance_is_simple_constant_base.py +52 -0
  569. simplibs/object/tools/randomize/_validations/validate_registry_is_randomize_registry_base.py +51 -0
  570. simplibs/object/tools/randomize/_validations/validate_retries_is_greater_than_zero.py +48 -0
  571. simplibs/object/tools/randomize/_validations/validate_retries_is_int.py +49 -0
  572. simplibs/object/tools/randomize/_validations/validate_skip_immutable_is_bool.py +43 -0
  573. simplibs/object/tools/randomize/_validations/validate_skip_unregistered_is_bool.py +44 -0
  574. simplibs/object/tools/randomize/random_data_filler.py +133 -0
  575. simplibs/object/tools/randomize/randomize_value.py +122 -0
  576. simplibs_object-0.1.0.dist-info/METADATA +590 -0
  577. simplibs_object-0.1.0.dist-info/RECORD +580 -0
  578. simplibs_object-0.1.0.dist-info/WHEEL +5 -0
  579. simplibs_object-0.1.0.dist-info/licenses/LICENSE +21 -0
  580. simplibs_object-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,93 @@
1
+ from typing import TYPE_CHECKING, NoReturn
2
+ # Outers
3
+ from ......exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.core_mixins import InfrastructureProtocol
7
+
8
+
9
+ def raise_immutability_constant_not_found(
10
+ instance: "InfrastructureProtocol",
11
+ name: str,
12
+ ) -> NoReturn:
13
+ """
14
+ Raises an error when a constant name is not found in the instance's
15
+ `_constant_names_set` during an immutable update.
16
+ """
17
+
18
+ # noinspection PyProtectedMember
19
+ raise SimpleRuntimeError(
20
+ error_name="IMMUTABILITY UPDATE ERROR",
21
+ label="constant name",
22
+ expected="Name must refer to a valid constant defined in the instance.",
23
+ value=name,
24
+ problem=(
25
+ f"Constant '{name}' does not exist in the instance. ",
26
+ "Immutable update cannot be applied."
27
+ ),
28
+ context=(
29
+ f"Immutable update attempted on instance '{type(instance).__name__}'. ",
30
+ f"Valid constants: {instance._constant_names_set}"
31
+ ),
32
+ how_to_fix=(
33
+ "Ensure that the provided name refers to a valid constant.",
34
+ "Check the instance's `_constant_names_set` for available constants.",
35
+ "If the name is meant to be a composite, use `with_composite` instead.",
36
+ ),
37
+ exception=KeyError,
38
+ )
39
+
40
+
41
+ _DESIGN_NOTES = """
42
+ # raise_immutability_constant_not_found
43
+
44
+ ## Purpose
45
+ Ensures that immutable updates targeting constants are always applied to valid,
46
+ existing constant nodes.
47
+ If a user attempts to update a constant that does not exist, this function
48
+ raises a structured diagnostic error explaining exactly what went wrong and how
49
+ to fix it.
50
+
51
+ This protects the immutability pipeline from invalid structural updates.
52
+
53
+ ## Architectural reasoning
54
+ Immutable updates rely on strict structural correctness:
55
+
56
+ - constants must exist,
57
+ - constants must be addressable via `_constant_names_set`,
58
+ - constants must have valid metadata and validation logic.
59
+
60
+ If a constant name is invalid:
61
+
62
+ - the update cannot be applied,
63
+ - composite recalculation would be incorrect,
64
+ - snapshot reconstruction would be inconsistent,
65
+ - debugging would become significantly harder.
66
+
67
+ This raise function ensures that the pipeline fails early, clearly, and safely.
68
+
69
+ ## Pipeline position
70
+ This function is used in the very first validation step of `with_constant`:
71
+
72
+ 1. Check whether `name` is in `_constant_names_set`.
73
+ 2. If not → raise this error immediately.
74
+ 3. No further processing is performed.
75
+
76
+ This guarantees that invalid updates never reach deeper pipeline layers.
77
+
78
+ ## Diagnostic value
79
+ The error message provides:
80
+
81
+ - the invalid constant name,
82
+ - the list of valid constants,
83
+ - the context of the attempted update,
84
+ - actionable steps to fix the issue,
85
+ - a clear distinction between constants and composites.
86
+
87
+ This makes the error friendly, actionable, and easy to understand.
88
+
89
+ ## Notes
90
+ - This is a pure `raise_...` function: it performs no conditional logic.
91
+ - It is used exclusively by the immutability update pipeline.
92
+ - All immutable constant updates must pass this check.
93
+ """
@@ -0,0 +1,147 @@
1
+ from typing import Any, TYPE_CHECKING
2
+ # Inners
3
+ from .vaidations import raise_immutability_constant_not_found
4
+ from .utils import (
5
+ create_snapshot_dict,
6
+ create_new_instance,
7
+ reacalculate_owner_value,
8
+ )
9
+ # Annotations
10
+ if TYPE_CHECKING:
11
+ from ....._core.protocols.mixins.core_mixins import (
12
+ InfrastructureProtocol,
13
+ InfrastructuredComponent,
14
+ )
15
+
16
+
17
+ def with_constant(
18
+ self: "InfrastructureProtocol",
19
+ name: str,
20
+ new_value: Any,
21
+ ) -> "InfrastructuredComponent":
22
+ """
23
+ Integration requirement:
24
+ This function is designed for the core pipeline framework. The object
25
+ provided in `self` MUST inherit from:
26
+ 1. Snapshot (provides _restore_snapshot)
27
+ 2. NodesDicts (provides metadata and node access)
28
+ Without these mixins, the pipeline will raise AttributeError.
29
+ """
30
+
31
+ # 1. Validate constant name
32
+ if name not in self._constant_names_set:
33
+ raise_immutability_constant_not_found(self, name)
34
+
35
+ # 2. Validate new value
36
+ instance, path = self._nodes_dict[name]
37
+ instance.validate(new_value)
38
+
39
+ # 3. Create current snapshot dictionary
40
+ snapshot_dict = create_snapshot_dict(self._nodes_tuple)
41
+
42
+ # 4. Write new constant value
43
+ snapshot_dict[name] = new_value
44
+
45
+ # 5. Recalculate composite values
46
+ reacalculate_owner_value(snapshot_dict, instance.owner)
47
+
48
+ # 6. Build clean snapshot tuple
49
+ new_snapshot = tuple(snapshot_dict.values())
50
+
51
+ # 7. Return new instance
52
+ return create_new_instance(self, new_snapshot)
53
+
54
+
55
+ _DESIGN_NOTES = """
56
+ # with_constant
57
+
58
+ ## Purpose
59
+ Updates a single constant (atomic node) in an immutable-safe way. This function
60
+ is the smallest unit of the immutability pipeline and is used whenever a single
61
+ constant value needs to be changed while ensuring composite nodes remain
62
+ consistent.
63
+
64
+ ## Architectural role
65
+ This function is a core part of the immutability subsystem and is used by:
66
+
67
+ - [with_constants](ca://s?q=Explain_with_constants) — batch constant updates
68
+ - [with_composite](ca://s?q=Explain_with_composite) — composite-level updates
69
+ - [with_any](ca://s?q=Explain_with_any) — mixed updates
70
+ - [Serialization update_constants](ca://s?q=Explain_update_constants) — partial dict updates
71
+ - [Snapshot restoration](ca://s?q=Explain_snapshot_restoration) — rebuilding state
72
+
73
+ It provides a deterministic, safe, and minimal update mechanism for atomic
74
+ values.
75
+
76
+ ## How it works
77
+ The function performs seven deterministic steps:
78
+
79
+ 1. **Validate constant name**
80
+ Ensures the target is a true constant, not a composite node.
81
+
82
+ 2. **Validate new value**
83
+ Uses the node’s own validation logic to ensure type and semantic correctness.
84
+
85
+ 3. **Create snapshot dictionary**
86
+ Builds a flat dictionary of current values using
87
+ [create_snapshot_dict](ca://s?q=Explain_create_snapshot_dict).
88
+
89
+ 4. **Write new constant value**
90
+ Updates the snapshot dictionary at the constant’s name.
91
+
92
+ 5. **Recalculate composite values**
93
+ Ensures structural consistency using
94
+ [reacalculate_owner_value](ca://s?q=Explain_recalculate_owner_value).
95
+
96
+ 6. **Build clean snapshot tuple**
97
+ Converts the dictionary into a positional snapshot matching `nodes_tuple`.
98
+
99
+ 7. **Return new instance**
100
+ Creates a new immutable instance using
101
+ [create_new_instance](ca://s?q=Explain_create_new_instance).
102
+
103
+ ## Why this function exists
104
+ Immutable updates must:
105
+
106
+ - avoid mutating the original instance,
107
+ - preserve structural metadata,
108
+ - recalculate composite nodes,
109
+ - produce a fully initialized new instance.
110
+
111
+ `with_constant` encapsulates this entire process in a minimal, predictable
112
+ pipeline.
113
+
114
+ ## Deterministic behavior
115
+ The update is deterministic because:
116
+
117
+ - `nodes_tuple` defines stable ordering,
118
+ - snapshot dictionaries use canonical `name_snake` keys,
119
+ - composite recalculation is pure,
120
+ - instance creation is clean and side-effect-free.
121
+
122
+ This determinism is essential for immutability, history tracking, and debugging.
123
+
124
+ ## Integration requirements
125
+ The function assumes the instance implements:
126
+
127
+ - [Snapshot](ca://s?q=Explain_Snapshot_mixin) — provides `_restore_snapshot`
128
+ - [NodesDicts](ca://s?q=Explain_NodesDicts_mixin) — provides node metadata
129
+
130
+ Without these mixins, the pipeline cannot reconstruct the instance.
131
+
132
+ ## Stability guarantee
133
+ Any change to this function would affect:
134
+
135
+ - immutability behavior,
136
+ - composite recalculation,
137
+ - serialization consistency,
138
+ - debugging tools,
139
+ - history tracking.
140
+
141
+ Therefore, `with_constant` is treated as a **core invariant** of the immutability subsystem.
142
+
143
+ ## Notes
144
+ - This function is intentionally minimal and side-effect-free.
145
+ - It is not part of the public API; it is used internally by mixins.
146
+ - All structural logic is delegated to helper utilities.
147
+ """
@@ -0,0 +1,17 @@
1
+ from .with_constants import with_constants
2
+
3
+
4
+ _DESIGN_NOTES = """
5
+ # with_constants
6
+
7
+ ## Purpose
8
+ Provides the batch constant update operation.
9
+ This function applies multiple constant changes immutably and ensures
10
+ structural correctness through tuple-based validation.
11
+
12
+ ## Component
13
+
14
+ | Component | Type | Description |
15
+ | :--------------- | :------- | :----------------------------------- |
16
+ | `with_constants` | Function | Applies multiple constant updates. |
17
+ """
@@ -0,0 +1,15 @@
1
+ from .find_longest_keys import find_longest_keys
2
+
3
+ _DESIGN_NOTES = """
4
+ # Helpers for Constant Batch Updates
5
+
6
+ ## Purpose
7
+ Provides utilities used by the `with_constants` pipeline. These helpers
8
+ determine recalculation order and structural depth of affected constants.
9
+
10
+ ## Internal Components Registry
11
+
12
+ | Component | Type | Description |
13
+ | :------------------ | :------- | :----------------------------------------------- |
14
+ | `find_longest_keys` | Function | Determines deepest affected constant paths. |
15
+ """
@@ -0,0 +1,112 @@
1
+ from typing import TYPE_CHECKING, Any
2
+ # Annotations
3
+ if TYPE_CHECKING:
4
+ from ......_core.protocols.alias_typings import PathDict, NamesTuple
5
+
6
+
7
+ def find_longest_keys(
8
+ path_dict: "PathDict",
9
+ ) -> "NamesTuple":
10
+ """
11
+ Finds the keys whose paths represent terminal (deepest) nodes within
12
+ the provided path dictionary.
13
+ """
14
+
15
+ # 1. Convert dictionary into a list of (key, path) pairs
16
+ # and sort them by their path (index 1)
17
+ sorted_path = sorted(path_dict.items(), key=lambda x: x[1])
18
+ longest_keys = []
19
+
20
+ # 2. Iterate and compare paths
21
+ for i in range(len(sorted_path) - 1):
22
+ key, path = sorted_path[i]
23
+ _, next_path = sorted_path[i + 1]
24
+
25
+ # If the next path starts with the current path,
26
+ # the current one is an intermediate node → skip it.
27
+ if next_path[:len(path)] == path:
28
+ continue
29
+
30
+ # Otherwise, this is a terminal node → store its key.
31
+ longest_keys.append(key)
32
+
33
+ # The last element in the sorted list is always terminal
34
+ longest_keys.append(sorted_path[-1][0])
35
+
36
+ return tuple(longest_keys)
37
+
38
+
39
+ _DESIGN_NOTES = """
40
+ # find_longest_keys
41
+
42
+ ## Purpose
43
+ Identifies the “deepest” or terminal nodes among a set of changed paths.
44
+ This function is used in the immutability pipeline to determine which composite
45
+ owners must be recalculated after constant updates.
46
+
47
+ It ensures that recalculation starts from the deepest affected nodes and moves
48
+ upward, preserving structural correctness.
49
+
50
+ ## Architectural role
51
+ This function is used by:
52
+
53
+ - [with_constants](ca://s?q=Explain_with_constants) — batch constant updates
54
+ - [with_any](ca://s?q=Explain_with_any) — mixed updates
55
+ - [with_composite](ca://s?q=Explain_with_composite) — composite updates
56
+
57
+ It determines the minimal set of composite nodes that must be recalculated.
58
+
59
+ ## How it works
60
+ The function performs three deterministic steps:
61
+
62
+ 1. **Sort paths by structural depth**
63
+ Sorting ensures that shorter (parent) paths appear before longer (child)
64
+ paths.
65
+
66
+ 2. **Compare each path with the next one**
67
+ If the next path starts with the current path, the current path is a parent
68
+ and not a terminal node.
69
+
70
+ 3. **Collect terminal nodes**
71
+ Terminal nodes are those whose paths are not prefixes of any subsequent path.
72
+
73
+ The last element in the sorted list is always terminal.
74
+
75
+ ## Why terminal nodes matter
76
+ Recalculating composite nodes must begin at the deepest affected point in the
77
+ structure. Starting from parents would produce incorrect values because their
78
+ children may not yet be updated.
79
+
80
+ Terminal nodes guarantee:
81
+
82
+ - correct recalculation order,
83
+ - minimal recomputation,
84
+ - structural consistency,
85
+ - deterministic behavior.
86
+
87
+ ## Deterministic behavior
88
+ The output is deterministic because:
89
+
90
+ - sorting is stable,
91
+ - path comparison is structural,
92
+ - terminal detection is positional,
93
+ - output order matches structural depth.
94
+
95
+ This determinism is essential for immutability pipelines.
96
+
97
+ ## Stability guarantee
98
+ Any change to this function would affect:
99
+
100
+ - composite recalculation order,
101
+ - immutability correctness,
102
+ - snapshot consistency,
103
+ - debugging tools.
104
+
105
+ Therefore, `find_longest_keys` is treated as a **core invariant** of the
106
+ immutability subsystem.
107
+
108
+ ## Notes
109
+ - This function is intentionally minimal and side‑effect‑free.
110
+ - It is not part of the public API; it is used internally by mixins.
111
+ - All structural logic is delegated to path ordering.
112
+ """
@@ -0,0 +1,25 @@
1
+ from .raise_immutability_batch_constant_not_found import raise_immutability_batch_constant_not_found
2
+ from .raise_immutability_constants_changes_not_tuple import raise_immutability_constants_changes_not_tuple
3
+ from .validate_inner_tuple_has_length_two import validate_inner_tuple_has_length_two
4
+ from .validate_inner_tuple_is_tuple import validate_inner_tuple_is_tuple
5
+ from .validate_inner_tuple_name_is_str import validate_inner_tuple_name_is_str
6
+
7
+
8
+ _DESIGN_NOTES = """
9
+ # Validations for with_constants
10
+
11
+ ## Purpose
12
+ Provides validation and raise functions used by the batch constant update
13
+ pipeline (`with_constants`). These checks ensure correct tuple structure and
14
+ validate constant existence.
15
+
16
+ ## Components
17
+
18
+ | Component | Type | Description |
19
+ | :--------------------------------------------- | :------- | :----------------------------------------------- |
20
+ | `raise_immutability_batch_constant_not_found` | Function | Raised when a batch constant is missing. |
21
+ | `raise_immutability_constants_changes_not_tuple` | Function | Ensures the batch input is a tuple. |
22
+ | `validate_inner_tuple_is_tuple` | Function | Ensures each change item is a tuple. |
23
+ | `validate_inner_tuple_has_length_two` | Function | Ensures each change item has two elements. |
24
+ | `validate_inner_tuple_name_is_str` | Function | Ensures the first element of each tuple is str. |
25
+ """
@@ -0,0 +1,94 @@
1
+ from typing import TYPE_CHECKING, NoReturn
2
+ # Outers
3
+ from ......exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.core_mixins import InfrastructureProtocol
7
+
8
+
9
+ def raise_immutability_batch_constant_not_found(
10
+ instance: "InfrastructureProtocol",
11
+ name: str,
12
+ ) -> NoReturn:
13
+ """
14
+ Raises an error when a constant name inside a batch update does not
15
+ exist in the instance's `_constant_names_set`.
16
+ """
17
+
18
+ # noinspection PyProtectedMember
19
+ raise SimpleRuntimeError(
20
+ error_name="IMMUTABILITY BATCH UPDATE ERROR",
21
+ label="constant name",
22
+ expected="Each (name, value) pair must refer to a valid constant.",
23
+ value=name,
24
+ problem=(
25
+ f"Constant '{name}' does not exist in the instance. ",
26
+ "Batch immutable update cannot continue."
27
+ ),
28
+ context=(
29
+ f"Batch update attempted on instance '{type(instance).__name__}'. "
30
+ f"Valid constants: {instance._constant_names_set}"
31
+ ),
32
+ how_to_fix=(
33
+ "Ensure that every (name, value) tuple refers to a valid constant.",
34
+ "Check the instance's `_constant_names_set` for available constants.",
35
+ "If the name is meant to be a composite, use `with_composite` or `with_any` instead.",
36
+ "Remove or correct the invalid constant name in the batch update.",
37
+ ),
38
+ exception=KeyError,
39
+ )
40
+
41
+
42
+ _DESIGN_NOTES = """
43
+ # raise_immutability_batch_constant_not_found
44
+
45
+ ## Purpose
46
+ Ensures that every `(name, value)` pair inside a batch constant update refers to
47
+ a valid constant.
48
+ Batch updates must be structurally perfect — a single invalid name would break
49
+ the entire immutability pipeline.
50
+
51
+ This function provides a clear, structured diagnostic error when a constant name
52
+ is invalid.
53
+
54
+ ## Architectural reasoning
55
+ `with_constants` processes multiple updates at once.
56
+ For correctness:
57
+
58
+ - every name must be a valid constant,
59
+ - every constant must have metadata and validation logic,
60
+ - composite names must not appear in this pipeline.
61
+
62
+ If an invalid name appears:
63
+
64
+ - recalculation order becomes undefined,
65
+ - snapshot reconstruction becomes inconsistent,
66
+ - debugging becomes significantly harder.
67
+
68
+ Failing early prevents deeper structural corruption.
69
+
70
+ ## Pipeline position
71
+ This function is used during step **4.3.3** of `with_constants`:
72
+
73
+ 1. Extract `(inner_name, new_value)`.
74
+ 2. Check whether `inner_name` is in `_constant_names_set`.
75
+ 3. If not → raise this error immediately.
76
+ 4. No further processing of this tuple is performed.
77
+
78
+ This guarantees that only valid constants enter the recalculation phase.
79
+
80
+ ## Diagnostic value
81
+ The error message provides:
82
+
83
+ - the invalid constant name,
84
+ - the list of valid constants,
85
+ - the context of the batch update,
86
+ - actionable steps to fix the issue.
87
+
88
+ This makes the error friendly, actionable, and easy to understand.
89
+
90
+ ## Notes
91
+ - This is a pure `raise_...` function: it performs no conditional logic.
92
+ - It is used exclusively by the `with_constants` pipeline.
93
+ - All batch constant updates must pass this check.
94
+ """
@@ -0,0 +1,94 @@
1
+ from typing import TYPE_CHECKING, NoReturn
2
+ # Outers
3
+ from ......exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.core_mixins import InfrastructureProtocol
7
+ from ......_core.protocols.alias_typings import ChangeTuple, ChangesTuple
8
+
9
+
10
+ def raise_immutability_constants_changes_not_tuple(
11
+ instance: "InfrastructureProtocol",
12
+ changes: "ChangeTuple | ChangesTuple | None",
13
+ ) -> NoReturn:
14
+ """
15
+ Raises an error when the `changes` argument passed to `with_constants`
16
+ is not a tuple.
17
+ """
18
+
19
+ raise SimpleRuntimeError(
20
+ error_name="IMMUTABILITY UPDATE ERROR",
21
+ label="changes",
22
+ expected="Tuple of (name, value) pairs or a single (name, value) tuple.",
23
+ value=type(changes).__name__ if changes is not None else "None",
24
+ problem=(
25
+ "Invalid type for `changes` argument in `with_constants`. ",
26
+ "Immutable batch update requires a tuple-based structure."
27
+ ),
28
+ context=(
29
+ f"Immutable constant batch update on instance '{type(instance).__name__}'. ",
30
+ "The `changes` parameter must be a tuple."
31
+ ),
32
+ how_to_fix=(
33
+ "Pass changes as a tuple: ((name, value), (name, value), ...).",
34
+ "For a single change, use: (name, value) — it will be normalized internally.",
35
+ "Do not use lists, dicts, or other container types for `changes`.",
36
+ ),
37
+ exception=TypeError,
38
+ )
39
+
40
+
41
+ _DESIGN_NOTES = """
42
+ # raise_immutability_constants_changes_not_tuple
43
+
44
+ ## Purpose
45
+ Ensures that the `changes` argument passed to `with_constants` has the correct
46
+ tuple-based structure.
47
+ The immutability pipeline relies on tuples for deterministic ordering and
48
+ structural validation. Any other container type would break these guarantees.
49
+
50
+ ## Architectural reasoning
51
+ `with_constants` expects:
52
+
53
+ - either a single `(name, value)` tuple,
54
+ - or a tuple of `(name, value)` tuples.
55
+
56
+ This design:
57
+
58
+ - preserves ordering,
59
+ - simplifies validation,
60
+ - avoids ambiguity of dicts/lists,
61
+ - keeps the API minimal and predictable.
62
+
63
+ If `changes` is not a tuple:
64
+
65
+ - the pipeline cannot reliably interpret the update,
66
+ - structural validation becomes ambiguous,
67
+ - debugging and logging lose determinism.
68
+
69
+ Therefore, the function fails early with a clear, structured error.
70
+
71
+ ## Pipeline position
72
+ This function is used at the beginning of the `with_constants` update flow:
73
+
74
+ 1. Check `isinstance(changes, tuple)`.
75
+ 2. If false → raise this error.
76
+ 3. No further processing is performed.
77
+
78
+ This guarantees that only well-formed inputs enter the deeper pipeline.
79
+
80
+ ## Diagnostic value
81
+ The error message explains:
82
+
83
+ - what type was received,
84
+ - what structure is expected,
85
+ - in which context the error occurred,
86
+ - how to fix the issue (including examples).
87
+
88
+ This makes the error actionable and easy to understand.
89
+
90
+ ## Notes
91
+ - This is a pure `raise_...` function: it performs no conditional logic.
92
+ - It is used exclusively by the `with_constants` pipeline.
93
+ - All batch constant updates must pass this check.
94
+ """
@@ -0,0 +1,91 @@
1
+ from typing import TYPE_CHECKING, NoReturn
2
+ # Outers
3
+ from ......exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.core_mixins import InfrastructureProtocol
7
+
8
+
9
+ def validate_inner_tuple_has_length_two(
10
+ instance: "InfrastructureProtocol",
11
+ inner_tuple: object,
12
+ ) -> None:
13
+ """
14
+ Validates that the provided inner_tuple has exactly two items:
15
+ (name, value).
16
+ """
17
+
18
+ if isinstance(inner_tuple, tuple) and len(inner_tuple) == 2:
19
+ return
20
+
21
+ raise SimpleRuntimeError(
22
+ error_name="IMMUTABILITY BATCH UPDATE ERROR",
23
+ label="change item length",
24
+ expected="Tuple of exactly two items: (name, value).",
25
+ value=f"length={len(inner_tuple)}" if isinstance(inner_tuple, tuple) else "not a tuple",
26
+ problem=(
27
+ "Invalid structure for change item. ",
28
+ "Each change must be a 2‑item tuple representing (name, value)."
29
+ ),
30
+ context=(
31
+ f"Batch update attempted on instance '{type(instance).__name__}'. ",
32
+ "The provided tuple does not have exactly two items."
33
+ ),
34
+ how_to_fix=(
35
+ "Ensure each change is provided as a 2‑item tuple.",
36
+ "Correct format: (name, value)",
37
+ "Incorrect formats include: (name,), (name, value, extra), or any other size.",
38
+ ),
39
+ exception=ValueError,
40
+ )
41
+
42
+
43
+ _DESIGN_NOTES = """
44
+ # validate_inner_tuple_has_length_two
45
+
46
+ ## Purpose
47
+ Ensures that each change item inside a batch update has exactly two elements:
48
+ `(name, value)`.
49
+ This is the minimal structural requirement for immutable updates — without it,
50
+ the pipeline cannot determine what should be updated or how.
51
+
52
+ ## Architectural reasoning
53
+ The immutability pipeline relies on strict tuple structure:
54
+
55
+ - index `0` → the node name,
56
+ - index `1` → the new value.
57
+
58
+ If the tuple has a different length:
59
+
60
+ - unpacking becomes ambiguous,
61
+ - routing logic cannot determine whether the item is a constant or composite,
62
+ - validation cannot proceed,
63
+ - debugging becomes significantly harder.
64
+
65
+ Failing early prevents structural corruption.
66
+
67
+ ## Pipeline position
68
+ This validation is part of step **4.3.1** in `with_constants`:
69
+
70
+ 1. Check that `inner_tuple` has length 2.
71
+ 2. If not → raise this error immediately.
72
+ 3. No further validation is performed on this item.
73
+
74
+ This ensures that only structurally correct items enter deeper validation layers.
75
+
76
+ ## Diagnostic value
77
+ The error message provides:
78
+
79
+ - the actual tuple length,
80
+ - the expected structure,
81
+ - the context of the batch update,
82
+ - actionable steps to fix the issue.
83
+
84
+ This makes the error friendly, actionable, and easy to understand.
85
+
86
+ ## Notes
87
+ - This is a pure validation function: it performs no additional logic.
88
+ - It is used by both `with_constants` and `with_any`.
89
+ - All batch update items must pass this check before further validation.
90
+
91
+ """