pyspecification 0.1.4__tar.gz → 2.0.0__tar.gz

{pyspecification-0.1.4 → pyspecification-2.0.0}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.3
 Name: pyspecification
-Version: 0.1.4
+Version: 2.0.0
 Summary: A lightweight, typed Python library for composing business rules as reusable, executable predicates.
 Author: aaltatan
 Author-email: aaltatan <a.altatan@gmail.com>
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
-Requires-Dist: pydantic==2.5.3
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/aaltatan/pyspecification
 Project-URL: Issues, https://github.com/aaltatan/pyspecification/issues
@@ -25,7 +24,7 @@ This project was inspired by the work and ideas shared by [ArjanCodes](https://g
 - predicates compose with `&`, `|`, and `~`
 - registry-based registration keeps rules organized
 - structured rule definitions can be compiled from dictionaries or JSON-like payloads
-- generated schemas make rule metadata portable and machine-readable
+- structured rule definitions make rule metadata portable and machine-readable
 
 It is especially useful for filtering, validation, authorization checks, and declarative rule engines without introducing a heavy framework.
 
@@ -68,7 +67,6 @@ This keeps your logic:
 - Registry pattern for rule registration and lookup
 - Custom argument processors for coercion and normalization
 - `PredicateCompiler` for compiling structured rule dictionaries into executable predicates
-- `RuleSchema` validation for declarative rule payloads
 - JSON schema generation for rule arguments and return types
 - Support for both logical and bitwise operator modes
 - Hidden rules and custom naming for internal/private rule registration
@@ -251,7 +249,7 @@ One of the strongest real-world use cases is turning rule definitions into SQLAl
 ```python
 from typing import Any
 
-from pyspecification import ObjectRulesRegistry, Predicate, PredicateCompiler, RuleSchema
+from pyspecification import ObjectRulesRegistry, Predicate, PredicateCompiler
 from sqlalchemy import ColumnElement, and_, create_engine, or_
 from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column, sessionmaker
 
@@ -313,24 +311,36 @@ def age__le(model: type[User], value: int) -> ColumnElement[bool]:
 compiler = PredicateCompiler(
     rules.rules,
     lambda schema: Predicate(
-        lambda _: and_(True) if schema["operator"] == "and" else or_(False),
+        lambda _: and_(True) if schema["operator"] == "all" else or_(False),
         operator="bitwise",
     ),
 )
 
 filter_rule_data = {
-    "operator": "or",
+    "operator": "any",
     "expressions": [
-        {"-is_admin": []},
-        {"age__ge": [18]},
+        {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "name": "age__ge",
+            "args": [18],
+            "kwargs": {},
+            "inverse": False,
+        }
     ],
 }
 
-predicate = compiler.compile(RuleSchema(**filter_rule_data).model_dump())
+predicate = compiler.compile(filter_rule_data)
+# is_admin() | age__ge(18)
+# User.is_admin | User.age >= 18
 
 with SessionLocal() as session:
     users = session.query(User).filter(predicate(User)).all()
-    print([user.name for user in users])
+    print([user.name for user in users])  # ['Abdullah', 'Bob', 'Charlie', 'Eve']
 ```
 
 This pattern is especially useful when you want:
@@ -397,7 +407,7 @@ If conversion fails, the library raises `ProcessArgumentError`.
 ```python
 from dataclasses import dataclass
 
-from pyspecification import Predicate, PredicateCompiler, RuleSchema, object_rule
+from pyspecification import Predicate, PredicateCompiler, object_rule
 
 
 @dataclass
@@ -430,83 +440,48 @@ rules = {
 
 compiler = PredicateCompiler(
     rules,
-    lambda schema: Predicate(lambda _: schema["operator"] == "and", operator="logical"),
+    lambda schema: Predicate(lambda _: schema["operator"] == "all", operator="logical"),
 )
 
 rule_data = {
-    "operator": "or",
+    "operator": "any",
     "expressions": [
-        {"is_admin": []},
         {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "operator": "all",
             "expressions": [
-                {"name__istartswith": "admin"},
-                {"age__between": [18, 30]},
-            ]
+                {
+                    "name": "name__istartswith", 
+                    "args": ["admin"], 
+                    "kwargs": {}, 
+                    "inverse": False,
+                },
+                {
+                    "name": "age__between", 
+                    "args": [18, 30], 
+                    "kwargs": {}, 
+                    "inverse": False,
+                },
+            ],
         },
     ],
 }
 
-predicate = compiler.compile(RuleSchema(**rule_data).model_dump())
-print(predicate(User("admin", 25, True)))  # True
-```
-
-### Predicate schema
-
-`PredicateCompiler.compile()` consumes the normalized dictionary produced by
-`RuleSchema(...).model_dump()`. A predicate schema always has four keys:
-
-```json
-{
-    "name": "rule_name",
-    "args": [],
-    "kwargs": {},
-    "inverse": false
-}
-```
-
-The `name` must be present in the dictionary of rules passed to the compiler.
-Use `args` for positional arguments and `kwargs` for keyword arguments. These
-examples assume the rules from the previous section:
-
-```json
-{
-    "name": "is_admin",
-    "args": [],
-    "kwargs": {},
-    "inverse": false
-}
-```
-
-```json
-{
-    "name": "name__istartswith",
-    "args": ["admin"],
-    "kwargs": {},
-    "inverse": false
-}
-```
-
-```json
-{
-    "name": "age__between",
-    "args": [],
-    "kwargs": {"min_age": 18, "max_age": 30},
-    "inverse": false
-}
-```
-
-Set `inverse` to `true` to negate one predicate:
+predicate = compiler.compile(rule_data)
+# is_admin() | (name__istartswith("admin") & age__between(18, 30))
 
-```json
-{
-    "name": "is_admin",
-    "args": [],
-    "kwargs": {},
-    "inverse": true
-}
+print(predicate(User("admin", 25, True)))  # True
 ```
 
-The normalized schema is convenient when rule definitions arrive as JSON:
+`PredicateCompiler.compile()` consumes a normalized dictionary. The `name`
+must be present in the dictionary of rules passed to the compiler. Use `args`
+for positional arguments, `kwargs` for keyword arguments, and `inverse` to
+negate one predicate:
 
 ```python
 import json
@@ -514,16 +489,16 @@ import json
 rule_json = '{"name": "age__between", "args": [18, 30], "kwargs": {}, "inverse": false}'
 rule_data = json.loads(rule_json)
 predicate = compiler.compile(rule_data)
-```
 
-### Expression wrapper schema
+print(repr(predicate))  # Predicate(age__between)
+```
 
-Use a wrapper to combine predicates. A wrapper has an `operator`, an
-`expressions` list, and an `inverse` flag:
+Use a wrapper to combine predicates. A wrapper has an `operator` and an
+`expressions` list:
 
 ```json
 {
-    "operator": "and",
+    "operator": "all",
     "expressions": [
         {
             "name": "is_admin",
@@ -537,17 +512,16 @@ Use a wrapper to combine predicates. A wrapper has an `operator`, an
             "kwargs": {},
             "inverse": false
         }
-    ],
-    "inverse": false
-}
+    ]
+} // is_admin() & age__between(18, 30)
 ```
 
-`operator` must be either `"and"` or `"or"`. Expressions can be nested to
+`operator` must be either `"all"` or `"any"`. Expressions can be nested to
 represent more complex logic:
 
 ```json
 {
-    "operator": "or",
+    "operator": "any",
     "expressions": [
         {
             "name": "is_admin",
@@ -556,7 +530,7 @@ represent more complex logic:
             "inverse": false
         },
         {
-            "operator": "and",
+            "operator": "all",
             "expressions": [
                 {
                     "name": "name__istartswith",
@@ -570,90 +544,27 @@ represent more complex logic:
                     "kwargs": {"min_age": 18, "max_age": 30},
                     "inverse": false
                 }
-            ],
-            "inverse": false
-        }
-    ],
-    "inverse": false
-}
-```
-
-You can also invert a complete wrapper:
-
-```json
-{
-    "operator": "or",
-    "expressions": [
-        {
-            "name": "is_admin",
-            "args": [],
-            "kwargs": {},
-            "inverse": false
-        },
-        {
-            "name": "age__between",
-            "args": [18, 30],
-            "kwargs": {},
-            "inverse": false
+            ]
         }
-    ],
-    "inverse": true
-}
-```
-
-For shorthand forms, validate the payload with `RuleSchema` first. It converts
-them into the normalized predicate and wrapper schemas:
-
-```python
-{"is_admin": []}
-{"-is_admin": []}
-{"name__istartswith": "admin"}
-{"age__between": [18, 30]}
-{"name__startswith": {"value": "admin"}}
+    ]
+} // is_admin() | (name__istartswith("admin") & age__between(min_age=18, max_age=30))
 ```
 
 The compiler raises `RuleDoesNotExistError` when a predicate name is not in the
 compiler's rule mapping. If the dictionary passed directly to `compile()` does
-not match a predicate or wrapper schema, it raises `TypeError`. The error
-includes the location of the invalid expression, the expected schemas, and the
-received value. Validate external or shorthand payloads with `RuleSchema`
-before compilation.
+not match a predicate or wrapper shape, it raises `TypeError`.
 
 ---
-
-## Rule schema validation
-
-`RuleSchema` validates declarative rule payloads.
-
-```python
-from pyspecification import RuleSchema
-
-rule_data = {
-    "operator": "and",
-    "expressions": [
-        {"name__startswith": "admin"},
-        {"age__gt": 18},
-    ],
-}
-
-schema = RuleSchema(**rule_data)
-print(schema.model_dump())
-```
-
-This is useful when you want to validate incoming rule definitions before compile-time execution.
-
-You can also use `RuleSchema` to represent nested predicate trees as typed, portable data.
-
 ---
 
 ## JSON schema generation
 
-`get_json_schema` inspects a rule function and returns JSON-schema-like metadata for parameters and return value.
+`get_rule_json_schema` inspects a rule function and returns JSON-schema-like metadata for parameters and return value.
 
 ```python
 from dataclasses import dataclass
 
