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.
- simplibs_rules-0.1.0/LICENSE +21 -0
- simplibs_rules-0.1.0/PKG-INFO +372 -0
- simplibs_rules-0.1.0/README.md +344 -0
- simplibs_rules-0.1.0/pyproject.toml +60 -0
- simplibs_rules-0.1.0/setup.cfg +4 -0
- simplibs_rules-0.1.0/src/simplibs/rules/__init__.py +943 -0
- simplibs_rules-0.1.0/src/simplibs/rules/base_class/Rule.py +322 -0
- simplibs_rules-0.1.0/src/simplibs/rules/base_class/_NotARule.py +33 -0
- simplibs_rules-0.1.0/src/simplibs/rules/base_class/__init__.py +17 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/AllOf.py +147 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/AnyOf.py +146 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/Compose.py +146 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/ForEach.py +120 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/NoneOf.py +112 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/Not.py +97 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/__init__.py +28 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/__init__.py +22 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/as_predicate.py +84 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/build_child_exception.py +39 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/describe_rule.py +72 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/validations/__init__.py +1 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_helpers/validations/raise_invalid_predicate.py +22 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/__init__.py +23 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_container_param_not_type_error.py +52 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_requires_at_least_one_rule_error.py +37 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/raise_rule_param_not_callable.py +54 -0
- simplibs_rules-0.1.0/src/simplibs/rules/containers/_init_validators/validate_compose_param_is_callable.py +72 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/__init__.py +103 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/__init__.py +18 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/accepts_one_positional_argument.py +127 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_helpers/format_container.py +50 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/__init__.py +40 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/__init__.py +21 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_has_length_param_conflict_error.py +53 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_regex_param_invalid_pattern_error.py +43 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/rule_errors/raise_user_rule_param_wrong_arity.py +53 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/__init__.py +32 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_bounds_inverted_error.py +78 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_min_max_incomparable_error.py +65 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_missing_error.py +77 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_callable_error.py +51 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_container_error.py +75 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_non_negative_integer_error.py +88 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_string_error.py +77 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_errors/raise_param_not_type_error.py +65 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/__init__.py +24 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_integer.py +73 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_not_zero.py +69 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_is_primitive_number.py +76 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/_init_validators/shared_validators/validate_param_remainder_in_range.py +58 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/CloseTo.py +149 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/DivisibleBy.py +120 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/HasRemainder.py +137 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/arithmetic/__init__.py +21 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsEmpty.py +101 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsFalse.py +81 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsNone.py +81 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/IsTrue.py +80 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/NotEmpty.py +100 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/checkers/__init__.py +25 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/AllUnique.py +124 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasItem.py +131 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasKey.py +104 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/HasKeys.py +115 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsContainer.py +99 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsSubsetOf.py +139 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/IsSupersetOf.py +138 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/collections/__init__.py +29 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/Equals.py +87 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/GreaterOrEqual.py +106 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/GreaterThan.py +106 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/InRange.py +166 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/LessOrEqual.py +106 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/LessThan.py +106 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/NotEquals.py +88 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/comparisons/__init__.py +29 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/HasAttribute.py +95 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/HasLength.py +177 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsCallable.py +81 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsDataclass.py +84 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsHashable.py +91 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsInstance.py +105 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsIterable.py +90 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsSubclass.py +122 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/IsType.py +82 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/introspection/__init__.py +34 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/Is.py +88 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/IsIn.py +144 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/IsNot.py +89 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/NotIn.py +145 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/UserRule.py +118 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/logic/__init__.py +24 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsBool.py +96 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsDecimal.py +83 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsEven.py +107 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsFinite.py +104 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsFloat.py +75 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsInfinity.py +97 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsInteger.py +118 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsNan.py +98 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsNumber.py +96 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsOdd.py +94 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsPi.py +138 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsPrimitiveNumber.py +87 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/IsZero.py +109 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/numeric/__init__.py +42 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/Contains.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/EndsWith.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAlnum.py +107 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAlpha.py +111 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsAscii.py +109 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsBlank.py +98 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsDigitString.py +115 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsLowercase.py +111 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsString.py +104 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsSubstringOf.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsTitlecase.py +130 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/IsUppercase.py +96 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/NotBlank.py +98 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/Regex.py +126 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/StartsWith.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/strings/__init__.py +44 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/IsAny.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/IsTyping.py +100 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/__init__.py +26 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/ORIGIN_TABLE.py +112 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/__init__.py +35 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_annotated_rule.py +106 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_any_of_rule.py +73 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_callable_rule.py +63 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_elements_rule.py +109 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_key_value_rule.py +65 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_literal_rule.py +60 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_tuple_rule.py +111 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_builders/build_type_rule.py +114 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_validations/__init__.py +16 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/_validations/raise_unsupported_annotation_error.py +63 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/build_typing_rule.py +131 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/__init__.py +20 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/get_supported_origins.py +42 -0
- simplibs_rules-0.1.0/src/simplibs/rules/predicates/typing/tools/is_supported_annotation.py +60 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/__init__.py +40 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/assert_rule_contract.py +198 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/__init__.py +27 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_build_exception.py +149 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_is_valid.py +90 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_param_error.py +77 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_raise_invalid.py +91 -0
- simplibs_rules-0.1.0/src/simplibs/rules/testing/asserts/assert_rule_validate.py +107 -0
- simplibs_rules-0.1.0/src/simplibs/rules/tools/__init__.py +16 -0
- simplibs_rules-0.1.0/src/simplibs/rules/tools/raise_invalid.py +84 -0
- simplibs_rules-0.1.0/src/simplibs_rules.egg-info/PKG-INFO +372 -0
- simplibs_rules-0.1.0/src/simplibs_rules.egg-info/SOURCES.txt +154 -0
- simplibs_rules-0.1.0/src/simplibs_rules.egg-info/dependency_links.txt +1 -0
- simplibs_rules-0.1.0/src/simplibs_rules.egg-info/requires.txt +5 -0
- 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
|
+
[](https://pypi.org/project/simplibs-rules/)
|
|
32
|
+
[](https://www.python.org/downloads/)
|
|
33
|
+
[](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)
|