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,81 @@
1
+ from typing import NoReturn, TYPE_CHECKING
2
+ # Outers
3
+ from .....exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ....protocols.classes import SimpleObjectProtocol
7
+
8
+
9
+ def raise_too_many_positional_args_error(
10
+ cls: "SimpleObjectProtocol",
11
+ given_count: int,
12
+ allowed_count: int,
13
+ ) -> NoReturn:
14
+ """Raises an error when too many positional arguments are passed to calculate_value."""
15
+
16
+ class_name = cls.__name__
17
+
18
+ raise SimpleRuntimeError(
19
+ error_name="INVALID PARAMETERS",
20
+ label="args",
21
+ value=f"{given_count} positional arguments",
22
+ expected=f"At most {allowed_count} positional arguments matching inner elements",
23
+ problem=(
24
+ f"The class '{class_name}' received more positional arguments than "
25
+ f"the number of defined inner elements."
26
+ ),
27
+ context=(
28
+ f"During parameter processing for '{class_name}.calculate_value', the "
29
+ f"system detected an argument count mismatch."
30
+ ),
31
+ how_to_fix=(
32
+ f"Provide no more than {allowed_count} positional arguments.",
33
+ "If you intended to use named parameters, pass them as keyword arguments.",
34
+ "Ensure that each positional argument corresponds to an inner element "
35
+ "in the order defined by the class.",
36
+ ),
37
+ exception=ValueError,
38
+ )
39
+
40
+
41
+ _DESIGN_NOTES = """
42
+ # raise_too_many_positional_args_error
43
+
44
+ ## Purpose
45
+ Signals that the user passed more positional arguments to `calculate_value` than
46
+ the number of inner elements defined in the composite class. This error is
47
+ user-facing and helps developers understand how to correctly supply parameters
48
+ to composite objects.
49
+
50
+ ---
51
+
52
+ ## Behavior
53
+ - Compares the number of provided positional arguments with the number of
54
+ declared inner elements.
55
+ - Raises a structured `SimpleRuntimeError` when the count exceeds the allowed
56
+ limit.
57
+ - Explains the mismatch and provides actionable guidance.
58
+
59
+ ---
60
+
61
+ ## Why this error exists
62
+ Composite objects define their structure through `_inners`.
63
+ Each inner corresponds to one parameter of `_logic`.
64
+
65
+ Passing more positional arguments than inner elements indicates a misuse of the
66
+ API — either:
67
+
68
+ - the user misunderstood the order of parameters, or
69
+ - they intended to use keyword arguments instead.
70
+
71
+ This error ensures the system remains predictable and prevents silent failures.
72
+
73
+ ---
74
+
75
+ ## Notes
76
+ - This function will be used inside `process_calculate_value_params`.
77
+ - The public-facing documentation belongs to `SimpleObject.calculate_value`,
78
+ not to this internal helper.
79
+ - The error uses `ValueError` as the underlying exception type for consistency
80
+ with Python’s parameter handling semantics.
81
+ """
@@ -0,0 +1,77 @@
1
+ from typing import NoReturn, TYPE_CHECKING
2
+ # Outers
3
+ from .....exceptions import SimpleRuntimeError
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ....protocols.classes import SimpleObjectProtocol
7
+
8
+
9
+ def raise_unknown_parameter_error(
10
+ cls: "SimpleObjectProtocol",
11
+ unknown_params: list[str],
12
+ ) -> NoReturn:
13
+ """Raises an error when unknown keyword parameters are passed to calculate_value."""
14
+
15
+ class_name = cls.__name__
16
+ formatted = ", ".join(f"'{p}'" for p in unknown_params)
17
+
18
+ raise SimpleRuntimeError(
19
+ error_name="INVALID PARAMETERS",
20
+ label="kwargs",
21
+ value=formatted,
22
+ expected="Only parameters matching the inner elements of the composite",
23
+ problem=(
24
+ f"The class '{class_name}' does not define the following parameters: "
25
+ f"{formatted}."
26
+ ),
27
+ context=(
28
+ f"During parameter processing for '{class_name}.calculate_value', "
29
+ f"the system detected keyword arguments that do not correspond to "
30
+ f"any inner element."
31
+ ),
32
+ how_to_fix=(
33
+ "Remove the unknown keyword arguments.",
34
+ "Ensure that each keyword argument matches the name of an inner element.",
35
+ "Check the '_inners' definition of the class to see the valid parameter names.",
36
+ ),
37
+ exception=ValueError,
38
+ )
39
+
40
+
41
+ _DESIGN_NOTES = """
42
+ # raise_unknown_parameter_error
43
+
44
+ ## Purpose
45
+ Signals that the user passed keyword arguments to `calculate_value` that do not
46
+ match any inner element defined in the composite class. This error is user-facing
47
+ and prevents silent misuse of the API.
48
+
49
+ ---
50
+
51
+ ## Behavior
52
+ - Collects all unknown keyword parameters.
53
+ - Raises a structured `SimpleRuntimeError` describing the mismatch.
54
+ - Provides actionable guidance on how to correct the call.
55
+
56
+ ---
57
+
58
+ ## Why this error exists
59
+ Composite objects define their structure through `_inners`.
60
+ Each inner element corresponds to one valid parameter name.
61
+
62
+ If the user passes a keyword argument that does not match any inner:
63
+
64
+ - the system cannot map the value to an inner element,
65
+ - the composite value cannot be computed correctly,
66
+ - the call becomes ambiguous or meaningless.
67
+
68
+ This error ensures predictable behavior and prevents silent failures.
69
+
70
+ ---
71
+
72
+ ## Notes
73
+ - Used inside `process_calculate_value_params`.
74
+ - The public-facing documentation belongs to `SimpleObject.calculate_value`.
75
+ - Uses `ValueError` as the underlying exception type for consistency with Python’s
76
+ argument handling semantics.
77
+ """
@@ -0,0 +1,20 @@
1
+ from .create_value_property import create_value_property
2
+ from .create_instance_property import create_instance_property
3
+ from .create_properties_for_inner import create_properties_for_inner
4
+
5
+ _DESIGN_NOTES = """
6
+ # Property Builders Sub-Package
7
+
8
+ ## Purpose
9
+ Provides unified generators for public-facing properties used across atomic and
10
+ composite runtime instances. These builders define the external API for reading
11
+ and mutating instance values, as well as accessing inner instance objects.
12
+
13
+ ## Internal Components Registry
14
+
15
+ | Component | Type | Description |
16
+ | :-------------------------- | :------- | :-------------------------------------------------------------------------- |
17
+ | `create_value_property` | Function | Builds the unified `value` property (getter + optional setter). |
18
+ | `create_instance_property` | Function | Builds read-only properties exposing inner instance objects. |
19
+ | `create_properties_for_inner` | Function | Generates paired value/instance properties for composite inner elements. |
20
+ """
@@ -0,0 +1,66 @@
1
+ from typing import Any, TYPE_CHECKING
2
+ from operator import attrgetter
3
+ # Annotations
4
+ if TYPE_CHECKING:
5
+ from ...protocols.metadata import SimpleMetadataLike
6
+
7
+
8
+ def create_instance_property(
9
+ inner_meta: "SimpleMetadataLike",
10
+ path: tuple[str, ...],
11
+ ) -> property:
12
+ """Creates a read-only property for accessing an inner instance."""
13
+
14
+ # 1. Prepare inner instance resolver
15
+ get_inner_instance = attrgetter(*path)
16
+
17
+ # 2. Create getter
18
+ def getter(self) -> Any:
19
+ return get_inner_instance(self)
20
+
21
+ # 3. Add return annotation
22
+ getter.__annotations__ = {"return": Any}
23
+
24
+ # 4. Build docstring
25
+ doc_string = (
26
+ f"Instance of the inner element `{inner_meta.name_snake}`.\n\n"
27
+ f"The getter returns the instance of the atom or composition stored in the "
28
+ f"private slot `{inner_meta.name_private}`.\n"
29
+ f"This property is read-only – assigning a new instance is not allowed."
30
+ )
31
+
32
+ # 5. Return read-only property
33
+ return property(
34
+ fget=getter,
35
+ doc=doc_string,
36
+ )
37
+
38
+
39
+ _DESIGN_NOTES = """
40
+ # create_instance_property
41
+
42
+ ## Purpose
43
+ Provides a read-only property that exposes the *instance* of an inner element
44
+ (atom or composite). This is the structural counterpart to `value` properties:
45
+ while `value` exposes the normalized value, this property exposes the underlying
46
+ instance object.
47
+
48
+ ## Behavior
49
+ 1. Uses `attrgetter(*path)` to resolve the inner instance efficiently.
50
+ 2. Returns the inner instance directly, without wrapping or transforming it.
51
+ 3. The property is strictly read-only:
52
+ - No setter is generated.
53
+ - Users cannot replace inner instances manually.
54
+ 4. The property is generated for:
55
+ - direct inners of composite classes,
56
+ - nested inners when mixins expand the inner tree.
57
+
58
+ ## Notes
59
+ - This property is essential for introspection, debugging, and advanced user
60
+ interactions with composite structures.
61
+ - It complements `create_value_property`, which exposes the *value* of the inner
62
+ node.
63
+ - Inner instances are always stored in private slots (e.g., `_motor`), and this
64
+ property provides the safe public API for accessing them.
65
+
66
+ """
@@ -0,0 +1,97 @@
1
+ from typing import TYPE_CHECKING
2
+ # Inners
3
+ from .create_value_property import create_value_property
4
+ from .create_instance_property import create_instance_property
5
+ # Annotations
6
+ if TYPE_CHECKING:
7
+ from ...protocols.metadata import SimpleMetadataLike
8
+ from ...protocols.alias_typings import PathTuple
9
+
10
+
11
+ def create_properties_for_inner(
12
+ inner_meta: "SimpleMetadataLike",
13
+ path: "PathTuple | ()" = (),
14
+ *,
15
+ mutable: bool = True,
16
+ ) -> dict[str, property]:
17
+ """Generates value and instance properties for a single inner element."""
18
+
19
+ # 1. Prepare output dictionary
20
+ property_dict = {}
21
+
22
+ # 2. Resolve names and path
23
+ name_snake = inner_meta.name_snake
24
+ instance_path = path + (inner_meta.name_private,)
25
+
26
+ # 3. Create value property
27
+ value_property = create_value_property(
28
+ inner_meta,
29
+ is_constant=inner_meta.is_constant,
30
+ mutable=mutable,
31
+ path=instance_path,
32
+ )
33
+
34
+ # 4. Create instance property
35
+ instance_property = create_instance_property(
36
+ inner_meta,
37
+ instance_path,
38
+ )
39
+
40
+ # 5. Insert properties into dictionary
41
+ property_dict[name_snake] = value_property
42
+ property_dict[f"{name_snake}_instance"] = instance_property
43
+
44
+ # 6. Return property mapping
45
+ return property_dict
46
+
47
+
48
+ _DESIGN_NOTES = """
49
+ # create_properties_for_inner
50
+
51
+ ## Purpose
52
+ Generates the two public properties associated with every inner element of a
53
+ composite instance:
54
+
55
+ 1. `<inner_name>` — exposes the value of the inner element (read/write depending
56
+ on mutability).
57
+ 2. `<inner_name>_instance` — exposes the inner instance object (read-only).
58
+
59
+ These properties form the public API for navigating and manipulating composite
60
+ structures.
61
+
62
+ ---
63
+
64
+ ## Behavior
65
+ 1. **Path Resolution**
66
+ - The function receives a `path` representing the attribute chain leading to
67
+ the inner element.
68
+ - It extends the path with the inner's private slot name, producing the full
69
+ lookup path for both properties.
70
+
71
+ 2. **Value Property**
72
+ - Created via `create_value_property`.
73
+ - Provides access to the normalized value of the inner element.
74
+ - Supports mutation only when the instance is mutable.
75
+ - Composite setters automatically decompose values into deeper inner nodes.
76
+
77
+ 3. **Instance Property**
78
+ - Created via `create_instance_property`.
79
+ - Provides read-only access to the inner instance object.
80
+ - Essential for introspection and advanced manipulation.
81
+
82
+ 4. **Dictionary Output**
83
+ - Returns a dictionary mapping:
84
+ - `<name_snake>` → value property
85
+ - `<name_snake>_instance` → instance property
86
+ - This dictionary is consumed by composite class builders and mixins.
87
+
88
+ ---
89
+
90
+ ## Notes
91
+ - This function is used both for direct inners and for nested inners when mixins
92
+ expand the composite tree.
93
+ - The separation of value and instance properties ensures a clean and predictable
94
+ API: values are mutable (when allowed), instances are not.
95
+ - The function is intentionally minimal; all logic is delegated to the underlying
96
+ property builders.
97
+ """
@@ -0,0 +1,98 @@
1
+ from typing import Optional, TYPE_CHECKING
2
+ # Inners
3
+ from .value_helpers import create_value_getter
4
+ from .value_helpers import create_value_setter
5
+ # Annotations
6
+ if TYPE_CHECKING:
7
+ from ...protocols.metadata import SimpleMetadataLike
8
+
9
+
10
+ def create_value_property(
11
+ meta: "SimpleMetadataLike",
12
+ *,
13
+ is_constant: bool = True,
14
+ mutable: bool = True,
15
+ path: Optional[tuple[str, ...]] = None,
16
+ ) -> property:
17
+ """Creates a unified value property for atomic and composite instances."""
18
+
19
+ # 1. Create getter
20
+ getter = create_value_getter(meta, path)
21
+
22
+ # 2. Build docstring (getter part)
23
+ doc_string = (
24
+ f"Value of type `{meta.value_type_name}`.\n\n"
25
+ f"Getter returns the value "
26
+ f"{'of this element' if path is None else 'of the inner element'}.\n"
27
+ )
28
+
29
+ # 3. Immutable → getter only
30
+ if not mutable:
31
+ return property(
32
+ fget=getter,
33
+ doc=doc_string,
34
+ )
35
+
36
+ # 4. Create setter
37
+ setter = create_value_setter(meta, is_constant, path)
38
+
39
+ # 5. Extend docstring (setter part)
40
+ if is_constant:
41
+ doc_string += (
42
+ "The setter normalizes the value, stores it, and "
43
+ "triggers an update cascade upwards."
44
+ )
45
+ else:
46
+ doc_string += (
47
+ "The setter decomposes the input value and distributes it "
48
+ "among the internal elements of the composition."
49
+ )
50
+
51
+ # 6. Return full property
52
+ return property(
53
+ fget=getter,
54
+ fset=setter,
55
+ doc=doc_string,
56
+ )
57
+
58
+
59
+ _DESIGN_NOTES = """
60
+ # create_value_property
61
+
62
+ ## Purpose
63
+ Creates the public-facing `value` property for both atomic and composite
64
+ instances. This property is the primary interface through which users read or
65
+ modify the value of an instance or any of its inner elements.
66
+
67
+ ## Behavior
68
+ 1. **Getter**
69
+ - Always returns the normalized value.
70
+ - If `path is None`, it reads `self._value` (root value).
71
+ - If `path` is provided, it resolves the inner instance and returns its `.value`.
72
+
73
+ 2. **Setter**
74
+ - Generated only when `mutable=True`.
75
+ - Atomic mode (`is_constant=True`):
76
+ - Writes the value via `_root_value_setter`.
77
+ - Triggers upward recalculation.
78
+ - Composite mode (`is_constant=False`):
79
+ - Requires `meta.is_decomposeable=True`.
80
+ - Writes the root value.
81
+ - Decomposes the value into inner nodes via `_recalculate_inners`.
82
+
83
+ 3. **Inner Properties**
84
+ - Composite instances generate additional `value` properties for each inner
85
+ element using the same mechanism.
86
+ - This ensures that every node in the composite tree exposes a consistent
87
+ `value` interface.
88
+
89
+ ## Notes
90
+ - The property is intentionally thin: all mutation logic is delegated to
91
+ `create_value_setter`, and all read logic to `create_value_getter`.
92
+ - Atomic and composite instances share the same property interface, making the
93
+ system uniform and predictable.
94
+ - Composite setters are guarded by `meta.is_decomposeable` to prevent invalid
95
+ direct assignments.
96
+ - Inner properties behave identically to root properties, enabling recursive
97
+ value manipulation throughout the composite tree.
98
+ """
@@ -0,0 +1,18 @@
1
+ from .create_value_getter import create_value_getter
2
+ from .create_value_setter import create_value_setter
3
+
4
+ _DESIGN_NOTES = """
5
+ # Property Value Helpers Sub-Package
6
+
7
+ ## Purpose
8
+ Contains low-level functional generators used internally by property builders.
9
+ These helpers encapsulate the core logic for reading and mutating normalized
10
+ values stored inside atomic and composite instances.
11
+
12
+ ## Internal Components Registry
13
+
14
+ | Component | Type | Description |
15
+ | :-------------------- | :------- | :------------------------------------------------------------------------- |
16
+ | `create_value_getter` | Function | Generates optimized getter closures for root and inner value access. |
17
+ | `create_value_setter` | Function | Generates setter closures handling normalization, decomposition, and logs. |
18
+ """
@@ -0,0 +1,52 @@
1
+ from typing import Any, TYPE_CHECKING, Callable
2
+ from operator import attrgetter
3
+ # Annotations
4
+ if TYPE_CHECKING:
5
+ from ....protocols.metadata import SimpleMetadataLike
6
+ from ....protocols.instance import SimpleInstanceLike
7
+ from ....protocols.alias_typings import PathTuple
8
+
9
+
10
+ def create_value_getter(
11
+ meta: "SimpleMetadataLike",
12
+ path: "PathTuple | None",
13
+ ) -> Callable:
14
+ """Creates a getter for root or inner value access."""
15
+
16
+ # Root getter
17
+ if path is None:
18
+ def getter(self: "SimpleInstanceLike") -> Any:
19
+ return self._value
20
+
21
+ # Inner getter
22
+ else:
23
+ get_inner_instance = attrgetter(*path)
24
+
25
+ def getter(self: "SimpleInstanceLike") -> Any:
26
+ return get_inner_instance(self).value
27
+
28
+ getter.__annotations__ = {"return": meta.value_type}
29
+ return getter
30
+
31
+
32
+ _DESIGN_NOTES = """
33
+ # create_value_getter
34
+
35
+ ## Purpose
36
+ Generates a unified getter function for both root-level and inner-level value
37
+ properties. The getter is intentionally identical for atomic and composite
38
+ instances: it always returns the current normalized value stored in the instance.
39
+
40
+ ## Behavior
41
+ - If `path is None`, the getter returns `self._value`.
42
+ - If `path` is provided, the getter resolves the inner instance using
43
+ `operator.attrgetter` and returns its `.value`.
44
+ - The return type annotation is injected dynamically based on metadata.
45
+
46
+ ## Notes
47
+ - Getter logic is intentionally minimal and side-effect free.
48
+ - Composite vs atomic behavior is handled entirely in the setter; the getter
49
+ remains uniform across all instance types.
50
+ - Using `attrgetter` avoids repeated attribute traversal and keeps the getter
51
+ fast and allocation-free.
52
+ """
@@ -0,0 +1,95 @@
1
+ from typing import Any, TYPE_CHECKING, Callable
2
+ from operator import attrgetter
3
+ # Outers
4
+ from ...object_methods.validations import raise_class_not_decomposeable
5
+ # Inners
6
+ from .validations import raise_locked_value_error
7
+ # Annotations
8
+ if TYPE_CHECKING:
9
+ from ....protocols.metadata import SimpleMetadataLike
10
+ from ....protocols.instance import SimpleInstanceLike
11
+ from ....protocols.alias_typings import PathTuple
12
+
13
+
14
+ def create_value_setter(
15
+ meta: "SimpleMetadataLike",
16
+ is_constant: bool = False,
17
+ path: "PathTuple | None" = None,
18
+ ) -> Callable:
19
+ """Creates a setter for root or inner value properties (atomic or composite)."""
20
+
21
+ # 1. Prepare inner resolver
22
+ get_inner = attrgetter(*path) if path is not None else None
23
+
24
+ # 2. Create setter
25
+ def setter(self: "SimpleInstanceLike", value: Any) -> None:
26
+
27
+ # 2.1 Locked instance cannot be modified
28
+ if self._locked:
29
+ raise_locked_value_error(value, self.__class__.__name__)
30
+
31
+ # 2.2 Composite setter requires decomposeable metadata
32
+ if not is_constant and not meta.is_decomposeable:
33
+ raise_class_not_decomposeable(meta)
34
+
35
+ # 2.3 Resolve target instance (root or inner)
36
+ instance = get_inner(self) if get_inner is not None else self
37
+
38
+ # 2.4 Write value and propagate recalculation upwards
39
+ # noinspection PyProtectedMember
40
+ instance._root_value_setter(value, recalculate_up=True)
41
+
42
+ # 2.5 Recalculate inners for composite values
43
+ if not is_constant:
44
+ # noinspection PyProtectedMember
45
+ instance._recalculate_inners()
46
+
47
+ # 2.6 Log only root-level value changes
48
+ if path is None:
49
+ from simplibs.object.settings.logging import log_value_event
50
+ log_value_event(self.__class__, value, event="set")
51
+
52
+ # 3. Add annotations
53
+ setter.__annotations__ = {"value": meta.value_type, "return": None}
54
+
55
+ # 4. Return setter
56
+ return setter
57
+
58
+
59
+ _DESIGN_NOTES = """
60
+ # create_value_setter
61
+
62
+ ## Purpose
63
+ Generates a unified setter function for both root-level and inner-level value
64
+ properties. The setter encapsulates all mutation semantics for atomic and
65
+ composite instances, including normalization, decomposition, recalculation, and
66
+ logging.
67
+
68
+ ## Behavior
69
+ - `is_constant=True`:
70
+ - Treats the value as atomic.
71
+ - Writes the normalized value via `_root_value_setter`.
72
+ - Triggers upward recalculation (`recalculate_up=True`).
73
+ - `is_constant=False`:
74
+ - Treats the value as composite.
75
+ - Requires `meta.is_decomposeable=True` (otherwise raises
76
+ `raise_class_not_decomposeable`).
77
+ - Writes the root value via `_root_value_setter`.
78
+ - Calls `_recalculate_inners()` to distribute the value into inner nodes.
79
+
80
+ - `path is None`:
81
+ - Operates on the root instance (`self`).
82
+ - Logs the value change via `log_value_event`.
83
+
84
+ - `path is not None`:
85
+ - Resolves an inner instance using `attrgetter(*path)`.
86
+ - Operates on that inner instance without logging.
87
+
88
+ ## Notes
89
+ - Locking (`self._locked`) prevents any mutation once the instance is frozen.
90
+ - Composite behavior is strictly guarded by metadata (`is_decomposeable`).
91
+ - Logging is intentionally limited to root-level changes to avoid noise from
92
+ inner recalculations.
93
+ - The setter is side-effectful by design: it updates value, triggers recalculation,
94
+ and optionally logs the event.
95
+ """
@@ -0,0 +1,16 @@
1
+ from .raise_locked_value_error import raise_locked_value_error
2
+
3
+
4
+ _DESIGN_NOTES = """
5
+ # Value Helper Validation Sub-Package
6
+
7
+ ## Purpose
8
+ Provides structured error generators used by value property builders. These
9
+ helpers ensure consistent diagnostics when value mutation is not permitted.
10
+
11
+ ## Internal Components Registry
12
+
13
+ | Component | Type | Description |
14
+ | :------------------------ | :------- | :------------------------------------------------ |
15
+ | `raise_locked_value_error` | Function | Raised when a locked instance attempts mutation. |
16
+ """