simplibs-rules 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. simplibs/rules/__init__.py +943 -0
  2. simplibs/rules/base_class/Rule.py +322 -0
  3. simplibs/rules/base_class/_NotARule.py +33 -0
  4. simplibs/rules/base_class/__init__.py +17 -0
  5. simplibs/rules/containers/AllOf.py +147 -0
  6. simplibs/rules/containers/AnyOf.py +146 -0
  7. simplibs/rules/containers/Compose.py +146 -0
  8. simplibs/rules/containers/ForEach.py +120 -0
  9. simplibs/rules/containers/NoneOf.py +112 -0
  10. simplibs/rules/containers/Not.py +97 -0
  11. simplibs/rules/containers/__init__.py +28 -0
  12. simplibs/rules/containers/_helpers/__init__.py +22 -0
  13. simplibs/rules/containers/_helpers/as_predicate.py +84 -0
  14. simplibs/rules/containers/_helpers/build_child_exception.py +39 -0
  15. simplibs/rules/containers/_helpers/describe_rule.py +72 -0
  16. simplibs/rules/containers/_helpers/validations/__init__.py +1 -0
  17. simplibs/rules/containers/_helpers/validations/raise_invalid_predicate.py +22 -0
  18. simplibs/rules/containers/_init_validators/__init__.py +23 -0
  19. simplibs/rules/containers/_init_validators/raise_container_param_not_type_error.py +52 -0
  20. simplibs/rules/containers/_init_validators/raise_requires_at_least_one_rule_error.py +37 -0
  21. simplibs/rules/containers/_init_validators/raise_rule_param_not_callable.py +54 -0
  22. simplibs/rules/containers/_init_validators/validate_compose_param_is_callable.py +72 -0
  23. simplibs/rules/predicates/__init__.py +103 -0
  24. simplibs/rules/predicates/_helpers/__init__.py +18 -0
  25. simplibs/rules/predicates/_helpers/accepts_one_positional_argument.py +127 -0
  26. simplibs/rules/predicates/_helpers/format_container.py +50 -0
  27. simplibs/rules/predicates/_init_validators/__init__.py +40 -0
  28. simplibs/rules/predicates/_init_validators/rule_errors/__init__.py +21 -0
  29. simplibs/rules/predicates/_init_validators/rule_errors/raise_has_length_param_conflict_error.py +53 -0
  30. simplibs/rules/predicates/_init_validators/rule_errors/raise_regex_param_invalid_pattern_error.py +43 -0
  31. simplibs/rules/predicates/_init_validators/rule_errors/raise_user_rule_param_wrong_arity.py +53 -0
  32. simplibs/rules/predicates/_init_validators/shared_errors/__init__.py +32 -0
  33. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_bounds_inverted_error.py +78 -0
  34. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_incomparable_error.py +65 -0
  35. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_missing_error.py +77 -0
  36. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_callable_error.py +51 -0
  37. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_container_error.py +75 -0
  38. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_non_negative_integer_error.py +88 -0
  39. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_string_error.py +77 -0
  40. simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_type_error.py +65 -0
  41. simplibs/rules/predicates/_init_validators/shared_validators/__init__.py +24 -0
  42. simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_integer.py +73 -0
  43. simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_not_zero.py +69 -0
  44. simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_primitive_number.py +76 -0
  45. simplibs/rules/predicates/_init_validators/shared_validators/validate_param_remainder_in_range.py +58 -0
  46. simplibs/rules/predicates/arithmetic/CloseTo.py +149 -0
  47. simplibs/rules/predicates/arithmetic/DivisibleBy.py +120 -0
  48. simplibs/rules/predicates/arithmetic/HasRemainder.py +137 -0
  49. simplibs/rules/predicates/arithmetic/__init__.py +21 -0
  50. simplibs/rules/predicates/checkers/IsEmpty.py +101 -0
  51. simplibs/rules/predicates/checkers/IsFalse.py +81 -0
  52. simplibs/rules/predicates/checkers/IsNone.py +81 -0
  53. simplibs/rules/predicates/checkers/IsTrue.py +80 -0
  54. simplibs/rules/predicates/checkers/NotEmpty.py +100 -0
  55. simplibs/rules/predicates/checkers/__init__.py +25 -0
  56. simplibs/rules/predicates/collections/AllUnique.py +124 -0
  57. simplibs/rules/predicates/collections/HasItem.py +131 -0
  58. simplibs/rules/predicates/collections/HasKey.py +104 -0
  59. simplibs/rules/predicates/collections/HasKeys.py +115 -0
  60. simplibs/rules/predicates/collections/IsContainer.py +99 -0
  61. simplibs/rules/predicates/collections/IsSubsetOf.py +139 -0
  62. simplibs/rules/predicates/collections/IsSupersetOf.py +138 -0
  63. simplibs/rules/predicates/collections/__init__.py +29 -0
  64. simplibs/rules/predicates/comparisons/Equals.py +87 -0
  65. simplibs/rules/predicates/comparisons/GreaterOrEqual.py +106 -0
  66. simplibs/rules/predicates/comparisons/GreaterThan.py +106 -0
  67. simplibs/rules/predicates/comparisons/InRange.py +166 -0
  68. simplibs/rules/predicates/comparisons/LessOrEqual.py +106 -0
  69. simplibs/rules/predicates/comparisons/LessThan.py +106 -0
  70. simplibs/rules/predicates/comparisons/NotEquals.py +88 -0
  71. simplibs/rules/predicates/comparisons/__init__.py +29 -0
  72. simplibs/rules/predicates/introspection/HasAttribute.py +95 -0
  73. simplibs/rules/predicates/introspection/HasLength.py +177 -0
  74. simplibs/rules/predicates/introspection/IsCallable.py +81 -0
  75. simplibs/rules/predicates/introspection/IsDataclass.py +84 -0
  76. simplibs/rules/predicates/introspection/IsHashable.py +91 -0
  77. simplibs/rules/predicates/introspection/IsInstance.py +105 -0
  78. simplibs/rules/predicates/introspection/IsIterable.py +90 -0
  79. simplibs/rules/predicates/introspection/IsSubclass.py +122 -0
  80. simplibs/rules/predicates/introspection/IsType.py +82 -0
  81. simplibs/rules/predicates/introspection/__init__.py +34 -0
  82. simplibs/rules/predicates/logic/Is.py +88 -0
  83. simplibs/rules/predicates/logic/IsIn.py +144 -0
  84. simplibs/rules/predicates/logic/IsNot.py +89 -0
  85. simplibs/rules/predicates/logic/NotIn.py +145 -0
  86. simplibs/rules/predicates/logic/UserRule.py +118 -0
  87. simplibs/rules/predicates/logic/__init__.py +24 -0
  88. simplibs/rules/predicates/numeric/IsBool.py +96 -0
  89. simplibs/rules/predicates/numeric/IsDecimal.py +83 -0
  90. simplibs/rules/predicates/numeric/IsEven.py +107 -0
  91. simplibs/rules/predicates/numeric/IsFinite.py +104 -0
  92. simplibs/rules/predicates/numeric/IsFloat.py +75 -0
  93. simplibs/rules/predicates/numeric/IsInfinity.py +97 -0
  94. simplibs/rules/predicates/numeric/IsInteger.py +118 -0
  95. simplibs/rules/predicates/numeric/IsNan.py +98 -0
  96. simplibs/rules/predicates/numeric/IsNumber.py +96 -0
  97. simplibs/rules/predicates/numeric/IsOdd.py +94 -0
  98. simplibs/rules/predicates/numeric/IsPi.py +138 -0
  99. simplibs/rules/predicates/numeric/IsPrimitiveNumber.py +87 -0
  100. simplibs/rules/predicates/numeric/IsZero.py +109 -0
  101. simplibs/rules/predicates/numeric/__init__.py +42 -0
  102. simplibs/rules/predicates/strings/Contains.py +114 -0
  103. simplibs/rules/predicates/strings/EndsWith.py +114 -0
  104. simplibs/rules/predicates/strings/IsAlnum.py +107 -0
  105. simplibs/rules/predicates/strings/IsAlpha.py +111 -0
  106. simplibs/rules/predicates/strings/IsAscii.py +109 -0
  107. simplibs/rules/predicates/strings/IsBlank.py +98 -0
  108. simplibs/rules/predicates/strings/IsDigitString.py +115 -0
  109. simplibs/rules/predicates/strings/IsLowercase.py +111 -0
  110. simplibs/rules/predicates/strings/IsString.py +104 -0
  111. simplibs/rules/predicates/strings/IsSubstringOf.py +114 -0
  112. simplibs/rules/predicates/strings/IsTitlecase.py +130 -0
  113. simplibs/rules/predicates/strings/IsUppercase.py +96 -0
  114. simplibs/rules/predicates/strings/NotBlank.py +98 -0
  115. simplibs/rules/predicates/strings/Regex.py +126 -0
  116. simplibs/rules/predicates/strings/StartsWith.py +114 -0
  117. simplibs/rules/predicates/strings/__init__.py +44 -0
  118. simplibs/rules/predicates/typing/IsAny.py +114 -0
  119. simplibs/rules/predicates/typing/IsTyping.py +100 -0
  120. simplibs/rules/predicates/typing/__init__.py +26 -0
  121. simplibs/rules/predicates/typing/_builders/ORIGIN_TABLE.py +112 -0
  122. simplibs/rules/predicates/typing/_builders/__init__.py +35 -0
  123. simplibs/rules/predicates/typing/_builders/build_annotated_rule.py +106 -0
  124. simplibs/rules/predicates/typing/_builders/build_any_of_rule.py +73 -0
  125. simplibs/rules/predicates/typing/_builders/build_callable_rule.py +63 -0
  126. simplibs/rules/predicates/typing/_builders/build_elements_rule.py +109 -0
  127. simplibs/rules/predicates/typing/_builders/build_key_value_rule.py +65 -0
  128. simplibs/rules/predicates/typing/_builders/build_literal_rule.py +60 -0
  129. simplibs/rules/predicates/typing/_builders/build_tuple_rule.py +111 -0
  130. simplibs/rules/predicates/typing/_builders/build_type_rule.py +114 -0
  131. simplibs/rules/predicates/typing/_validations/__init__.py +16 -0
  132. simplibs/rules/predicates/typing/_validations/raise_unsupported_annotation_error.py +63 -0
  133. simplibs/rules/predicates/typing/build_typing_rule.py +131 -0
  134. simplibs/rules/predicates/typing/tools/__init__.py +20 -0
  135. simplibs/rules/predicates/typing/tools/get_supported_origins.py +42 -0
  136. simplibs/rules/predicates/typing/tools/is_supported_annotation.py +60 -0
  137. simplibs/rules/testing/__init__.py +40 -0
  138. simplibs/rules/testing/assert_rule_contract.py +198 -0
  139. simplibs/rules/testing/asserts/__init__.py +27 -0
  140. simplibs/rules/testing/asserts/assert_rule_build_exception.py +149 -0
  141. simplibs/rules/testing/asserts/assert_rule_is_valid.py +90 -0
  142. simplibs/rules/testing/asserts/assert_rule_param_error.py +77 -0
  143. simplibs/rules/testing/asserts/assert_rule_raise_invalid.py +91 -0
  144. simplibs/rules/testing/asserts/assert_rule_validate.py +107 -0
  145. simplibs/rules/tools/__init__.py +16 -0
  146. simplibs/rules/tools/raise_invalid.py +84 -0
  147. simplibs_rules-0.1.0.dist-info/METADATA +372 -0
  148. simplibs_rules-0.1.0.dist-info/RECORD +151 -0
  149. simplibs_rules-0.1.0.dist-info/WHEEL +5 -0
  150. simplibs_rules-0.1.0.dist-info/licenses/LICENSE +21 -0
  151. simplibs_rules-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,943 @@
