simplibs-rules 0.1.0__tar.gz

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 (156) hide show
  1. simplibs_rules-0.1.0/LICENSE +21 -0
  2. simplibs_rules-0.1.0/PKG-INFO +372 -0
  3. simplibs_rules-0.1.0/README.md +344 -0
  4. simplibs_rules-0.1.0/pyproject.toml +60 -0
  5. simplibs_rules-0.1.0/setup.cfg +4 -0
  6. simplibs_rules-0.1.0/src/simplibs/rules/__init__.py +943 -0
  7. simplibs_rules-0.1.0/src/simplibs/rules/base_class/Rule.py +322 -0
  8. simplibs_rules-0.1.0/src/simplibs/rules/base_class/_NotARule.py +33 -0
  9. simplibs_rules-0.1.0/src/simplibs/rules/base_class/__init__.py +17 -0
  10. simplibs_rules-0.1.0/src/simplibs/rules/containers/AllOf.py +147 -0
  11. simplibs_rules-0.1.0/src/simplibs/rules/containers/AnyOf.py +146 -0
  12. simplibs_rules-0.1.0/src/simplibs/rules/containers/Compose.py +146 -0
  13. simplibs_rules-0.1.0/src/simplibs/rules/containers/ForEach.py +120 -0
  14. simplibs_rules-0.1.0/src/simplibs/rules/containers/NoneOf.py +112 -0
  15. simplibs_rules-0.1.0/src/simplibs/rules/containers/Not.py +97 -0
  16. simplibs_rules-0.1.0/src/simplibs/rules/containers/__init__.py +28 -0
  17. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/__init__.py +22 -0
  18. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/as_predicate.py +84 -0
  19. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/build_child_exception.py +39 -0
  20. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/describe_rule.py +72 -0
  21. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/validations/__init__.py +1 -0
  22. simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/validations/raise_invalid_predicate.py +22 -0
  23. simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/__init__.py +23 -0
  24. simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_container_param_not_type_error.py +52 -0
  25. simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_requires_at_least_one_rule_error.py +37 -0
  26. simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_rule_param_not_callable.py +54 -0
  27. simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/validate_compose_param_is_callable.py +72 -0
  28. simplibs_rules-0.1.0/src/simplibs/rules/predicates/__init__.py +103 -0
  29. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/__init__.py +18 -0
  30. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/accepts_one_positional_argument.py +127 -0
  31. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/format_container.py +50 -0
  32. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/__init__.py +40 -0
  33. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/__init__.py +21 -0
  34. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_has_length_param_conflict_error.py +53 -0
  35. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_regex_param_invalid_pattern_error.py +43 -0
  36. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_user_rule_param_wrong_arity.py +53 -0
  37. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/__init__.py +32 -0
  38. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_bounds_inverted_error.py +78 -0
  39. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_incomparable_error.py +65 -0
  40. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_missing_error.py +77 -0
  41. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_callable_error.py +51 -0
  42. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_container_error.py +75 -0
  43. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_non_negative_integer_error.py +88 -0
  44. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_string_error.py +77 -0
  45. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_type_error.py +65 -0
  46. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/__init__.py +24 -0
  47. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_integer.py +73 -0
  48. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_not_zero.py +69 -0
  49. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_primitive_number.py +76 -0
  50. simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_remainder_in_range.py +58 -0
  51. simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/CloseTo.py +149 -0
  52. simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/DivisibleBy.py +120 -0
  53. simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/HasRemainder.py +137 -0
  54. simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/__init__.py +21 -0
  55. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsEmpty.py +101 -0
  56. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsFalse.py +81 -0
  57. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsNone.py +81 -0
  58. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsTrue.py +80 -0
  59. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/NotEmpty.py +100 -0
  60. simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/__init__.py +25 -0
  61. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/AllUnique.py +124 -0
  62. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasItem.py +131 -0
  63. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasKey.py +104 -0
  64. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasKeys.py +115 -0
  65. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsContainer.py +99 -0
  66. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsSubsetOf.py +139 -0
  67. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsSupersetOf.py +138 -0
  68. simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/__init__.py +29 -0
  69. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/Equals.py +87 -0
  70. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/GreaterOrEqual.py +106 -0
  71. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/GreaterThan.py +106 -0
  72. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/InRange.py +166 -0
  73. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/LessOrEqual.py +106 -0
  74. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/LessThan.py +106 -0
  75. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/NotEquals.py +88 -0
  76. simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/__init__.py +29 -0
  77. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/HasAttribute.py +95 -0
  78. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/HasLength.py +177 -0
  79. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsCallable.py +81 -0
  80. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsDataclass.py +84 -0
  81. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsHashable.py +91 -0
  82. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsInstance.py +105 -0
  83. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsIterable.py +90 -0
  84. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsSubclass.py +122 -0
  85. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsType.py +82 -0
  86. simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/__init__.py +34 -0
  87. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/Is.py +88 -0
  88. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/IsIn.py +144 -0
  89. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/IsNot.py +89 -0
  90. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/NotIn.py +145 -0
  91. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/UserRule.py +118 -0
  92. simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/__init__.py +24 -0
  93. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsBool.py +96 -0
  94. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsDecimal.py +83 -0
  95. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsEven.py +107 -0
  96. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsFinite.py +104 -0
  97. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsFloat.py +75 -0
  98. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsInfinity.py +97 -0
  99. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsInteger.py +118 -0
  100. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsNan.py +98 -0
  101. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsNumber.py +96 -0
  102. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsOdd.py +94 -0
  103. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsPi.py +138 -0
  104. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsPrimitiveNumber.py +87 -0
  105. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsZero.py +109 -0
  106. simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/__init__.py +42 -0
  107. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/Contains.py +114 -0
  108. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/EndsWith.py +114 -0
  109. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAlnum.py +107 -0
  110. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAlpha.py +111 -0
  111. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAscii.py +109 -0
  112. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsBlank.py +98 -0
  113. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsDigitString.py +115 -0
  114. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsLowercase.py +111 -0
  115. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsString.py +104 -0
  116. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsSubstringOf.py +114 -0
  117. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsTitlecase.py +130 -0
  118. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsUppercase.py +96 -0
  119. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/NotBlank.py +98 -0
  120. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/Regex.py +126 -0
  121. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/StartsWith.py +114 -0
  122. simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/__init__.py +44 -0
  123. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/IsAny.py +114 -0
  124. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/IsTyping.py +100 -0
  125. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/__init__.py +26 -0
  126. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/ORIGIN_TABLE.py +112 -0
  127. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/__init__.py +35 -0
  128. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_annotated_rule.py +106 -0
  129. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_any_of_rule.py +73 -0
  130. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_callable_rule.py +63 -0
  131. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_elements_rule.py +109 -0
  132. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_key_value_rule.py +65 -0
  133. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_literal_rule.py +60 -0
  134. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_tuple_rule.py +111 -0
  135. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_type_rule.py +114 -0
  136. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_validations/__init__.py +16 -0
  137. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_validations/raise_unsupported_annotation_error.py +63 -0
  138. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/build_typing_rule.py +131 -0
  139. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/__init__.py +20 -0
  140. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/get_supported_origins.py +42 -0
  141. simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/is_supported_annotation.py +60 -0
  142. simplibs_rules-0.1.0/src/simplibs/rules/testing/__init__.py +40 -0
  143. simplibs_rules-0.1.0/src/simplibs/rules/testing/assert_rule_contract.py +198 -0
  144. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/__init__.py +27 -0
  145. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_build_exception.py +149 -0
  146. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_is_valid.py +90 -0
  147. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_param_error.py +77 -0
  148. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_raise_invalid.py +91 -0
  149. simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_validate.py +107 -0
  150. simplibs_rules-0.1.0/src/simplibs/rules/tools/__init__.py +16 -0
  151. simplibs_rules-0.1.0/src/simplibs/rules/tools/raise_invalid.py +84 -0
  152. simplibs_rules-0.1.0/src/simplibs_rules.egg-info/PKG-INFO +372 -0
  153. simplibs_rules-0.1.0/src/simplibs_rules.egg-info/SOURCES.txt +154 -0
  154. simplibs_rules-0.1.0/src/simplibs_rules.egg-info/dependency_links.txt +1 -0
  155. simplibs_rules-0.1.0/src/simplibs_rules.egg-info/requires.txt +5 -0
  156. simplibs_rules-0.1.0/src/simplibs_rules.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Dalibor Sova (Sudip2708)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,372 @@