-from pyspecification import get_json_schema, object_rule
+from pyspecification import get_rule_json_schema, object_rule
 
 
 @dataclass
@@ -668,11 +579,8 @@ def name__istartswith(user: User, value: str) -> bool:
     return user.name.lower().startswith(value.lower())
 
 
-print(get_json_schema(name__istartswith))
-# {
-#   "value": {"type": "string"},
-#   "return": {"type": "boolean"},
-# }
+print(get_rule_json_schema(name__istartswith))
+# {'value': {'type': 'string'}, 'return': {'type': 'boolean'}}
 ```
 
 This is useful for:
@@ -731,7 +639,7 @@ filtered = [user for user in users if predicate(user)]
 This is one of the most useful real-world patterns for the package. You can define a reusable rule set and compile it into SQLAlchemy boolean expressions for database queries.
 
 ```python
-from pyspecification import ObjectRulesRegistry, Predicate, PredicateCompiler, RuleSchema
+from pyspecification import ObjectRulesRegistry, Predicate, PredicateCompiler
 from sqlalchemy import ColumnElement, and_, or_
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
@@ -765,20 +673,32 @@ def age__ge(model: type[User], value: int) -> ColumnElement[bool]:
 compiler = PredicateCompiler(
     rules.rules,
     lambda schema: Predicate(
-        lambda _: and_(True) if schema["operator"] == "and" else or_(False),
+        lambda _: and_(True) if schema["operator"] == "all" else or_(False),
         operator="bitwise",
     ),
 )
 
 filter_rule = {
-    "operator": "or",
+    "operator": "any",
     "expressions": [
-        {"is_admin": []},
-        {"age__ge": [18]},
+        {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "name": "age__ge",
+            "args": [18],
+            "kwargs": {},
+            "inverse": False,
+        },
     ],
 }
 