1
+ from types import SimpleNamespace
2
+
3
+ # Base class
4
+ from .base_class import Rule
5
+
6
+ # Containers
7
+ from .containers import (
8
+ AllOf,
9
+ AnyOf,
10
+ Compose,
11
+ ForEach,
12
+ NoneOf,
13
+ Not,
14
+ )
15
+
16
+ # Predicates — arithmetic
17
+ from .predicates.arithmetic import (
18
+ CloseTo,
19
+ DivisibleBy,
20
+ HasRemainder,
21
+ )
22
+
23
+ # Predicates — checkers
24
+ from .predicates.checkers import (
25
+ IsEmpty,
26
+ IsFalse,
27
+ IsNone,
28
+ IsTrue,
29
+ NotEmpty,
30
+ )
31
+
32
+ # Predicates — collections
33
+ from .predicates.collections import (
34
+ AllUnique,
35
+ HasItem,
36
+ HasKey,
37
+ HasKeys,
38
+ IsContainer,
39
+ IsSubsetOf,
40
+ IsSupersetOf,
41
+ )
42
+
43
+ # Predicates — comparisons
44
+ from .predicates.comparisons import (
45
+ Equals,
46
+ GreaterOrEqual,
47
+ GreaterThan,
48
+ InRange,
49
+ LessOrEqual,
50
+ LessThan,
51
+ NotEquals,
52
+ )
53
+
54
+ # Predicates — introspection
55
+ from .predicates.introspection import (
56
+ HasAttribute,
57
+ HasLength,
58
+ IsCallable,
59
+ IsDataclass,
60
+ IsHashable,
61
+ IsInstance,
62
+ IsIterable,
63
+ IsSubclass,
64
+ IsType,
65
+ )
66
+
67
+ # Predicates — logic
68
+ from .predicates.logic import (
69
+ Is,
70
+ IsIn,
71
+ IsNot,
72
+ NotIn,
73
+ UserRule,
74
+ )
75
+
76
+ # Predicates — numeric
77
+ from .predicates.numeric import (
78
+ IsBool,
79
+ IsDecimal,
80
+ IsFloat,
81
+ IsInfinity,
82
+ IsInteger,
83
+ IsNan,
84
+ IsNumber,
85
+ IsPi,
86
+ IsPrimitiveNumber,
87
+ IsZero,
88
+ IsEven,
89
+ IsOdd,
90
+ IsFinite
91
+ )
92
+
93
+ # Predicates — strings
94
+ from .predicates.strings import (
95
+ Contains,
96
+ EndsWith,
97
+ IsBlank,
98
+ IsString,
99
+ NotBlank,
100
+ Regex,
101
+ StartsWith,
102
+ IsSubstringOf,
103
+ IsAlpha,
104
+ IsAlnum,
105
+ IsDigitString,
106
+ IsAscii,
107
+ IsLowercase,
108
+ IsUppercase,
109
+ IsTitlecase
110
+ )
111
+
112
+ # Predicates — typing
113
+ from .predicates.typing import (
114
+ IsAny,
115
+ IsTyping,
116
+ build_typing_rule,
117
+ get_supported_origins,
118
+ is_supported_annotation
119
+ )
120
+
121
+ # Tools
122
+ from .tools import raise_invalid
123
+
124
+
125
+ # ============================================================================
126
+ # Rule shortcuts
127
+ # ============================================================================
128
+
129
+ # Parameterized rules are exposed as classes.
130
+ # Zero-parameter rules are exposed as pre-instantiated objects.
131
+ #
132
+ # This allows:
133
+ #
134
+ # validate(value, is_integer & greater_than(0))
135
+ #
136
+ # instead of:
137
+ #
138
+ # validate(value, IsInteger() & GreaterThan(0))
139
+
140
+
141
+ # ---- containers ------------------------------------------------------------
142
+
143
+ all_of = AllOf # *rules
144
+ any_of = AnyOf # *rules
145
+ compose = Compose # transformer, validator
146
+ for_each = ForEach # rule
147
+ none_of = NoneOf # *rules
148
+ negate = Not # rule
149
+
150
+
151
+ # ---- predicates/arithmetic -------------------------------------------------
152
+
153
+ close_to = CloseTo # target, *, rel_tol=1e-9, abs_tol=0.0
154
+ divisible_by = DivisibleBy # divisor
155
+ has_remainder = HasRemainder # divisor, remainder
156
+
157
+
158
+ # ---- predicates/checkers ---------------------------------------------------
159
+
160
+ is_empty = IsEmpty()
161
+ is_false = IsFalse()
162
+ is_none = IsNone()
163
+ is_true = IsTrue()
164
+ not_empty = NotEmpty()
165
+
166
+
167
+ # ---- predicates/collections ------------------------------------------------
168
+
169
+ all_unique = AllUnique()
170
+ has_item = HasItem # item
171
+ has_key = HasKey # key
172
+ has_keys = HasKeys # *keys
173
+ is_container = IsContainer()
174
+ is_subset_of = IsSubsetOf # reference
175
+ is_superset_of = IsSupersetOf # reference
176
+
177
+
178
+ # ---- predicates/comparisons ------------------------------------------------
179
+
180
+ equals = eq = Equals # expected_value
181
+ greater_or_equal = ge = GreaterOrEqual # threshold
182
+ greater_than = gt = GreaterThan # threshold
183
+ in_range = InRange # min_val, max_val, include_min=True, include_max=True
184
+ less_or_equal = le = LessOrEqual # threshold
185
+ less_than = lt = LessThan # threshold
186
+ not_equals = ne = NotEquals # forbidden
187
+
188
+
189
+ # ---- predicates/introspection ----------------------------------------------
190
+
191
+ has_attribute = has_attr = HasAttribute # attr_name
192
+ has_length = HasLength # length=None, *, min_length=None, min_length=None, max_length=None
193
+ is_callable = IsCallable()
194
+ is_dataclass = IsDataclass()
195
+ is_hashable = IsHashable()
196
+ is_instance = IsInstance # *types
197
+ is_iterable = IsIterable()
198
+ is_subclass = IsSubclass # *types
199
+ is_type = IsType()
200
+
201
+
202
+ # ---- predicates/logic ------------------------------------------------------
203
+
204
+ is_same = same_as = Is # expected
205
+ is_in = IsIn # options
206
+ is_not = IsNot # forbidden
207
+ not_in = NotIn # options
208
+ user_rule = UserRule # rule
209
+
210
+ # ---- predicates/numeric ----------------------------------------------------
211
+
212
+ is_bool = IsBool()
213
+ is_decimal = IsDecimal()
214
+ is_float = IsFloat()
215
+ is_infinity = IsInfinity()
216
+ is_integer = is_int = IsInteger()
217
+ is_nan = IsNan()
218
+ is_number = IsNumber()
219
+ is_pi = IsPi # decimal_places
220
+ is_primitive_number = IsPrimitiveNumber()
221
+ is_zero = IsZero()
222
+ is_even = IsEven()
223
+ is_odd = IsOdd()
224
+ is_finite = IsFinite()
225
+
226
+
227
+ # ---- predicates/strings ----------------------------------------------------
228
+
229
+ contains = Contains # substring
230
+ ends_with = EndsWith # suffix
231
+ is_blank = IsBlank()
232
+ is_string = is_str = IsString()
233
+ not_blank = NotBlank()
234
+ regex = Regex # pattern
235
+ starts_with = StartsWith # prefix
236
+ is_substring_of = IsSubstringOf # target_string
237
+ is_alpha = IsAlpha()
238
+ is_alnum = IsAlnum()
239
+ is_digit_string = IsDigitString()
240
+ is_ascii = IsAscii()
241
+ is_lowercase = IsLowercase()
242
+ is_uppercase = IsUppercase()
243
+ is_titlecase = IsTitlecase()
244
+
245
+ # ---- predicates/typing -------------------------------------------------------
246
+
247
+ is_any = always_true = IsAny()
248
+ always_false = ~IsAny()
249
+ is_typing = IsTyping
250
+
251
+
252
+ # ============================================================================
253
+ # Grouped namespaces
254
+ # ============================================================================
255
+
256
+ # All concrete Rule classes.
257
+ #
258
+ # Useful when the class itself is required, for example for subclassing,
259
+ # isinstance checks, introspection, or programmatic rule construction.
260
+
261
+ rule_class = SimpleNamespace(
262
+ # containers
263
+ AllOf=AllOf,
264
+ AnyOf=AnyOf,
265
+ Compose=Compose,
266
+ ForEach=ForEach,
267
+ NoneOf=NoneOf,
268
+ Not=Not,
269
+
270
+ # arithmetic
271
+ CloseTo=CloseTo,
272
+ DivisibleBy=DivisibleBy,
273
+ HasRemainder=HasRemainder,
274
+
275
+ # checkers
276
+ IsEmpty=IsEmpty,
277
+ IsFalse=IsFalse,
278
+ IsNone=IsNone,
279
+ IsTrue=IsTrue,
280
+ NotEmpty=NotEmpty,
281
+
282
+ # collections
283
+ AllUnique=AllUnique,
284
+ HasItem=HasItem,
285
+ HasKey=HasKey,
286
+ HasKeys=HasKeys,
287
+ IsContainer=IsContainer,
288
+ IsSubsetOf=IsSubsetOf,
289
+ IsSupersetOf=IsSupersetOf,
290
+
291
+ # comparisons
292
+ Equals=Equals,
293
+ GreaterOrEqual=GreaterOrEqual,
294
+ GreaterThan=GreaterThan,
295
+ InRange=InRange,
296
+ LessOrEqual=LessOrEqual,
297
+ LessThan=LessThan,
298
+ NotEquals=NotEquals,
299
+
300
+ # introspection
301
+ HasAttribute=HasAttribute,
302
+ HasLength=HasLength,
303
+ IsCallable=IsCallable,
304
+ IsDataclass=IsDataclass,
305
+ IsHashable=IsHashable,
306
+ IsInstance=IsInstance,
307
+ IsIterable=IsIterable,
308
+ IsSubclass=IsSubclass,
309
+ IsType=IsType,
310
+
311
+ # logic
312
+ Is=Is,
313
+ IsIn=IsIn,
314
+ IsNot=IsNot,
315
+ NotIn=NotIn,
316
+ UserRule=UserRule,
317
+
318
+ # numeric
319
+ IsBool=IsBool,
320
+ IsDecimal=IsDecimal,
321
+ IsFloat=IsFloat,
322
+ IsInfinity=IsInfinity,
323
+ IsInteger=IsInteger,
324
+ IsNan=IsNan,
325
+ IsNumber=IsNumber,
326
+ IsPi=IsPi,
327
+ IsPrimitiveNumber=IsPrimitiveNumber,
328
+ IsZero=IsZero,
329
+ IsEven=IsEven,
330
+ IsOdd=IsOdd,
331
+ IsFinite=IsFinite,
332
+
333
+ # strings
334
+ Contains=Contains,
335
+ EndsWith=EndsWith,
336
+ IsBlank=IsBlank,
337
+ IsString=IsString,
338
+ NotBlank=NotBlank,
339
+ Regex=Regex,
340
+ StartsWith=StartsWith,
341
+ IsSubstringOf=IsSubstringOf,
342
+ IsAlpha=IsAlpha,
343
+ IsAlnum=IsAlnum,
344
+ IsDigitString=IsDigitString,
345
+ IsAscii=IsAscii,
346
+ IsLowercase=IsLowercase,
347
+ IsUppercase=IsUppercase,
348
+ IsTitlecase=IsTitlecase,
349
+
350
+ # typing
351
+ IsAny=IsAny,
352
+ IsTyping=IsTyping,
353
+ )
354
+
355
+
356
+ # All public snake_case rule shortcuts.
357
+ #
358
+ # Every attribute points to the same object as its corresponding module-level
359
+ # shortcut. Zero-parameter rules are shared instances; parameterized rules
360
+ # refer to their classes.
361
+
362
+ rules = SimpleNamespace(
363
+ # containers
364
+ all_of=all_of,
365
+ any_of=any_of,
366
+ compose=compose,
367
+ for_each=for_each,
368
+ none_of=none_of,
369
+ negate=negate,
370
+
371
+ # arithmetic
372
+ close_to=close_to,
373
+ divisible_by=divisible_by,
374
+ has_remainder=has_remainder,
375
+
376
+ # checkers
377
+ is_empty=is_empty,
378
+ is_false=is_false,
379
+ is_none=is_none,
380
+ is_true=is_true,
381
+ not_empty=not_empty,
382
+
383
+ # collections
384
+ all_unique=all_unique,
385
+ has_item=has_item,
386
+ has_key=has_key,
387
+ has_keys=has_keys,
388
+ is_container=is_container,
389
+ is_subset_of=is_subset_of,
390
+ is_superset_of=is_superset_of,
391
+
392
+ # comparisons
393
+ equals=equals,
394
+ eq=eq,
395
+ greater_or_equal=greater_or_equal,
396
+ ge=ge,
397
+ greater_than=greater_than,
398
+ gt=gt,
399
+ in_range=in_range,
400
+ less_or_equal=less_or_equal,
401
+ le=le,
402
+ less_than=less_than,
403
+ lt=lt,
404
+ not_equals=not_equals,
405
+ ne=ne,
406
+
407
+ # introspection
408
+ has_attribute=has_attribute,
409
+ has_attr=has_attr,
410
+ has_length=has_length,
411
+ is_callable=is_callable,
412
+ is_dataclass=is_dataclass,
413
+ is_hashable=is_hashable,
414
+ is_instance=is_instance,
415
+ is_iterable=is_iterable,
416
+ is_subclass=is_subclass,
417
+ is_type=is_type,
418
+
419
+ # logic
420
+ same_as=same_as,
421
+ is_same=is_same,
422
+ is_in=is_in,
423
+ is_not=is_not,
424
+ not_in=not_in,
425
+ user_rule=user_rule,
426
+
427
+
428
+ # numeric
429
+ is_bool=is_bool,
430
+ is_decimal=is_decimal,
431
+ is_float=is_float,
432
+ is_infinity=is_infinity,
433
+ is_integer=is_integer,
434
+ is_int=is_int,
435
+ is_nan=is_nan,
436
+ is_number=is_number,
437
+ is_pi=is_pi,
438
+ is_primitive_number=is_primitive_number,
439
+ is_zero=is_zero,
440
+ is_even=is_even,
441
+ is_odd=is_odd,
442
+ is_finite=is_finite,
443
+
444
+ # strings
445
+ contains=contains,
446
+ ends_with=ends_with,
447
+ is_blank=is_blank,
448
+ is_string=is_string,
449
+ is_str=is_str,
450
+ not_blank=not_blank,
451
+ regex=regex,
452
+ starts_with=starts_with,
453
+ is_substring_of=is_substring_of,
454
+ is_alpha=is_alpha,
455
+ is_alnum=is_alnum,
456
+ is_digit_string=is_digit_string,
457
+ is_ascii=is_ascii,
458
+ is_lowercase=is_lowercase,
459
+ is_uppercase=is_uppercase,
460
+ is_titlecase=is_titlecase,
461
+
462
+ # typing
463
+ always_false=always_false,
464
+ always_true=always_true,
465
+ is_any=is_any,
466
+ is_typing=is_typing,
467
+ )
468
+
469
+ # ============================================================================
470
+ # Public exports
471
+ # ============================================================================
472
+
473
+ __all__ = [
474
+ "Rule",
475
+ "rule_class",
476
+ "rules",
477
+
478
+ # containers
479
+ "AllOf",
480
+ "AnyOf",
481
+ "Compose",
482
+ "ForEach",
483
+ "NoneOf",
484
+ "Not",
485
+
486
+ # arithmetic
487
+ "CloseTo",
488
+ "DivisibleBy",
489
+ "HasRemainder",
490
+
491
+ # checkers
492
+ "IsEmpty",
493
+ "IsFalse",
494
+ "IsNone",
495
+ "IsTrue",
496
+ "NotEmpty",
497
+
498
+ # collections
499
+ "AllUnique",
500
+ "HasItem",
501
+ "HasKey",
502
+ "HasKeys",
503
+ "IsContainer",
504
+ "IsSubsetOf",
505
+ "IsSupersetOf",
506
+
507
+ # comparisons
508
+ "Equals",
509
+ "GreaterOrEqual",
510
+ "GreaterThan",
511
+ "InRange",
512
+ "LessOrEqual",
513
+ "LessThan",
514
+ "NotEquals",
515
+
516
+ # introspection
517
+ "HasAttribute",
518
+ "HasLength",
519
+ "IsCallable",
520
+ "IsDataclass",
521
+ "IsHashable",
522
+ "IsInstance",
523
+ "IsIterable",
524
+ "IsSubclass",
525
+ "IsType",
526
+
527
+ # logic
528
+ "Is",
529
+ "IsIn",
530
+ "IsNot",
531
+ "NotIn",
532
+ "UserRule",
533
+
534
+ # numeric
535
+ "IsBool",
536
+ "IsDecimal",
537
+ "IsFloat",
538
+ "IsInfinity",
539
+ "IsInteger",
540
+ "IsNan",
541
+ "IsNumber",
542
+ "IsPi",
543
+ "IsPrimitiveNumber",
544
+ "IsZero",
545
+ "IsEven",
546
+ "IsOdd",
547
+ "IsFinite",
548
+
549
+ # strings
550
+ "Contains",
551
+ "EndsWith",
552
+ "IsBlank",
553
+ "IsString",
554
+ "NotBlank",
555
+ "Regex",
556
+ "StartsWith",
557
+ "IsSubstringOf",
558
+ "IsAlpha",
559
+ "IsAlnum",
560
+ "IsDigitString",
561
+ "IsAscii",
562
+ "IsLowercase",
563
+ "IsUppercase",
564
+ "IsTitlecase",
565
+
566
+ # typing
567
+ "IsAny",
568
+ "IsTyping",
569
+ "build_typing_rule",
570
+ "get_supported_origins",
571
+ "is_supported_annotation",
572
+
573
+ # tools
574
+ "raise_invalid",
575
+
576
+ # shortcuts
577
+ "all_of",
578
+ "any_of",
579
+ "compose",
580
+ "for_each",
581
+ "none_of",
582
+ "negate",
583
+ "close_to",
584
+ "divisible_by",
585
+ "has_remainder",
586
+ "is_empty",
587
+ "is_false",
588
+ "is_none",
589
+ "is_true",
590
+ "not_empty",
591
+ "all_unique",
592
+ "has_item",
593
+ "has_key",
594
+ "has_keys",
595
+ "is_container",
596
+ "is_subset_of",
597
+ "is_superset_of",
598
+ "equals",
599
+ "eq",
600
+ "greater_or_equal",
601
+ "ge",
602
+ "greater_than",
603
+ "gt",
604
+ "in_range",
605
+ "less_or_equal",
606
+ "le",
607
+ "less_than",
608
+ "lt",
609
+ "not_equals",
610
+ "ne",
611
+ "has_attribute",
612
+ "has_attr",
613
+ "has_length",
614
+ "is_callable",
615
+ "is_dataclass",
616
+ "is_hashable",
617
+ "is_instance",
618
+ "is_iterable",
619
+ "is_subclass",
620
+ "is_type",
621
+ "same_as",
622
+ "is_same",
623
+ "is_in",
624
+ "is_not",
625
+ "not_in",
626
+ "user_rule",
627
+ "is_bool",
628
+ "is_decimal",
629
+ "is_float",
630
+ "is_infinity",
631
+ "is_integer",
632
+ "is_int",
633
+ "is_nan",
634
+ "is_number",
635
+ "is_pi",
636
+ "is_primitive_number",
637
+ "is_zero",
638
+ "is_even",
639
+ "is_odd",
640
+ "is_finite",
641
+ "contains",
642
+ "ends_with",
643
+ "is_blank",
644
+ "is_string",
645
+ "is_str",
646
+ "not_blank",
647
+ "regex",
648
+ "starts_with",
649
+ "is_substring_of",
650
+ "is_alpha",
651
+ "is_alnum",
652
+ "is_digit_string",
653
+ "is_ascii",
654
+ "is_lowercase",
655
+ "is_uppercase",
656
+ "is_titlecase",
657
+ "is_typing",
658
+ "always_false",
659
+ "always_true",
660
+ "is_any",
661
+ "is_typing",
662
+ ]
663
+
664
+
665
+ # ============================================================================
666
+ # Design notes
667
+ # ============================================================================
668
+
669
+ _DESIGN_NOTES = """
670
+ # rules — Central Rule Namespace
671
+
672
+ This module is the main public entry point for the validation rules provided
673
+ by `simplibs-validate`.
674
+
675
+ It exposes three complementary interfaces:
676
+
677
+ 1. Concrete rule classes
678
+ 2. Readable snake_case shortcuts
679
+ 3. Grouped namespaces for programmatic access
680
+
681
+
682
+ ## 1. Rule shortcuts
683
+
684
+ Parameterized rules are exposed as their classes:
685
+
686
+ greater_than = GreaterThan
687
+ regex = Regex
688
+ is_instance = IsInstance
689
+
690
+ The caller supplies the required configuration:
691
+
692
+ validate(value, greater_than(0))
693
+ validate(value, regex(r"^[a-z]+$"))
694
+ validate(value, is_instance(int))
695
+
696
+ Zero-parameter rules are exposed as pre-instantiated objects:
697
+
698
+ is_integer = IsInteger()
699
+ is_string = IsString()
700
+ is_none = IsNone()
701
+
702
+ They can therefore be used directly:
703
+
704
+ validate(value, is_integer)
705
+ validate(value, is_string & not_empty)
706
+ validate(value, is_none | is_string)
707
+
708
+
709
+ ## 2. Composition
710
+
711
+ Because Rule implements the `&`, `|`, and `~` operators, shortcuts can be
712
+ combined directly into declarative validation expressions:
713
+
714
+ is_integer & greater_or_equal(0) & less_than(100)
715
+
716
+ is_string & not_empty & starts_with("user_")
717
+
718
+ is_none | is_instance(dict)
719
+
720
+ ~(is_string & is_blank)
721
+
722
+ The operators correspond to:
723
+
724
+ & -> logical AND
725
+ | -> logical OR
726
+ ~ -> logical NOT
727
+
728
+
729
+ ## 3. Grouped namespaces
730
+
731
+ ### `rule_class`
732
+
733
+ Contains every concrete Rule subclass under its original class name:
734
+
735
+ rule_class.IsInteger
736
+ rule_class.GreaterThan
737
+ rule_class.Regex
738
+
739
+ This namespace is intended for programmatic access when the actual class is
740
+ required, such as subclass checks, introspection, or dynamic construction.
741
+
742
+
743
+ ### `rules`
744
+
745
+ Contains every public snake_case shortcut:
746
+
747
+ rules.is_integer
748
+ rules.greater_than
749
+ rules.regex
750
+
751
+ It is functionally equivalent to importing the shortcuts directly:
752
+
753
+ from simplibs.rules import is_integer
754
+
755
+ # or
756
+
757
+ from simplibs.rules import rules
758
+ rules.is_integer
759
+
760
+ Both references point to the same underlying object for zero-parameter
761
+ rules, or to the same underlying class for parameterized rules.
762
+
763
+
764
+ ## 4. Naming policy
765
+
766
+ Rule shortcuts use descriptive snake_case names derived from the semantics
767
+ of the rule.
768
+
769
+ Names are intentionally not abbreviated. The goal is to keep composed
770
+ validation expressions readable and self-describing:
771
+
772
+ is_string & not_empty & has_length(min_length=3)
773
+
774
+ is preferred over an abbreviated form such as:
775
+
776
+ is_str & nonempty & length(...)
777
+
778
+ The public API therefore favors clarity and discoverability over minimizing
779
+ individual identifier length.
780
+
781
+
782
+ ## 5. Keyword-related names
783
+
784
+ Python keywords cannot be used as ordinary identifiers. Where necessary,
785
+ the public name uses a descriptive alternative:
786
+
787
+ Is -> same_as
788
+ Not -> negate
789
+
790
+ The `is_in` and `is_not` names remain valid Python identifiers because they
791
+ are compound names rather than the keywords themselves.
792
+
793
+
794
+ ## 6. Rule reference tables
795
+
796
+ ### `containers/`
797
+
798
+ | Shortcut | Parameters | Logic |
799
+ |------------|--------------------------|------------------------------------|
800
+ | `all_of` | `*rules` | All rules must pass. |
801
+ | `any_of` | `*rules` | At least one rule must pass. |
802
+ | `compose` | `transformer, validator` | Validate the transformed value. |
803
+ | `for_each` | `rule` | The rule must pass for every item. |
804
+ | `none_of` | `*rules` | No rule may pass. |
805
+ | `negate` | `rule` | The rule must fail. |
806
+
807
+
808
+ ### `predicates/arithmetic/`
809
+
810
+ | Shortcut | Parameters | Logic |
811
+ |-----------------|----------------------------------------|-----------------------------------------|
812
+ | `close_to` | `target, *, rel_tol=1e-9, abs_tol=0.0` | Value is approximately equal to target. |
813
+ | `divisible_by` | `divisor` | `value % divisor == 0` |
814
+ | `has_remainder` | `divisor, remainder` | `value % divisor == remainder` |
815
+
816
+
817
+ ### `predicates/checkers/`
818
+
819
+ | Shortcut | Parameters | Logic |
820
+ |-------------|------------|-------------------|
821
+ | `is_empty` | — | `len(value) == 0` |
822
+ | `is_false` | — | `value is False` |
823
+ | `is_none` | — | `value is None` |
824
+ | `is_true` | — | `value is True` |
825
+ | `not_empty` | — | `len(value) > 0` |
826
+
827
+
828
+ ### `predicates/collections/`
829
+
830
+ | Shortcut | Parameters | Logic |
831
+ |------------------|-------------|----------------------------------------------|
832
+ | `all_unique` | — | All values are unique. |
833
+ | `has_item` | `item` | Container value must contain the given item. |
834
+ | `has_key` | `key` | The key exists in the value. |
835
+ | `has_keys` | `*keys` | All specified keys exist. |
836
+ | `is_container` | — | Value is a supported container. |
837
+ | `is_subset_of` | `reference` | Value is a subset of the reference. |
838
+ | `is_superset_of` | `reference` | Value is a superset of the reference. |
839
+
840
+
841
+ ### `predicates/comparisons/`
842
+
843
+ | Shortcut | Parameters | Logic |
844
+ |--------------------|--------------------------------------------------------|-----------------------------------------|
845
+ | `equals` | `expected_value` | `value == expected_value` |
846
+ | `eq` | `expected_value` | `value == expected_value` |
847
+ | `greater_or_equal` | `threshold` | `value >= threshold` |
848
+ | `ge` | `threshold` | `value >= threshold` |
849
+ | `greater_than` | `threshold` | `value > threshold` |
850
+ | `gt` | `threshold` | `value > threshold` |
851
+ | `in_range` | `min_val, max_val, include_min=True, include_max=True` | Value lies within the configured range. |
852
+ | `less_or_equal` | `threshold` | `value <= threshold` |
853
+ | `le` | `threshold` | `value <= threshold` |
854
+ | `less_than` | `threshold` | `value < threshold` |
855
+ | `lt` | `threshold` | `value < threshold` |
856
+ | `not_equals` | `forbidden` | `value != forbidden` |
857
+ | `ne` | `forbidden` | `value != forbidden` |
858
+
859
+ ### `predicates/introspection/`
860
+
861
+ | Shortcut | Parameters | Logic |
862
+ |-----------------|----------------------------------------------------|---------------------------------------------|
863
+ | `has_attribute` | `attr_name` | Attribute exists on the value. |
864
+ | `has_attr` | `attr_name` | Attribute exists on the value. |
865
+ | `has_length` | `length=None, *, min_length=None, max_length=None` | Value has the specified length or range. |
866
+ | `is_callable` | — | Value is callable. |
867
+ | `is_dataclass` | — | Value is a dataclass instance or class. |
868
+ | `is_hashable` | — | Value is hashable. |
869
+ | `is_instance` | `*types` | `isinstance(value, types)` |
870
+ | `is_iterable` | — | Value is iterable. |
871
+ | `is_subclass` | `*types` | Value is a subclass of the specified types. |
872
+ | `is_type` | — | Value is a type object. |
873
+
874
+
875
+ ### `predicates/logic/`
876
+
877
+ | Shortcut | Parameters | Logic |
878
+ |-------------|-------------|----------------------------------------------|
879
+ | `same_as` | `expected` | `value is expected` |
880
+ | `is_same` | `expected` | `value is expected` |
881
+ | `is_in` | `options` | `value in options` |
882
+ | `is_not` | `forbidden` | `value is not forbidden` |
883
+ | `not_in` | `options` | `value not in options` |
884
+ | `user_rule` | `rule` | `value satisfies arbitrary user predicate` |
885
+
886
+
887
+ ### `predicates/numeric/`
888
+
889
+ | Shortcut | Parameters | Logic |
890
+ |-----------------------|------------------|----------------------------------------------------------------------|
891
+ | `is_bool` | — | Value is a `bool`. |
892
+ | `is_decimal` | — | Value is a `Decimal`. |
893
+ | `is_even` | — | Value is an even integer (booleans excluded). |
894
+ | `is_finite` | — | Value is a primitive number (int/float) that is neither NaN nor inf. |
895
+ | `is_float` | — | Value is a `float`. |
896
+ | `is_infinity` | — | Value is infinite. |
897
+ | `is_integer` | — | Value is an integer but not a boolean. |
898
+ | `is_int` | — | Value is an integer but not a boolean. |
899
+ | `is_nan` | — | Value is NaN. |
900
+ | `is_number` | — | Value is a supported numeric type other than `bool`. |
901
+ | `is_odd` | — | Value is an odd integer (booleans excluded). |
902
+ | `is_pi` | `decimal_places` | Value equals π to the specified precision. |
903
+ | `is_primitive_number` | — | Value is a primitive integer or float, excluding `bool`. |
904
+ | `is_zero` | — | `value == 0` |
905
+
906
+
907
+ ### `predicates/strings/`
908
+
909
+ | Shortcut | Parameters | Logic |
910
+ |-------------------|-----------------|------------------------------------------------------|
911
+ | `contains` | `substring` | Substring occurs in the value. |
912
+ | `ends_with` | `suffix` | Value ends with the suffix. |
913
+ | `is_alnum` | — | String consists entirely of alphanumeric characters. |
914
+ | `is_alpha` | — | String consists entirely of alphabetic characters. |
915
+ | `is_ascii` | — | String contains only ASCII characters. |
916
+ | `is_blank` | — | String contains only whitespace or is empty. |
917
+ | `is_digit_string` | — | String consists entirely of digit characters. |
918
+ | `is_lowercase` | — | String is entirely lowercase. |
919
+ | `is_string` | — | Value is a `str`. |
920
+ | `is_str` | — | Value is a `str`. |
921
+ | `is_titlecase` | — | String is title-cased. |
922
+ | `is_uppercase` | — | String is entirely uppercase. |
923
+ | `not_blank` | — | String contains non-whitespace characters. |
924
+ | `regex` | `pattern` | Regex search finds a match in the string. |
925
+ | `starts_with` | `prefix` | Value starts with the prefix. |
926
+ | `is_substring_of` | `target_string` | String value must be a substring of a target string. |
927
+
928
+
929
+ ### `typing/`
930
+
931
+ | Shortcut | Parameters | Logic |
932
+ |----------------|--------------|-------------------------------------------------|
933
+ | `always_false` | — | Always fails validation (default-deny). |
934
+ | `always_true` | — | Always passes validation. |
935
+ | `is_any` | — | Alias for `always_true` (accepts any value). |
936
+ | `is_typing` | `annotation` | Value must satisfy the given typing annotation. |
937
+
938
+ ## 6. Tools (`tools/`)
939
+ Provides execution utilities for direct exception management and control flow optimization:
940
+ - `raise_invalid`: Directly builds and triggers a structured `ValidationError` for
941
+ a failed `Rule` or plain callable predicate. Used in "happy path" control flow guards
942
+ where a condition failure has already been determined inline, avoiding redundant rule re-evaluation.
943
+ """