1
+ Metadata-Version: 2.4
2
+ Name: simplibs-rules
3
+ Version: 0.1.0
4
+ Summary: Composable, explicit validation rules โ€” pure predicates, zero transformation.
5
+ Author-email: "Dalibor Sova (Sudip2708)" <daliborsova@seznam.cz>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/simplibs/simplibs-rules
8
+ Project-URL: Repository, https://github.com/simplibs/simplibs-rules
9
+ Project-URL: Issues, https://github.com/simplibs/simplibs-rules/issues
10
+ Project-URL: Changelog, https://github.com/simplibs/simplibs-rules/blob/main/CHANGELOG.md
11
+ Keywords: validation,validator,rules,predicates,data-validation,type-hints,testing,simplibs,simplibs-rules,developer-tools
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Topic :: Software Development :: Testing
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: simplibs-exception>=1.1.2
24
+ Requires-Dist: simplibs-sentinels>=0.1.0
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7.0; extra == "dev"
27
+ Dynamic: license-file
28
+
29
+ # ๐Ÿ“ `simplibs-rules`
30
+
31
+ [![PyPI](https://img.shields.io/pypi/v/simplibs-rules)](https://pypi.org/project/simplibs-rules/)
32
+ [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
33
+ [![Licence](https://img.shields.io/badge/licence-MIT-green)](https://github.com/simplibs/simplibs-rules/blob/main/LICENSE)
34
+
35
+ **Composable, explicit validation rules โ€” pure predicates, zero transformation.**
36
+
37
+ A lightweight, high-performance Python library defining atomic, composable validation
38
+ rules built on a clean `Rule` abstraction. Rules combine naturally with plain
39
+ Python operators (`|`, `&`, `~`), carry structured, human-readable diagnostics
40
+ on failure via [`simplibs-exception`](https://pypi.org/project/simplibs-exception/), and โ€” through integrated type
41
+ decomposition โ€” understand Python's typing annotations natively.
42
+
43
+ ```python
44
+ from simplibs.rules import is_integer, greater_than, IsTyping
45
+
46
+ # Operator composition
47
+ positive_int = is_integer & greater_than(0)
48
+
49
+ positive_int.is_valid(5) # -> True
50
+ positive_int.is_valid(-5) # -> False
51
+
52
+ # Type annotation decomposition
53
+ rule = IsTyping(list[int] | None)
54
+ rule.is_valid([1, 2, 3]) # -> True
55
+ rule.is_valid(["1", "2"]) # -> False
56
+ ```
57
+
58
+ > `simplibs-rules` is the foundational rule engine of the ecosystem. If you just want
59
+ > to validate values in your own code without composing rules by hand, see
60
+ > [`simplibs-validate`](https://pypi.org/project/simplibs-validate/), which builds
61
+ > `validate()`, ready-made `validate_*` wrappers, and self-validating decorators on
62
+ > top of this library.
63
+
64
+ ---
65
+
66
+ ## ๐Ÿงญ The Core Philosophy
67
+
68
+ Most validation approaches force a choice: write ad-hoc `if`/`raise` checks scattered
69
+ through your codebase, or adopt heavy data-transformation frameworks.
70
+ `simplibs-rules` is a **pure predicate engine**. A `Rule` never transforms or coerces
71
+ a value; it only ever answers *"does this value satisfy me?"* and, on failure,
72
+ provides structured, precise diagnostic exceptions.
73
+
74
+ Every rule is a small, composable object. You combine them with plain Python
75
+ operators instead of writing nested configuration or custom functions:
76
+
77
+ ```python
78
+ is_string & has_length(min_length=3) & not_blank
79
+ ```
80
+
81
+ By decoupling rule definitions and evaluation logic from validation
82
+ invocation wrappers, `simplibs-rules` serves as the foundational rule engine
83
+ for higher-level validation tools โ€” such as [`simplibs-validate`](https://pypi.org/project/simplibs-validate/)
84
+ (the `validate()` entry point, ready-made wrappers, self-validating decorators) and the
85
+ upcoming `simplibs-types` (reusable, named validated types built on `Rule`).
86
+
87
+ ---
88
+
89
+ ## ๐Ÿ“ฆ Installation
90
+
91
+ ```bash
92
+ pip install simplibs-rules
93
+ ```
94
+
95
+ ---
96
+
97
+ ## ๐Ÿš€ Quick Start in 60 Seconds
98
+
99
+ ### Level 1: Evaluating rules directly
100
+
101
+ ```python
102
+ from simplibs.rules import is_integer, greater_than
103
+
104
+ rule = is_integer & greater_than(0)
105
+
106
+ rule.is_valid(5) # -> True
107
+ rule.is_valid(-5) # -> False
108
+
109
+ # Raising structured exceptions
110
+ if not rule.is_valid(-5):
111
+ raise rule.build_exception(-5, value_name="age")
112
+ ```
113
+
114
+ ### Level 2: Rule execution with return options
115
+
116
+ ```python
117
+ rule = is_integer & greater_than(0)
118
+
119
+ rule.validate(5) # -> True
120
+ rule.validate(5, return_value=True) # -> 5
121
+ rule.validate(-5, return_bool=True) # -> False
122
+ rule.validate(-5) # -> raises ValidateError
123
+ ```
124
+
125
+ ### Level 3: Annotation-driven rules
126
+
127
+ ```python
128
+ from simplibs.rules import IsTyping, build_typing_rule
129
+
130
+ # Converts complex typing constructs directly into rule trees:
131
+ typing_rule = IsTyping(dict[str, int])
132
+
133
+ typing_rule.is_valid({"apples": 5, "oranges": 10}) # -> True
134
+ typing_rule.is_valid({"apples": "5"}) # -> False
135
+ ```
136
+
137
+ ### Level 4: Unconditional direct triggers
138
+
139
+ When control flow guards in your application have already detected a failure condition
140
+ inline, use `raise_invalid()` to bypass rule evaluation entirely and construct the
141
+ diagnostic exception immediately:
142
+
143
+ ```python
144
+ from simplibs.rules import raise_invalid, is_integer
145
+
146
+ value = -5
147
+
148
+ if value < 0:
149
+ # Bypasses evaluation and directly raises the structured exception card
150
+ raise_invalid(value, is_integer, value_name="age", context="Must be non-negative")
151
+ ```
152
+
153
+ ---
154
+
155
+ ## ๐Ÿ› ๏ธ Architecture & Package Structure
156
+
157
+ ```
158
+ src/simplibs/rules/
159
+ โ”œโ”€โ”€ base_class/ โ—„โ”€โ”€ Abstract base class Rule & internal helpers (_NotARule)
160
+ โ”‚ โ”œโ”€โ”€ Rule.py
161
+ โ”‚ โ””โ”€โ”€ _NotARule.py
162
+ โ”œโ”€โ”€ containers/ โ—„โ”€โ”€ Rule combinators (AllOf, AnyOf, Not, NoneOf, ForEach, Compose)
163
+ โ”œโ”€โ”€ predicates/ โ—„โ”€โ”€ Single-purpose predicate rules
164
+ โ”‚ โ”œโ”€โ”€ arithmetic/ โ—„โ”€โ”€ CloseTo, DivisibleBy, HasRemainder
165
+ โ”‚ โ”œโ”€โ”€ checkers/ โ—„โ”€โ”€ IsEmpty, NotEmpty, IsNone, IsTrue, IsFalse
166
+ โ”‚ โ”œโ”€โ”€ collections/ โ—„โ”€โ”€ IsContainer, HasItem, HasKey, HasKeys, AllUnique, IsSubsetOf, IsSupersetOf
167
+ โ”‚ โ”œโ”€โ”€ comparisons/ โ—„โ”€โ”€ Equals, NotEquals, GreaterThan, GreaterOrEqual, LessThan, LessOrEqual, InRange
168
+ โ”‚ โ”œโ”€โ”€ introspection/ โ—„โ”€โ”€ IsInstance, IsType, IsSubclass, IsDataclass, IsCallable, IsHashable, IsIterable, HasAttribute, HasLength
169
+ โ”‚ โ”œโ”€โ”€ logic/ โ—„โ”€โ”€ Is, IsNot, IsIn, NotIn, UserRule
170
+ โ”‚ โ”œโ”€โ”€ numeric/ โ—„โ”€โ”€ IsBool, IsInteger, IsFloat, IsDecimal, IsNumber, IsPrimitiveNumber, IsZero, IsNan, IsInfinity, IsPi
171
+ โ”‚ โ”œโ”€โ”€ strings/ โ—„โ”€โ”€ IsString, Contains, IsSubstringOf, StartsWith, EndsWith, Regex, IsBlank, NotBlank
172
+ โ”‚ โ””โ”€โ”€ typing/ โ—„โ”€โ”€ Annotation-driven evaluation (IsAny, IsTyping, build_typing_rule)
173
+ โ”œโ”€โ”€ tools/ โ—„โ”€โ”€ Operational helper utilities
174
+ โ”‚ โ””โ”€โ”€ raise_invalid.py โ—„โ”€โ”€ Unconditional exception trigger (bypasses logic evaluation)
175
+ โ””โ”€โ”€ testing/ โ—„โ”€โ”€ Testing contracts for Rule implementations
176
+ โ””โ”€โ”€ assert_rule_contract.py
177
+ ```
178
+
179
+ ---
180
+
181
+ ## ๐Ÿงฉ The `Rule` Class
182
+
183
+ Every rule in this library inherits from `Rule`. It defines the mandatory
184
+ contract (`is_valid`, `build_exception`) and provides full composition
185
+ capabilities out of the box.
186
+
187
+ ```python
188
+ class Rule(ABC):
189
+
190
+ @abstractmethod
191
+ def is_valid(self, value: Any) -> bool:
192
+ """Return True if the tested value satisfies the rule, otherwise False."""
193
+ raise NotImplementedError
194
+
195
+ @abstractmethod
196
+ def build_exception(
197
+ self,
198
+ value: Any,
199
+ value_name: str | None = None,
200
+ context: str | None = None,
201
+ ) -> Exception:
202
+ """Create and return a structured exception describing the validation failure."""
203
+ raise NotImplementedError
204
+
205
+ def __call__(self, value: Any) -> bool:
206
+ """Allow using the rule instance directly as a predicate function."""
207
+ return self.is_valid(value)
208
+
209
+ def validate(
210
+ self,
211
+ value: Any,
212
+ *,
213
+ value_name: str | None = None,
214
+ context: str | None = None,
215
+ return_bool: bool = False,
216
+ return_value: bool = False,
217
+ ) -> Any:
218
+ """Validate a value against this rule."""
219
+ if self.is_valid(value):
220
+ return value if return_value else True
221
+
222
+ if return_bool:
223
+ return False
224
+
225
+ raise self.build_exception(value, value_name=value_name, context=context)
226
+
227
+ def annotated(self, type_: type) -> Any:
228
+ """Wrap this rule as `typing.Annotated[type_, self]` for type hints."""
229
+ return Annotated[type_, self]
230
+
231
+ # Operators for logical composition with @overload support for non-rule callables
232
+ @overload
233
+ def __or__(self, other: _NotARule) -> Any: ...
234
+ @overload
235
+ def __or__(self, other: Rule | Callable[[Any], bool]) -> Rule: ...
236
+
237
+ @overload
238
+ def __and__(self, other: _NotARule) -> Any: ...
239
+ @overload
240
+ def __and__(self, other: Rule | Callable[[Any], bool]) -> Rule: ...
241
+
242
+ def __invert__(self) -> Rule: ...
243
+ ```
244
+
245
+ โžก๏ธ Full method-by-method reference: [README_RULE_CLASS](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_CLASS.md)
246
+
247
+ ---
248
+
249
+ ## ๐Ÿ“– Rule Quick Reference
250
+
251
+ Every built-in `Rule` is exposed in two ways: as its **class** (`IsInteger`),
252
+ and as a **snake_case shortcut** (`is_integer`) โ€” a pre-instantiated object
253
+ for zero-parameter rules, or the class itself for parameterized ones.
254
+ Both are fully interchangeable.
255
+
256
+ ### `containers/` โ€” Composing other rules
257
+
258
+ | Class | Shortcut | Description / Parameters |
259
+ |-----------|------------|----------------------------------------------------------------|
260
+ | `AllOf` | `all_of` | Logical AND across multiple rules (`*rules`). Behind `&`. |
261
+ | `AnyOf` | `any_of` | Logical OR across multiple rules (`*rules`). Behind `\|`. |
262
+ | `Compose` | `compose` | Transforms value before checking (`transformer, validator`). |
263
+ | `ForEach` | `for_each` | Validates every item in an iterable (`rule`). |
264
+ | `NoneOf` | `none_of` | Value must satisfy none of the given rules (`*rules`). |
265
+ | `Not` | `negate` | Logical NOT for a single rule (`rule`). Behind `~`. |
266
+
267
+ โžก๏ธ [README_RULE_CONTAINERS](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_CONTAINERS.md)
268
+
269
+ ### `predicates/` โ€” Atomic predicates
270
+
271
+ * **`arithmetic/`**: `CloseTo`, `DivisibleBy`, `HasRemainder` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_ARITHMETIC.md)
272
+ * **`checkers/`**: `IsEmpty`, `NotEmpty`, `IsNone`, `IsTrue`, `IsFalse` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_CHECKERS.md)
273
+ * **`collections/`**: `IsContainer`, `HasItem`, `HasKey`, `HasKeys`, `AllUnique`, `IsSubsetOf`, `IsSupersetOf` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_COLLECTIONS.md)
274
+ * **`comparisons/`**: `Equals`, `NotEquals`, `GreaterThan`, `GreaterOrEqual`, `LessThan`, `LessOrEqual`, `InRange` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_COMPARISONS.md)
275
+ * **`introspection/`**: `IsInstance`, `IsType`, `IsSubclass`, `IsDataclass`, `IsCallable`, `IsHashable`, `IsIterable`, `HasAttribute`, `HasLength` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_INTROSPECTION.md)
276
+ * **`logic/`**: `Is`, `IsNot`, `IsIn`, `NotIn`, `UserRule` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_LOGIC.md)
277
+ * **`numeric/`**: `IsBool`, `IsInteger`, `IsFloat`, `IsDecimal`, `IsNumber`, `IsPrimitiveNumber`, `IsZero`, `IsNan`, `IsInfinity`, `IsPi` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_NUMERIC.md)
278
+ * **`strings/`**: `IsString`, `Contains`, `IsSubstringOf`, `StartsWith`, `EndsWith`, `Regex`, `IsBlank`, `NotBlank` โ€” [README](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_PREDICATE_STRINGS.md)
279
+
280
+ ### `predicates/typing/` โ€” Annotation-driven evaluation
281
+
282
+ | Class / Function | Shortcut | Description |
283
+ |----------------------|-------------|----------------------------------------------------------|
284
+ | `IsAny` | `is_any` | Always passes (`True`). Represents `typing.Any`. |
285
+ | `IsTyping` | `is_typing` | Recursively converts an annotation into a `Rule` tree. |
286
+ | `build_typing_rule` | - | Functional entry point for annotation decomposition. |
287
+
288
+ `IsTyping` recursively decomposes an arbitrary type annotation (`list[int]`, `dict[str,
289
+ int] | None`, `Literal[...]`, `Callable[...]`, ...) into a composed `Rule` tree โ€” the
290
+ mechanism that also powers `simplibs-validate`'s `validate_call`/`validate_dataclass`.
291
+
292
+ โžก๏ธ [README_RULE_TYPING](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_TYPING.md) โ€” the public `IsTyping`/`build_typing_rule` entry points
293
+ โžก๏ธ [README_RULE_TYPING_BUILDERS](https://github.com/simplibs/simplibs-rules/blob/main/docs/rules/README_RULE_TYPING_BUILDERS.md) โ€” the internal per-construct decomposition engine
294
+
295
+ ---
296
+
297
+ ## ๐Ÿงช Testing Utilities
298
+
299
+ `simplibs-rules` includes its own contract testing tools to ensure custom or existing `Rule`
300
+ implementations strictly follow all rules and return modes:
301
+
302
+ * **`assert_rule_contract`**: Verifies `is_valid`, direct calling, `validate()` matrix,
303
+ return modes, exception generation, and `raise_invalid()` consistency for any `Rule` instance.
304
+
305
+ โžก๏ธ [README_TESTING_ASSERTS_RULE_CONTRACT](https://github.com/simplibs/simplibs-rules/blob/main/docs/testing/README_TESTING_ASSERTS_RULE_CONTRACT.md)
306
+
307
+ ---
308
+
309
+ ## โš ๏ธ Exceptions
310
+
311
+ Diagnostic exceptions built by `build_exception()`/`raise_invalid()` are structured
312
+ [`simplibs.exception.SimpleException`](https://pypi.org/project/simplibs-exception/) cards
313
+ rather than bare tracebacks. `simplibs-validate` builds its own `ValidateError` hierarchy
314
+ on top of the same mechanism for the higher-level entry points (`validate()`,
315
+ `validate_call`, ...).
316
+
317
+ ---
318
+
319
+ ## ๐Ÿ”— Related libraries
320
+
321
+ * **[`simplibs-validate`](https://pypi.org/project/simplibs-validate/)** โ€” the `validate()`
322
+ entry point, ready-made `validate_*` wrappers, and self-validating decorators
323
+ (`validate_call`, `validate_dataclass`) built on top of `Rule`. `raise_invalid()`
324
+ lives here, in `simplibs-rules`, not there.
325
+ * **`simplibs-types`** *(in progress)* โ€” reusable, named validated types (`Annotated[type,
326
+ Rule]` combinations) built on `Rule`, for sharing a single constraint definition across
327
+ many annotations.
328
+
329
+ ---
330
+
331
+ ## โ˜ฏ๏ธ About simplibs
332
+
333
+ All libraries in the **simplibs** (Simple Libraries) ecosystem share a common
334
+ engineering philosophy:
335
+
336
+ * **Dyslexia-friendly:**
337
+ We actively minimize cognitive load. Code is atomized into small, self-contained units,
338
+ files are named directly after the logical task they perform, and explanations describe
339
+ *why* something is designed, not just *what* it is.
340
+ * **Programmer's Zen:**
341
+ Nothing should be missing, and nothing should be superfluous. We value clean execution
342
+ paths and robust, understandable code architectures over rushed, messy feature sets.
343
+ * **Defensive Style:**
344
+ We actively anticipate edge cases and failure modes so that only safe operational paths
345
+ remain. Our code is built to degrade gracefully rather than crash unexpectedly.
346
+ * **Minimalism:**
347
+ Find the most direct path to the goal in as few operational steps as possible without
348
+ taking shortcuts on safety, readability, or completeness.
349
+ * **Code as Craft:**
350
+ Code should be pleasant to look at, readable at a glance, and evoke structural harmony.
351
+ We treat software engineering as a precision trade.
352
+
353
+ ---
354
+
355
+ ### ๐Ÿค Contributing & Community
356
+
357
+ This is an **open-source project** built with love and care. We strongly believe in
358
+ community collaboration and welcome any feedback, bug reports, or feature ideas!
359
+
360
+ * **Want to contribute?** Feel free to open an Issue or submit a Pull Request.
361
+ * **Want to get in touch?** If you'd like to discuss the project further, collaborate,
362
+ or just say hello, feel free to open a GitHub Issue or start a Discussion.
363
+
364
+ ---
365
+
366
+ ### ๐Ÿ“ License
367
+
368
+ This library is released under the **MIT License**. Build great things!
369
+
370
+ ---
371
+
372
+ [โ–ฒ Back to Top](#-simplibs-rules)