-query_predicate = compiler.compile(RuleSchema(**filter_rule).model_dump())
+query_predicate = compiler.compile(filter_rule)
+# is_admin() | age__ge(18)
+# User.is_admin | User.age >= 18
 ```
 
 This makes it easy to expose admin filters, user search rules, and role-based queries without manually stitching SQL conditions together.
@@ -795,7 +715,7 @@ This allows readable authorization checks without large condition trees.
 
 ### 3. Dynamic rule engines
 
-The compiler and schema APIs make it easy to store or receive rules as structured data.
+The compiler makes it easy to store or receive rules as structured data.
 
 Examples:
 
@@ -836,10 +756,6 @@ Rules should do one thing and avoid hidden side effects.
 
 If your project has many rules, registries provide structure and reduce duplication.
 
-### Validate schema before compile
-
-If you load rules from external sources, validate them via `RuleSchema` before compiling.
-
 ---
 
 ## Exceptions
@@ -870,7 +786,7 @@ rule. Its specialized exceptions describe the problem:
 `RuleDoesNotExistError` includes the missing name and the available rule names,
 which is useful when rules are dynamically loaded. Malformed normalized
 compiler payloads raise `TypeError`; its message identifies the JSON-like path
-of the invalid expression and shows the expected schemas.
+of the invalid expression and shows the expected shapes.
 
 ---
 
@@ -880,14 +796,13 @@ This project includes runnable examples under the `scripts/` directory:
 
 - `scripts/rules_example.py` — basic object-based rule composition
 - `scripts/reg_example.py` — registry usage and compiled rule predicate patterns
-- `scripts/json_schema_example.py` — JSON schema generation examples
 
 The test suite under `tests/` also demonstrates behavior for:
 
 - registry registration
 - predicate composition
 - compiler validation
-- schema serialization
+- structured rule compilation
 - filtering workflows
 
 ---
@@ -897,7 +812,7 @@ The test suite under `tests/` also demonstrates behavior for:
 ```python
 from dataclasses import dataclass
 
