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,103 @@
1
+ from typing import TYPE_CHECKING
2
+ # Outers
3
+ from ..core.validations import raise_unvalide_snapshot_index
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.state import HistoryProtocol
7
+
8
+
9
+ def go_to_history_on_index(
10
+ self: "HistoryProtocol",
11
+ index: int
12
+ ) -> None:
13
+ """
14
+ Navigates to a specific history entry by index and restores its snapshot.
15
+ """
16
+
17
+ # 1. Validate index
18
+ if not (0 <= index < self._history_count):
19
+ raise_unvalide_snapshot_index(self, index)
20
+
21
+ # 2. Switch to the selected entry
22
+ self._history_index = index
23
+ _, snapshot = self._history[self._history_index]
24
+ self._restore_snapshot(snapshot)
25
+
26
+
27
+ _DESIGN_NOTES = """
28
+ # go_to_history_on_index
29
+
30
+ ## Purpose
31
+ Navigates to a specific history entry using its integer index and restores the
32
+ corresponding snapshot. This function provides fast, deterministic navigation
33
+ within the history list.
34
+
35
+ ## Architectural role
36
+ `go_to_history_on_index` is used by:
37
+
38
+ - `History.go_to_index`
39
+ - undo/redo logic (indirectly)
40
+ - debugging tools
41
+ - diffing utilities
42
+ - composite and constant recalculation pipelines (when navigating snapshots)
43
+
44
+ It is the primary mechanism for index‑based history navigation.
45
+
46
+ ## How it works
47
+ The function performs two deterministic steps:
48
+
49
+ ### 1. Validate index
50
+ Ensures the index is within the valid range `[0, _history_count)`.
51
+ Invalid indices trigger a structured validation error.
52
+
53
+ ### 2. Restore snapshot
54
+ Updates `_history_index` and restores the snapshot using `_restore_snapshot`.
55
+ This operation mutates the instance to reflect the historical state.
56
+
57
+ ## Integration requirements
58
+ The function assumes the instance implements:
59
+
60
+ - **History internals**
61
+ `_history`, `_history_index`, `_history_count`
62
+
63
+ - **SnapshotMixin**
64
+ Provides `_restore_snapshot(snapshot)`.
65
+
66
+ Without these components, index‑based navigation cannot operate correctly.
67
+
68
+ ## Why this function exists
69
+ Index‑based navigation is:
70
+
71
+ - fast,
72
+ - predictable,
73
+ - stable,
74
+ - independent of timestamps,
75
+ - ideal for undo/redo operations.
76
+
77
+ This function encapsulates the minimal logic required to jump to a specific
78
+ history entry.
79
+
80
+ ## Deterministic behavior
81
+ Navigation is guaranteed to be:
82
+
83
+ - index‑safe,
84
+ - stable across mutations,
85
+ - consistent with undo/redo semantics,
86
+ - compatible with diffing and debugging tools.
87
+
88
+ ## Stability guarantee
89
+ Any change to this function would affect:
90
+
91
+ - undo/redo behavior,
92
+ - navigation correctness,
93
+ - snapshot restoration,
94
+ - debugging tools.
95
+
96
+ Therefore, `go_to_history_on_index` is treated as a **core invariant** of the
97
+ history subsystem.
98
+
99
+ ## Notes
100
+ - This function is intentionally minimal and side‑effect‑free.
101
+ - It is not part of the public API; it is used internally by mixins.
102
+ - All structural logic is delegated to history internals and snapshot restoration.
103
+ """
@@ -0,0 +1,115 @@
1
+ from typing import TYPE_CHECKING
2
+ from datetime import datetime
3
+ # Outers
4
+ from ..core.validations import raise_unvalide_timestamp, raise_unvalide_snopshot_timestamp
5
+ # Annotations
6
+ if TYPE_CHECKING:
7
+ from ......_core.protocols.mixins.state import HistoryProtocol
8
+
9
+
10
+ def go_to_history_on_timestamp(
11
+ self: "HistoryProtocol",
12
+ timestamp: datetime
13
+ ) -> None:
14
+ """
15
+ Navigates to a specific history entry by timestamp and restores its snapshot.
16
+ """
17
+
18
+ # 1. Validate timestamp type
19
+ if not isinstance(timestamp, datetime):
20
+ raise_unvalide_timestamp(self, timestamp)
21
+
22
+ # 2. Search for matching timestamp
23
+ for i, (ts, snapshot) in enumerate(self._history):
24
+ if ts == timestamp:
25
+ self._history_index = i
26
+ self._restore_snapshot(snapshot)
27
+ return
28
+
29
+ # 3. Timestamp not found
30
+ raise_unvalide_snopshot_timestamp(self, timestamp)
31
+
32
+
33
+ _DESIGN_NOTES = """
34
+ # go_to_history_on_timestamp
35
+
36
+ ## Purpose
37
+ Navigates to a specific history entry using a datetime timestamp and restores
38
+ the corresponding snapshot. This function provides semantic, human‑readable
39
+ navigation within the history list.
40
+
41
+ ## Architectural role
42
+ `go_to_history_on_timestamp` is used by:
43
+
44
+ - `History.go_to_timestamp`
45
+ - debugging tools
46
+ - diffing utilities
47
+ - history import/export pipelines
48
+ - composite and constant recalculation pipelines (when navigating snapshots)
49
+
50
+ It is the primary mechanism for timestamp‑based history navigation.
51
+
52
+ ## How it works
53
+ The function performs three deterministic steps:
54
+
55
+ ### 1. Validate timestamp
56
+ Ensures the provided value is a valid `datetime` instance.
57
+ Invalid values trigger a structured validation error.
58
+
59
+ ### 2. Search for matching timestamp
60
+ Iterates through the history list and compares timestamps.
61
+ If a match is found:
62
+ - `_history_index` is updated,
63
+ - the snapshot is restored using `_restore_snapshot`,
64
+ - navigation completes immediately.
65
+
66
+ ### 3. Timestamp not found
67
+ If no entry matches the provided timestamp, a structured validation error is
68
+ raised, including a list of available timestamps for debugging.
69
+
70
+ ## Integration requirements
71
+ The function assumes the instance implements:
72
+
73
+ - **History internals**
74
+ `_history`, `_history_index`, `_history_count`
75
+
76
+ - **SnapshotMixin**
77
+ Provides `_restore_snapshot(snapshot)`.
78
+
79
+ Without these components, timestamp‑based navigation cannot operate correctly.
80
+
81
+ ## Why this function exists
82
+ Timestamp‑based navigation is:
83
+
84
+ - human‑friendly,
85
+ - semantically meaningful,
86
+ - ideal for debugging and diffing,
87
+ - useful when index positions are unknown or irrelevant.
88
+
89
+ This function encapsulates the minimal logic required to jump to a specific
90
+ historical moment.
91
+
92
+ ## Deterministic behavior
93
+ Navigation is guaranteed to be:
94
+
95
+ - timestamp‑safe,
96
+ - stable across mutations,
97
+ - consistent with undo/redo semantics,
98
+ - compatible with diffing and debugging tools.
99
+
100
+ ## Stability guarantee
101
+ Any change to this function would affect:
102
+
103
+ - navigation correctness,
104
+ - undo/redo behavior,
105
+ - snapshot restoration,
106
+ - debugging tools.
107
+
108
+ Therefore, `go_to_history_on_timestamp` is treated as a **core invariant** of
109
+ the history subsystem.
110
+
111
+ ## Notes
112
+ - This function is intentionally minimal and side‑effect‑free.
113
+ - It is not part of the public API; it is used internally by mixins.
114
+ - All structural logic is delegated to history internals and snapshot restoration.
115
+ """
@@ -0,0 +1,103 @@
1
+ from typing import TYPE_CHECKING
2
+ # Annotations
3
+ if TYPE_CHECKING:
4
+ from ......_core.protocols.mixins.state import HistoryProtocol
5
+
6
+
7
+ def go_to_last_history(
8
+ self: "HistoryProtocol"
9
+ ) -> None:
10
+ """
11
+ Navigates to the last history entry and restores its snapshot.
12
+ """
13
+
14
+ # 1. Check if already at the last entry
15
+ last_index = self._history_count - 1
16
+ if self._history_index != last_index:
17
+
18
+ # 2. Switch to the last entry
19
+ self._history_index = last_index
20
+ _, snapshot = self._history[self._history_index]
21
+ self._restore_snapshot(snapshot)
22
+
23
+
24
+ _DESIGN_NOTES = """
25
+ # go_to_last_history
26
+
27
+ ## Purpose
28
+ Navigates to the most recent history entry and restores its snapshot.
29
+ This function provides a fast, deterministic way to jump to the newest state
30
+ recorded in the history subsystem.
31
+
32
+ ## Architectural role
33
+ `go_to_last_history` is used by:
34
+
35
+ - `History.go_to_last`
36
+ - debugging tools
37
+ - diffing utilities
38
+ - composite and constant recalculation pipelines
39
+ - import/export routines (when restoring history)
40
+
41
+ It is the primary mechanism for “jump to latest state” navigation.
42
+
43
+ ## How it works
44
+ The function performs two deterministic steps:
45
+
46
+ ### 1. Check if navigation is needed
47
+ If the current history index already points to the last entry, the function
48
+ performs no action. This avoids unnecessary snapshot restoration.
49
+
50
+ ### 2. Restore the last snapshot
51
+ If navigation is needed:
52
+ - `_history_index` is updated,
53
+ - the snapshot of the last entry is restored using `_restore_snapshot`.
54
+
55
+ This mutates the instance to reflect the most recent historical state.
56
+
57
+ ## Integration requirements
58
+ The function assumes the instance implements:
59
+
60
+ - **History internals**
61
+ `_history`, `_history_index`, `_history_count`
62
+
63
+ - **SnapshotMixin**
64
+ Provides `_restore_snapshot(snapshot)`.
65
+
66
+ Without these components, last‑entry navigation cannot operate correctly.
67
+
68
+ ## Why this function exists
69
+ Jumping to the latest state is a common operation in:
70
+
71
+ - debugging,
72
+ - interactive editing,
73
+ - undo/redo workflows,
74
+ - history import/export,
75
+ - composite recalculation.
76
+
77
+ This function encapsulates the minimal logic required to perform that jump
78
+ safely and deterministically.
79
+
80
+ ## Deterministic behavior
81
+ Navigation is guaranteed to be:
82
+
83
+ - index‑safe,
84
+ - stable across mutations,
85
+ - consistent with undo/redo semantics,
86
+ - compatible with diffing and debugging tools.
87
+
88
+ ## Stability guarantee
89
+ Any change to this function would affect:
90
+
91
+ - undo/redo behavior,
92
+ - navigation correctness,
93
+ - snapshot restoration,
94
+ - debugging tools.
95
+
96
+ Therefore, `go_to_last_history` is treated as a **core invariant** of the
97
+ history subsystem.
98
+
99
+ ## Notes
100
+ - This function is intentionally minimal and side‑effect‑free.
101
+ - It is not part of the public API; it is used internally by mixins.
102
+ - All structural logic is delegated to history internals and snapshot restoration.
103
+ """
@@ -0,0 +1,103 @@
1
+ from typing import TYPE_CHECKING
2
+ # Annotations
3
+ if TYPE_CHECKING:
4
+ from ......_core.protocols.mixins.state import HistoryProtocol
5
+
6
+
7
+ def history_redo(
8
+ self: "HistoryProtocol"
9
+ ) -> bool:
10
+ """
11
+ Moves forward to the next history entry (if available) and restores its snapshot.
12
+ """
13
+
14
+ # 1. Check if a forward move is possible
15
+ if self._history_index >= self._history_count - 1:
16
+ return False
17
+
18
+ # 2. Move to the next entry
19
+ self._history_index += 1
20
+ _, snapshot = self._history[self._history_index]
21
+ self._restore_snapshot(snapshot)
22
+ return True
23
+
24
+
25
+ _DESIGN_NOTES = """
26
+ # history_redo
27
+
28
+ ## Purpose
29
+ Moves forward in the history list and restores the snapshot of the next entry.
30
+ This function implements the forward half of the undo/redo navigation model.
31
+
32
+ ## Architectural role
33
+ `history_redo` is used by:
34
+
35
+ - `History.redo`
36
+ - interactive editing workflows
37
+ - debugging tools
38
+ - composite and constant recalculation pipelines
39
+ - history import/export routines (when replaying state transitions)
40
+
41
+ It provides deterministic forward navigation within the history subsystem.
42
+
43
+ ## How it works
44
+ The function performs two deterministic steps:
45
+
46
+ ### 1. Check if forward navigation is possible
47
+ If the current index already points to the last history entry, the function
48
+ returns `False` and performs no action.
49
+ This prevents invalid navigation and avoids unnecessary snapshot restoration.
50
+
51
+ ### 2. Restore the next snapshot
52
+ If navigation is possible:
53
+ - `_history_index` is incremented,
54
+ - the snapshot of the next entry is restored using `_restore_snapshot`,
55
+ - the function returns `True` to signal successful navigation.
56
+
57
+ ## Integration requirements
58
+ The function assumes the instance implements:
59
+
60
+ - **History internals**
61
+ `_history`, `_history_index`, `_history_count`
62
+
63
+ - **SnapshotMixin**
64
+ Provides `_restore_snapshot(snapshot)`.
65
+
66
+ Without these components, redo navigation cannot operate correctly.
67
+
68
+ ## Why this function exists
69
+ Undo/redo navigation is a core feature of:
70
+
71
+ - interactive editing,
72
+ - state debugging,
73
+ - reversible transformations,
74
+ - history replay,
75
+ - composite recalculation.
76
+
77
+ `history_redo` encapsulates the minimal logic required to move forward safely
78
+ and deterministically.
79
+
80
+ ## Deterministic behavior
81
+ Redo navigation is guaranteed to be:
82
+
83
+ - index‑safe,
84
+ - stable across mutations,
85
+ - consistent with undo semantics,
86
+ - compatible with diffing and debugging tools.
87
+
88
+ ## Stability guarantee
89
+ Any change to this function would affect:
90
+
91
+ - undo/redo behavior,
92
+ - navigation correctness,
93
+ - snapshot restoration,
94
+ - debugging tools.
95
+
96
+ Therefore, `history_redo` is treated as a **core invariant** of the history
97
+ subsystem.
98
+
99
+ ## Notes
100
+ - This function is intentionally minimal and side‑effect‑free.
101
+ - It is not part of the public API; it is used internally by mixins.
102
+ - All structural logic is delegated to history internals and snapshot restoration.
103
+ """
@@ -0,0 +1,104 @@
1
+ from typing import TYPE_CHECKING
2
+ # Annotations
3
+ if TYPE_CHECKING:
4
+ from ......_core.protocols.mixins.state import HistoryProtocol
5
+
6
+
7
+ def history_undo(
8
+ self: "HistoryProtocol"
9
+ ) -> bool:
10
+ """
11
+ Moves backward to the previous history entry (if available) and restores its snapshot.
12
+ """
13
+
14
+ # 1. Check if a backward move is possible
15
+ if self._history_index <= 0:
16
+ return False
17
+
18
+ # 2. Move to the previous entry
19
+ self._history_index -= 1
20
+ _, snapshot = self._history[self._history_index]
21
+ self._restore_snapshot(snapshot)
22
+ return True
23
+
24
+
25
+ _DESIGN_NOTES = """
26
+ # history_undo
27
+
28
+ ## Purpose
29
+ Moves backward in the history list and restores the snapshot of the previous
30
+ entry. This function implements the backward half of the undo/redo navigation
31
+ model.
32
+
33
+ ## Architectural role
34
+ `history_undo` is used by:
35
+
36
+ - `History.undo`
37
+ - interactive editing workflows
38
+ - debugging tools
39
+ - composite and constant recalculation pipelines
40
+ - history import/export routines (when replaying state transitions)
41
+
42
+ It provides deterministic backward navigation within the history subsystem.
43
+
44
+ ## How it works
45
+ The function performs two deterministic steps:
46
+
47
+ ### 1. Check if backward navigation is possible
48
+ If the current index already points to the first history entry, the function
49
+ returns `False` and performs no action.
50
+ This prevents invalid navigation and avoids unnecessary snapshot restoration.
51
+
52
+ ### 2. Restore the previous snapshot
53
+ If navigation is possible:
54
+ - `_history_index` is decremented,
55
+ - the snapshot of the previous entry is restored using `_restore_snapshot`,
56
+ - the function returns `True` to signal successful navigation.
57
+
58
+ ## Integration requirements
59
+ The function assumes the instance implements:
60
+
61
+ - **History internals**
62
+ `_history`, `_history_index`, `_history_count`
63
+
64
+ - **SnapshotMixin**
65
+ Provides `_restore_snapshot(snapshot)`.
66
+
67
+ Without these components, undo navigation cannot operate correctly.
68
+
69
+ ## Why this function exists
70
+ Undo/redo navigation is a core feature of:
71
+
72
+ - interactive editing,
73
+ - state debugging,
74
+ - reversible transformations,
75
+ - history replay,
76
+ - composite recalculation.
77
+
78
+ `history_undo` encapsulates the minimal logic required to move backward safely
79
+ and deterministically.
80
+
81
+ ## Deterministic behavior
82
+ Undo navigation is guaranteed to be:
83
+
84
+ - index‑safe,
85
+ - stable across mutations,
86
+ - consistent with redo semantics,
87
+ - compatible with diffing and debugging tools.
88
+
89
+ ## Stability guarantee
90
+ Any change to this function would affect:
91
+
92
+ - undo/redo behavior,
93
+ - navigation correctness,
94
+ - snapshot restoration,
95
+ - debugging tools.
96
+
97
+ Therefore, `history_undo` is treated as a **core invariant** of the history
98
+ subsystem.
99
+
100
+ ## Notes
101
+ - This function is intentionally minimal and side‑effect‑free.
102
+ - It is not part of the public API; it is used internally by mixins.
103
+ - All structural logic is delegated to history internals and snapshot restoration.
104
+ """
@@ -0,0 +1,31 @@
1
+ from .export_history_to_dict import export_history_to_dict
2
+ from .import_history_from_dict import import_history_from_dict
3
+
4
+
5
+ _DESIGN_NOTES = """
6
+ # History Transfer Utilities
7
+
8
+ ## Purpose
9
+ Provides import/export helpers used by the History mixin to serialize and
10
+ restore historical state. These utilities implement the core mechanics of:
11
+
12
+ - exporting history into a portable dictionary format,
13
+ - importing history with owner-class validation,
14
+ - restoring snapshots safely and atomically.
15
+
16
+ They form the transfer layer of the history subsystem and are used by
17
+ serialization pipelines, debugging tools, external replay utilities, and
18
+ cross‑process state transfer.
19
+
20
+ ## Components
21
+
22
+ | Component | Type | Description |
23
+ | :------------------------ | :--------| :------------------------------------------------------- |
24
+ | `export_history_to_dict` | Function | Exports history into a stable, portable dictionary. |
25
+ | `import_history_from_dict`| Function | Imports history with validation and atomic restoration. |
26
+
27
+ ## Notes
28
+ - These utilities are internal and not part of the public API.
29
+ - They rely on History internals, SnapshotMixin, and serialization metadata.
30
+ - They are treated as core invariants of the history subsystem.
31
+ """
@@ -0,0 +1,110 @@
1
+ from typing import TYPE_CHECKING
2
+ # Outers
3
+ from ....._common_logic.constants import OWNER_CLASS, HISTORY
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ......_core.protocols.mixins.state import HistoryProtocol
7
+ from ......_core.protocols.alias_typings import HistoryDict
8
+
9
+
10
+ def export_history_to_dict(
11
+ self: "HistoryProtocol"
12
+ ) -> "HistoryDict":
13
+ """
14
+ Exports the history into a portable dictionary format:
15
+ { _owner_class: ..., history: ( (timestamp, [values...]), ... ) }
16
+ """
17
+ return {
18
+ OWNER_CLASS: self.meta.owner_class,
19
+ HISTORY: self.history
20
+ }
21
+
22
+
23
+ _DESIGN_NOTES = """
24
+ # export_history_to_dict
25
+
26
+ ## Purpose
27
+ Exports the entire history of the instance into a portable, serialization‑friendly
28
+ dictionary format. This representation is used for:
29
+
30
+ - persistence,
31
+ - debugging,
32
+ - external tooling,
33
+ - state replay,
34
+ - cross‑process or cross‑machine transfer.
35
+
36
+ The exported structure is stable, deterministic, and independent of internal
37
+ implementation details.
38
+
39
+ ## Architectural role
40
+ `export_history_to_dict` is used by:
41
+
42
+ - `History.export_history_to_dict`
43
+ - serialization pipelines
44
+ - debugging tools
45
+ - history import/export utilities
46
+ - snapshot diffing and replay mechanisms
47
+
48
+ It provides a clean, minimal, and predictable representation of the history.
49
+
50
+ ## How it works
51
+ The function performs a single deterministic step:
52
+
53
+ ### 1. Build dictionary representation
54
+ Creates a dictionary containing:
55
+
56
+ - `_owner_class` — the class that owns the history (used for validation during import)
57
+ - `history` — a tuple of history entries, each entry being:
58
+ - a timestamp (`datetime`)
59
+ - a snapshot tuple of raw values
60
+
61
+ This structure is fully portable and safe for serialization.
62
+
63
+ ## Integration requirements
64
+ The function assumes the instance implements:
65
+
66
+ - **History internals**
67
+ `_history`, `_history_index`, `_history_count`
68
+
69
+ - **Serialization metadata**
70
+ `meta.owner_class`
71
+
72
+ Without these components, history export cannot operate correctly.
73
+
74
+ ## Why this function exists
75
+ History must be exportable for:
76
+
77
+ - debugging,
78
+ - persistence,
79
+ - external analysis,
80
+ - replaying state transitions,
81
+ - transferring state between processes or machines.
82
+
83
+ This function encapsulates the minimal logic required to produce a stable,
84
+ portable representation.
85
+
86
+ ## Deterministic behavior
87
+ The exported dictionary is guaranteed to be:
88
+
89
+ - stable across runs,
90
+ - independent of internal representation,
91
+ - safe for serialization,
92
+ - compatible with import pipelines,
93
+ - predictable for debugging and diffing.
94
+
95
+ ## Stability guarantee
96
+ Any change to this function would affect:
97
+
98
+ - serialization consistency,
99
+ - import behavior,
100
+ - debugging tools,
101
+ - replay mechanisms.
102
+
103
+ Therefore, `export_history_to_dict` is treated as a **core invariant** of the
104
+ history subsystem.
105
+
106
+ ## Notes
107
+ - This function is intentionally minimal and side‑effect‑free.
108
+ - It is not part of the public API; it is used internally by mixins.
109
+ - All structural logic is delegated to history internals and metadata.
110
+ """