simplibs-object 0.1.1__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.1.dist-info/METADATA +590 -0
  577. simplibs_object-0.1.1.dist-info/RECORD +580 -0
  578. simplibs_object-0.1.1.dist-info/WHEEL +5 -0
  579. simplibs_object-0.1.1.dist-info/licenses/LICENSE +21 -0
  580. simplibs_object-0.1.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,121 @@
1
+ from typing import TYPE_CHECKING, Any
2
+ # Outers
3
+ from ...._common_logic.immutability import with_composite
4
+ # Inners
5
+ from ._align_operand_type import _align_operand_type
6
+ # Annotations
7
+ if TYPE_CHECKING:
8
+ from ....._core.protocols.mixins.dunders.numeric import UnaryProtocol
9
+ from ....._core.protocols.mixins.dunders.numeric.internal_types import UnaryOperator
10
+
11
+
12
+ def execute_unary_op(
13
+ self: "UnaryProtocol",
14
+ operator: "UnaryOperator"
15
+ ) -> Any:
16
+ """
17
+ Fast modular executor for unary numeric operations.
18
+ Applies the operator to self.value and returns a new instance via
19
+ with_composite. Includes fallback for safe type alignment.
20
+ """
21
+
22
+ # 1. Attempt direct computation
23
+ try:
24
+ return with_composite(self, self.meta.name_snake, operator(self.value))
25
+
26
+ # 2. Attempt safe type alignment
27
+ except TypeError:
28
+
29
+ # 2.1 Align operand type
30
+ coerced = _align_operand_type(self, self.value)
31
+
32
+ # 2.2 Retry computation
33
+ try:
34
+ return with_composite(self, self.meta.name_snake, operator(coerced))
35
+
36
+ # 2.3 Give up if still invalid
37
+ except TypeError:
38
+ return NotImplemented
39
+
40
+
41
+ _DESIGN_NOTES = """
42
+ # execute_unary_op
43
+
44
+ ## Purpose
45
+ Provides the unified executor for all unary numeric dunder operations
46
+ (`__neg__`, `__pos__`, `__abs__`).
47
+ It ensures that unary operations:
48
+
49
+ - apply the operator safely,
50
+ - support lazy fallback type alignment,
51
+ - return new composite instances,
52
+ - behave consistently across all numeric mixins.
53
+
54
+ ---
55
+
56
+ ## Architectural Role
57
+ This helper is used internally by the Unary mixin to implement all unary dunders.
58
+
59
+ It provides:
60
+
61
+ - operand extraction (always `self.value`),
62
+ - safe type alignment,
63
+ - composite instance creation,
64
+ - unified fallback behavior.
65
+
66
+ It is the core unary engine for Simple numeric objects.
67
+
68
+ ---
69
+
70
+ ## Behavior
71
+
72
+ ### 1. Direct unary computation
73
+ Executes:
74
+
75
+ ```
76
+ operator(self.value)
77
+ ```
78
+
79
+ If successful, returns a new composite instance:
80
+
81
+ ```
82
+ with_composite(self, self.meta.name_snake, result)
83
+ ```
84
+
85
+ Unary operations **always** produce composites — they propagate through inner
86
+ nodes exactly like arithmetic operations.
87
+
88
+ ### 2. Lazy fallback type alignment
89
+ If the operation fails with `TypeError`, the function attempts safe alignment:
90
+
91
+ ```
92
+ coerced = _align_operand_type(self, self.value)
93
+ ```
94
+
95
+ This allows operations like:
96
+
97
+ - `-Decimal(int_value)`
98
+ - `abs(Fraction(int_value))`
99
+ - `+float(int_value)`
100
+
101
+ but avoids unsafe conversions (e.g., `float → Decimal`).
102
+
103
+ ### 3. Second attempt
104
+ The operator is retried with the aligned operand.
105
+
106
+ If it still fails, the function returns:
107
+
108
+ ```
109
+ NotImplemented
110
+ ```
111
+
112
+ This signals Python to fall back to alternative resolution or raise an error.
113
+
114
+ ---
115
+
116
+ ## Notes
117
+ - This function is internal and not part of the public API.
118
+ - It guarantees deterministic unary behavior across all numeric mixins.
119
+ - It keeps mixin implementations minimal and declarative.
120
+ - Unary operations never mutate the instance — they always return a new composite.
121
+ """
@@ -0,0 +1,96 @@
1
+ from typing import TYPE_CHECKING
2
+ # Outers
3
+ from ...base_class import SimpleMixin
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ...._core.protocols.mixins.dunders.representation import ValueDisplayProtocol
7
+
8
+
9
+ class ValueDisplay(SimpleMixin):
10
+ """
11
+ Overrides __repr__ and __str__ so the object presents itself as the
12
+ raw value it wraps.
13
+
14
+ Changes how the object is displayed so it represents its value.
15
+ Intended only for atomic (constant-only) types that should behave as
16
+ "value-like" objects (e.g. Decimal, UUID, PhoneNumber...).
17
+
18
+ ValueDisplay is a common mixin, but it is not a standard one — it is
19
+ a specialized, opt-in, constant-only mixin, meant to be used only
20
+ when you want the object to behave like a "value object" (e.g.
21
+ Decimal, UUID, Path, Enum, ...).
22
+ """
23
+
24
+ # ----------------------------------------
25
+ # Basic interface
26
+ # ----------------------------------------
27
+
28
+ # Compatibility declaration
29
+ _constant_only = True
30
+
31
+ # Slot definition
32
+ __slots__ = ()
33
+
34
+ # ----------------------------------------
35
+ # Methods - REPR / STR
36
+ # ----------------------------------------
37
+
38
+ def __repr__(
39
+ self: "ValueDisplayProtocol"
40
+ ) -> str:
41
+ """
42
+ Technical representation of the object in the format:
43
+ ClassName(value_repr)
44
+ Used for debugging and logging.
45
+ """
46
+ return f"{self.meta.class_name}({self.value!r})"
47
+
48
+ def __str__(
49
+ self: "ValueDisplayProtocol"
50
+ ) -> str:
51
+ """
52
+ User-facing representation of the object.
53
+ Returns the plain value converted to a string.
54
+ """
55
+ return str(self.value)
56
+
57
+
58
+ _DESIGN_NOTES = """
59
+ # ValueDisplay
60
+
61
+ ## Purpose
62
+ Makes an atomic instance *look and print* like the raw value it wraps,
63
+ instead of like a generic object. With this mixin, `print(price)` shows
64
+ `19.99`, not something like `<SimpleConstant object at 0x...>`.
65
+
66
+ > For newcomers: `__repr__` is the "developer-facing" representation
67
+ > (what you see in a debugger, a REPL, or inside a list/dict print),
68
+ > while `__str__` is the "user-facing" one (what `print()` and `str()`
69
+ > use). This mixin gives each a distinct but related shape.
70
+
71
+ ## Compatibility
72
+ - `_constant_only = True` — this is a deliberate opt-in restriction, not
73
+ a technical limitation. Value-like display only makes sense for atoms
74
+ that model a single "value" (`Decimal`, `UUID`, `PhoneNumber`,
75
+ `Path`-like types) — not for composites, which are made of multiple
76
+ named parts and are better served by a structural, field-by-field
77
+ representation (see `InstanceBase`'s default `__repr__`/`__str__`,
78
+ which this mixin deliberately does *not* touch on composites).
79
+
80
+ ## Logic
81
+ - `__repr__` returns `ClassName(value_repr)` — keeps the class identity
82
+ visible (so `PhoneNumber('+420...')` still tells you what it is) while
83
+ showing the wrapped value using its own `repr()`.
84
+ - `__str__` returns just `str(self.value)` — drops the class name
85
+ entirely, so the object reads exactly like its underlying value in
86
+ print statements, f-strings, and string concatenation.
87
+
88
+ ## Notes
89
+ - Opt-in by design: most Simple instances should *not* use this mixin,
90
+ since hiding the class identity from `str()` can be misleading for
91
+ types where "which class this is" matters more than "what the raw
92
+ value looks like."
93
+ - Pairs naturally with `ValueFormatting`, which adds `format()`/
94
+ `__format__`/`__bytes__`/`__bool__` without touching `__repr__`/
95
+ `__str__` — the two mixins split representation concerns cleanly.
96
+ """
@@ -0,0 +1,144 @@
1
+ from typing import TYPE_CHECKING
2
+ # Outers
3
+ from ...base_class import SimpleMixin
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ...._core.protocols.mixins.dunders.representation import ValueDisplayProtocol
7
+
8
+
9
+ class ValueFormatting(SimpleMixin):
10
+ """
11
+ Representation and conversion dunders tied to the object's value.
12
+ Does not touch __repr__ / __str__ — those are defined in
13
+ InstanceBase.
14
+ Works for both atomic and composite types, since both have a value.
15
+ """
16
+
17
+ # ----------------------------------------
18
+ # Basic interface
19
+ # ----------------------------------------
20
+
21
+ # Slot definition
22
+ __slots__ = ()
23
+
24
+ # ----------------------------------------
25
+ # Methods = FORMAT
26
+ # ----------------------------------------
27
+
28
+ def format(
29
+ self: "ValueDisplayProtocol",
30
+ pattern: str | None = None
31
+ ) -> str:
32
+ """
33
+ Formats the instance's value according to the given pattern or mask.
34
+ If no pattern is given, uses the mask from metadata (meta.mask),
35
+ if it exists. Suitable for formatting numbers, text, and simple
36
+ composite values.
37
+ """
38
+ value = self.value
39
+ mask = pattern or getattr(self.meta, "mask", None)
40
+
41
+ if mask and isinstance(value, (str, int, float)):
42
+ # If pattern is a format string template like '{:03d}' or has replacement fields
43
+ if "{" in mask and "}" in mask:
44
+ return mask.format(value)
45
+ # Otherwise treat as a standard format specifier (e.g. '03d', '.2f')
46
+ try:
47
+ return format(value, mask)
48
+ except (ValueError, TypeError):
49
+ return mask.format(value)
50
+
51
+ return str(value)
52
+
53
+ def __format__(
54
+ self: "ValueDisplayProtocol",
55
+ format_spec: str = ""
56
+ ) -> str:
57
+ """
58
+ Support for f-string formatting and the built-in format() function.
59
+ Enables syntax like: f"{obj:03d}" or format(obj, "03d").
60
+ """
61
+ if not format_spec:
62
+ return self.format()
63
+ return format(self.value, format_spec)
64
+
65
+ # ----------------------------------------
66
+ # Methods = BYTES / BOOL
67
+ # ----------------------------------------
68
+
69
+ def __bytes__(
70
+ self: "ValueDisplayProtocol"
71
+ ) -> bytes:
72
+ """
73
+ Converts the instance's value to bytes.
74
+ Supports:
75
+ - bytes -> returned directly
76
+ - bytearray, memoryview -> bytes(...)
77
+ - str -> UTF-8 encode
78
+ Other types raise TypeError.
79
+ """
80
+ value = self.value
81
+
82
+ if isinstance(value, bytes):
83
+ return value
84
+
85
+ if isinstance(value, (bytearray, memoryview)):
86
+ return bytes(value)
87
+
88
+ if isinstance(value, str):
89
+ return value.encode("utf-8")
90
+
91
+ raise TypeError(
92
+ f"Cannot convert {self.meta.class_name} "
93
+ f"(type={type(value).__name__}) to bytes."
94
+ )
95
+
96
+ def __bool__(
97
+ self: "ValueDisplayProtocol"
98
+ ) -> bool:
99
+ """
100
+ The object's truthiness matches the truthiness of its value.
101
+ """
102
+ return bool(self.value)
103
+
104
+
105
+ _DESIGN_NOTES = """
106
+ # ValueFormatting
107
+
108
+ ## Purpose
109
+ Adds value-driven formatting and conversion behavior — `format()`,
110
+ f-string support via `__format__`, `bytes(obj)`, and `bool(obj)` — all
111
+ routed through the instance's `.value`, without touching how the object
112
+ prints via `__repr__`/`__str__` (that's `ValueDisplay`'s job, or the
113
+ default from `InstanceBase`).
114
+
115
+ ## Compatibility
116
+ - No compatibility flags — unlike `ValueDisplay`, this mixin is *not*
117
+ constant-only. Both atoms and composites have a `.value`, so both can
118
+ reasonably be formatted, converted to bytes, or tested for truthiness.
119
+
120
+ ## Logic & Architecture
121
+ - **Distinction between `format()` and `__format__`:**
122
+ - `__format__(format_spec)` directly delegates to Python's built-in
123
+ `format(self.value, format_spec)`. When using standard f-strings like
124
+ `f"{instance:03d}"`, Python passes `"03d"` (a format specification, not
125
+ a template containing `{}`). Forwarding this to standard `str.format()`
126
+ would fail or return raw specifier strings.
127
+ - `format(pattern=...)` serves as a higher-level convenience method that
128
+ accepts either template strings (e.g. `"{:03d}"`, `"{}_formatted"`), format
129
+ specifiers (e.g. `"03d"`), or blueprint-level masks via `meta.mask`.
130
+ - **`__bytes__`:**
131
+ Handles common convertible types explicitly (`bytes` passthrough,
132
+ `bytearray`/`memoryview` via `bytes(...)`, `str` via UTF-8 encoding)
133
+ and raises a descriptive `TypeError` for anything else.
134
+ - **`__bool__`:**
135
+ Forwards to `bool(self.value)` to ensure that truthiness directly reflects
136
+ the wrapped inner value.
137
+
138
+ ## Notes
139
+ - Deliberately independent from `ValueDisplay` — a class can use one,
140
+ both, or neither depending on whether it needs value-like *printing*,
141
+ value-like *formatting/conversion*, or both.
142
+ - `meta.mask` is an optional, blueprint-level setting; its absence is not
143
+ an error, `format()` just degrades to `str(value)`.
144
+ """
@@ -0,0 +1,24 @@
1
+ from .ValueDisplay import ValueDisplay
2
+ from .ValueFormatting import ValueFormatting
3
+
4
+
5
+ _DESIGN_NOTES = """
6
+ # Representation Dunders
7
+
8
+ ## Purpose
9
+ Controls how a Simple instance presents itself as text and how its
10
+ value converts to formatted strings, bytes, and booleans.
11
+
12
+ ## Components
13
+
14
+ | Component | Type | Description |
15
+ | :------------------- | :---- | :---------------------------------------------------------------- |
16
+ | `ValueDisplay` | Mixin | `__repr__` / `__str__` — value-like display, `_constant_only`. |
17
+ | `ValueFormatting` | Mixin | `format()` / `__format__` / `__bytes__` / `__bool__`. |
18
+
19
+ ## Notes
20
+ - `ValueDisplay` is opt-in and constant-only by design — most instances
21
+ should keep the default structural `__repr__`/`__str__`.
22
+ - `ValueFormatting` works for both atoms and composites and does not
23
+ touch `__repr__`/`__str__`, so the two mixins can be combined freely.
24
+ """
@@ -0,0 +1,48 @@
1
+ _DESIGN_NOTES = """
2
+ # Others Package Overview
3
+
4
+ The `others` package groups every mixin that adds Simple-ecosystem-
5
+ specific behavior rather than implementing a standard Python protocol.
6
+ Where `dunders` covers hooks Python itself looks for, `others` covers
7
+ capabilities the Simple system defines on its own terms: immutable
8
+ change methods, numeric stepping, property ergonomics, and state
9
+ management.
10
+
11
+ This package does not re-export any components. All functionality is
12
+ accessed directly through the corresponding sub-packages.
13
+
14
+ ---
15
+
16
+ ## Sub-Packages
17
+
18
+ ### 1. immutable
19
+ The "change without mutating" API for immutable instances:
20
+ - generic core methods (`with_constant`, `with_composite`, ...),
21
+ - per-inner generated setters (`with_<name>(value)`).
22
+
23
+ ### 2. numerical
24
+ Safe, bounded numeric stepping via `Stepper` controllers:
25
+ - one stepper for an atom's own value,
26
+ - one stepper per inner of a composite.
27
+
28
+ ### 3. properties
29
+ Ergonomic property-based access:
30
+ - direct attribute access to a composite's inners,
31
+ - shortcut properties over frequently used metadata fields.
32
+
33
+ ### 4. state
34
+ State management for mutable instances:
35
+ - remembering construction-time state,
36
+ - dirty tracking,
37
+ - full undo/redo history,
38
+ - runtime read-only locking.
39
+
40
+ ---
41
+
42
+ ## Notes
43
+ - This package is internal and not intended for direct user interaction.
44
+ - Each sub-package is self-contained and exposes its own public API.
45
+ - `core_mixins` is deliberately kept at the package root rather than
46
+ under `others`, since it is shared infrastructure used by both
47
+ `dunders` and `others` alike, not a sibling category of either.
48
+ """
@@ -0,0 +1,142 @@
1
+ from typing import Any, TYPE_CHECKING
2
+ # Outers
3
+ from ...core_mixins import Infrastructure
4
+ from ..._common_logic.immutability import (
5
+ with_constants,
6
+ with_constant,
7
+ with_composite,
8
+ with_any,
9
+ create_new_instance
10
+ )
11
+ # Inners
12
+ from ._validations import raise_with_changes_input_not_dict
13
+ # Annotations
14
+ if TYPE_CHECKING:
15
+ from ...._core.protocols.mixins.immutable import ImmutableMethodsProtocol
16
+ from ...._core.protocols.alias_typings import ChangesTuple, ChangesDict
17
+
18
+
19
+ class ImmutableMethods(Infrastructure):
20
+ """
21
+ Mixin providing the immutable API for working with instances:
22
+
23
+ - with_constants(...)
24
+ - with_constant(...)
25
+ - with_composite(...)
26
+
27
+ Construction of immutable classes (getter-only value, removal of
28
+ setters, removal of mutating methods, immutable inners) is now
29
+ handled directly in make_atom_class / make_composite_class.
30
+ """
31
+
32
+ # ----------------------------------------
33
+ # Basic interface
34
+ # ----------------------------------------
35
+
36
+ # Compatibility declaration
37
+ _immutable_only = True
38
+
39
+ # Slot definition
40
+ __slots__ = ()
41
+
42
+ # ----------------------------------------
43
+ # Methods - Immutable API (core)
44
+ # ----------------------------------------
45
+
46
+ def with_constants(
47
+ self: "ImmutableMethodsProtocol",
48
+ changes_tuple: "ChangesTuple | None" = None
49
+ ) -> "ImmutableMethodsProtocol":
50
+ """Creates a new immutable instance based on multiple changes."""
51
+ return with_constants(self, changes_tuple)
52
+
53
+ def with_constant(
54
+ self: "ImmutableMethodsProtocol",
55
+ name: str,
56
+ new_value: Any
57
+ ) -> "ImmutableMethodsProtocol":
58
+ """Creates a new immutable instance by changing a single constant."""
59
+ return with_constant(self, name, new_value)
60
+
61
+ def with_composite(
62
+ self: "ImmutableMethodsProtocol",
63
+ name: str,
64
+ new_value: Any
65
+ ) -> "ImmutableMethodsProtocol":
66
+ """Creates a new immutable instance by changing a single composite."""
67
+ return with_composite(self, name, new_value)
68
+
69
+ # ----------------------------------------
70
+ # Methods - Immutable API (extended)
71
+ # ----------------------------------------
72
+
73
+ def with_changes(
74
+ self: "ImmutableMethodsProtocol",
75
+ changes_dict: "ChangesDict"
76
+ ) -> "ImmutableMethodsProtocol":
77
+ """Method allowing multiple constant changes to be given as a dict."""
78
+ if not isinstance(changes_dict, dict):
79
+ raise_with_changes_input_not_dict(self, changes_dict)
80
+ return with_any(self, tuple(changes_dict.items()))
81
+
82
+ def with_value(
83
+ self: "ImmutableMethodsProtocol",
84
+ new_value: Any
85
+ ) -> "ImmutableMethodsProtocol":
86
+ """Method for changing the main value - a convenience alias."""
87
+ return self.with_composite(self.meta.name_snake, new_value)
88
+
89
+ def duplicate(
90
+ self: "ImmutableMethodsProtocol"
91
+ ) -> "ImmutableMethodsProtocol":
92
+ """Method returning a new instance with the same values."""
93
+ return create_new_instance(self, self._build_snapshot())
94
+
95
+
96
+ _DESIGN_NOTES = """
97
+ # ImmutableMethods
98
+
99
+ ## Purpose
100
+ The core "change without mutating" API for immutable instances —
101
+ `with_constant`, `with_composite`, `with_constants`, plus the more
102
+ ergonomic `with_changes` (dict-based) and `with_value` (alias for
103
+ changing the top-level value) and `duplicate` (identical copy).
104
+
105
+ > For newcomers: this is the classic immutable-object pattern — instead
106
+ > of `obj.value = 10`, you write `new_obj = obj.with_value(10)` and the
107
+ > original `obj` is left untouched. Every method here returns a new
108
+ > instance rather than modifying `self`.
109
+
110
+ ## Compatibility
111
+ - `_immutable_only = True` — the whole premise of "return a new
112
+ instance instead of mutating" only makes sense for immutable objects;
113
+ mutable instances get their equivalent API elsewhere (direct attribute
114
+ assignment, or the `Call`/`Inplace` dunder mixins).
115
+
116
+ ## Logic
117
+ - The three "core" methods (`with_constants`, `with_constant`,
118
+ `with_composite`) are thin wrappers delegating straight to the
119
+ matching top-level utility functions — this class adds no logic beyond
120
+ routing.
121
+ - `with_changes(changes_dict)` validates the input is actually a `dict`
122
+ (raising a descriptive error via `raise_with_changes_input_not_dict`
123
+ otherwise), then converts it to the tuple-of-pairs shape `with_any`
124
+ expects.
125
+ - `with_value(new_value)` is sugar for
126
+ `self.with_composite(self.meta.name_snake, new_value)` — i.e. "change
127
+ the value this instance itself represents," using its own name as the
128
+ composite key.
129
+ - `duplicate()` builds a snapshot of the current state and feeds it into
130
+ `create_new_instance` — producing an equal-but-distinct instance
131
+ without going through any change logic at all.
132
+
133
+ ## Notes
134
+ - The docstring's mention that immutable class construction (getter-only
135
+ values, no setters) happens in `make_atom_class`/`make_composite_class`
136
+ is a pointer to *where else* to look — this mixin only supplies the
137
+ "change" API, not the structural immutability itself.
138
+ - `duplicate()` is functionally similar to `Copyable.__copy__` in the
139
+ dunders package — both build from a snapshot — but is exposed here as
140
+ a named, discoverable method rather than only reachable via
141
+ `copy.copy()`.
142
+ """
@@ -0,0 +1,111 @@
1
+ from typing import Any, TYPE_CHECKING
2
+ # Inners
3
+ from .ImmutableMethods import ImmutableMethods
4
+ # Annotations
5
+ if TYPE_CHECKING:
6
+ from ...._core.protocols.mixins.immutable import ImmutableMethodsWithInnersProtocol
7
+ from ...._core.protocols.instance import SimpleInstanceLike
8
+
9
+
10
+ class ImmutableWithInners(ImmutableMethods):
11
+ """
12
+ Adds, on top of the base class's basic methods, dedicated methods for
13
+ every inner.
14
+
15
+ Guarantees the presence of dynamically generated immutable methods
16
+ (setters) for each inner element (e.g. `obj.with_uzel(value)`).
17
+ Every one of these methods produces a new, transformed instance (Self).
18
+ """
19
+
20
+ # ----------------------------------------
21
+ # Basic interface
22
+ # ----------------------------------------
23
+
24
+ # Compatibility declaration
25
+ _immutable_only = True
26
+ _composite_only = True
27
+
28
+ # Slot definition
29
+ __slots__ = ()
30
+
31
+ # ----------------------------------------
32
+ # Hook for modifying the instance class
33
+ # ----------------------------------------
34
+
35
+ @staticmethod
36
+ def __extend_instance_class__(
37
+ instance_cls: "SimpleInstanceLike"
38
+ ) -> "SimpleInstanceLike":
39
+ """
40
+ Internal method for attaching elements to the class, before the
41
+ initialization process.
42
+ """
43
+
44
+ # 1. Iterate over nodes
45
+ for name in instance_cls.meta.node_names_set:
46
+
47
+ # 2. Method definition
48
+ # (All use the composite method, since it forwards constants to with_constant)
49
+ def method(self: "ImmutableMethodsWithInnersProtocol", value: Any, _name: str=name):
50
+ return self.with_composite(_name, value)
51
+
52
+ # 3. Set the inner element's attributes
53
+ method_name = f"with_{name}"
54
+ method.__name__ = method_name
55
+ method.__doc__ = (
56
+ f"Immutable setter for the value `{name}`.\n"
57
+ f"Returns a new immutable instance with `{name}` changed."
58
+ )
59
+
60
+ # 4. Create the method attribute
61
+ setattr(instance_cls, method_name, method)
62
+
63
+ # 5. Return the modified class
64
+ return instance_cls
65
+
66
+
67
+ _DESIGN_NOTES = """
68
+ # ImmutableWithInners
69
+
70
+ ## Purpose
71
+ Generates a dedicated `with_<name>(value)` method for every inner of a
72
+ composite, so instead of writing `obj.with_composite("uzel", value)`
73
+ generically, callers get a specific, autocomplete-friendly
74
+ `obj.with_uzel(value)` for each field the blueprint actually defines.
75
+
76
+ > For newcomers: this is code generation at class-creation time, not at
77
+ > instance-creation time — the methods are attached once, when the
78
+ > instance class itself is built, and every instance of that class shares
79
+ > them.
80
+
81
+ ## Compatibility
82
+ - `_immutable_only = True` — inherited requirement, since every generated
83
+ method returns a new instance rather than mutating.
84
+ - `_composite_only = True` — per-inner setters only make sense where
85
+ inners exist; an atom has nothing to generate methods for.
86
+
87
+ ## Logic
88
+ `__extend_instance_class__` runs once per instance class, before
89
+ initialization:
90
+ 1. Iterates `instance_cls.meta.node_names_set` — every inner's name.
91
+ 2. For each name, defines a small closure `method(self, value, _name=name)`
92
+ that forwards to `self.with_composite(_name, value)`. The default
93
+ argument `_name=name` is what pins each generated method to its own
94
+ name — without it, every closure would share the loop variable and
95
+ all end up pointing at the last name iterated.
96
+ 3. Names the method `with_<name>`, gives it a generated docstring, and
97
+ attaches it to the class via `setattr`.
98
+
99
+ The comment "all use the composite method, since it forwards constants to
100
+ with_constant" explains why there's no special-casing between constant
101
+ inners and composite inners here — `with_composite` already knows how to
102
+ route a constant change down to `with_constant` internally.
103
+
104
+ ## Notes
105
+ - This is one of the (apparently few) mixins that actually uses the
106
+ `__extend_instance_class__` hook, alongside property-generating mixins
107
+ like `InnersProperty` and `Equalizer` — most mixins only use
108
+ `init_mixins`.
109
+ - The generated methods are true instance-class attributes, not computed
110
+ per-instance — inspectable via `dir()` or `help()` on the class itself.
111
+ """