-from pyspecification import ObjectRulesRegistry, PredicateCompiler, RuleSchema
+from pyspecification import ObjectRulesRegistry, Predicate, PredicateCompiler
 
 
 @dataclass
@@ -926,21 +841,37 @@ def age__between(user: User, min_age: int, max_age: int) -> bool:
 
 
 rule_definition = {
-    "operator": "or",
+    "operator": "any",
     "expressions": [
-        {"is_admin": []},
         {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "operator": "all",
             "expressions": [
-                {"name__istartswith": "admin"},
-                {"age__between": [18, 30]},
+                {
+                    "name": "name__istartswith",
+                    "args": ["admin"],
+                    "kwargs": {},
+                    "inverse": False,
+                },
+                {
+                    "name": "age__between",
+                    "args": [18, 30],
+                    "kwargs": {},
+                    "inverse": False,
+                },
             ]
         },
     ],
 }
 
-schema = RuleSchema(**rule_definition)
 compiler = PredicateCompiler(registry.rules, lambda spec: Predicate(lambda _: True, operator="logical"))
-predicate = compiler.compile(schema.model_dump())
+predicate = compiler.compile(rule_definition)
+# is_admin() | (name__istartswith("admin") & age__between(18, 30))
 
 users = [
     User("Abdullah", 18, True),
@@ -948,20 +879,20 @@ users = [
     User("Charlie", 12, False),
 ]
 
-print([predicate(user) for user in users])
+print([predicate(user) for user in users])  # [True, True, False]
 ```
 
 ---
 
 ## Summary
 
-`pyspecification` brings together rule registration, predicate composition, schema validation, and runtime compilation in a compact library designed around functional and declarative rule authoring.
+`pyspecification` brings together rule registration, predicate composition, and runtime compilation in a compact library designed around functional and declarative rule authoring.
 
 It is a practical fit for projects that need to:
 
 - express business rules clearly
 - compose conditions without nested `if` chains
-- validate dynamic rule payloads
+- compile dynamic rule payloads
 - support filtering and policy evaluation
 - keep rule logic easy to test and maintain