pyspecification 2.0.0__tar.gz → 2.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyspecification
-Version: 2.0.0
+Version: 2.0.2
 Summary: A lightweight, typed Python library for composing business rules as reusable, executable predicates.
 Author: aaltatan
 Author-email: aaltatan <a.altatan@gmail.com>
@@ -354,6 +354,140 @@ This pattern is especially useful when you want:
 
 ---
 
+### 6. Django ORM integration example
+
+This example demonstrates how to use `pyspecification` with Django models.
+`pyspecification` does not import Django or provide a Django-specific adapter;
+the rules return Django `Q` objects, while the existing bitwise predicate
+composition supplies `&`, `|`, and `~` support.
+
+```python
+# models.py
+from typing import Any, Self
+
+from django.db import models
+from pyspecification import Predicate
+
+
+class EmployeeQuerySet(models.QuerySet):
+    def filter_by_rule(self, rule: Predicate[Any, models.Q]) -> Self:
+        return self.filter(rule(Employee))
+
+
+class EmployeeManager(models.Manager):
+    def get_queryset(self) -> EmployeeQuerySet:
+        return EmployeeQuerySet(self.model, using=self._db)
+
+    def filter_by_rule(self, rule: Predicate[Any, models.Q]) -> EmployeeQuerySet:
+        return self.get_queryset().filter_by_rule(rule)
+
+
+class Employee(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+    is_admin = models.BooleanField(default=False)
+
+    objects = EmployeeManager()
+
+    def __str__(self) -> str:
+        return self.name
+```
+
+```python
+# rules.py
+from typing import Any
+
+from pyspecification import ObjectRulesRegistry
+from django.db.models import Q
+
+
+registry = ObjectRulesRegistry[Any, Q](operator="bitwise")
+
+
+@registry.rule()
+def is_admin(_: Any) -> Q:
+    return Q(is_admin=True)
+
+
+@registry.rule()
+def name__eq(_: Any, value: str) -> Q:
+    return Q(name=value)
+
+
+@registry.rule()
+def age__gte(_: Any, value: int) -> Q:
+    return Q(age__gte=value)
+
+
+@registry.rule()
+def age__lte(_: Any, value: int) -> Q:
+    return Q(age__lte=value)
+```
+
+```python
+# views.py
+from typing import Any
+
+from django.db.models import Q
+from django.http import HttpRequest, HttpResponse
+from pyspecification import Predicate, PredicateCompiler
+
+from .rules import registry
+from .models import Employee
+
+
+FILTER_RULE = {
+    "operator": "any",
+    "expressions": [
+        {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "operator": "all",
+            "expressions": [
+                {
+                    "name": "name__eq",
+                    "args": ["admin"],
+                    "kwargs": {},
+                    "inverse": False,
+                },
+                {
+                    "name": "age__gte",
+                    "args": [18],
+                    "kwargs": {},
+                    "inverse": False,
+                },
+            ]
+        }
+    ]
+}
+
+compiler = PredicateCompiler[Any, Q](
+    registry.rules,
+    lambda _: Predicate(lambda _: Q(), operator="bitwise"),
+)
+
+def filter_employees(request: HttpRequest) -> HttpResponse:
+    predicate = compiler.compile(FILTER_RULE)
+    employees = Employee.objects.filter_by_rule(predicate)
+    return HttpResponse(f"Employees: {employees}")
+```
+
+The model, rule, and view snippets can live in their normal Django app
+modules. No Django settings or model changes are required beyond the standard
+Django project setup.
+
+This pattern is especially useful when you want:
+
+- declarative Django queryset filters
+- reusable admin and dashboard filter rules
+- object-level permissions backed by Django `Q` expressions
+
+---
+
 ## Custom processors
 
 Rules can apply argument processors to coerce values before evaluation.

{pyspecification-2.0.0 → pyspecification-2.0.2}/README.md

@@ -340,6 +340,140 @@ This pattern is especially useful when you want:
 
 ---
 
+### 6. Django ORM integration example
+
+This example demonstrates how to use `pyspecification` with Django models.
+`pyspecification` does not import Django or provide a Django-specific adapter;
+the rules return Django `Q` objects, while the existing bitwise predicate
+composition supplies `&`, `|`, and `~` support.
+
+```python
+# models.py
+from typing import Any, Self
+
+from django.db import models
+from pyspecification import Predicate
+
+
+class EmployeeQuerySet(models.QuerySet):
+    def filter_by_rule(self, rule: Predicate[Any, models.Q]) -> Self:
+        return self.filter(rule(Employee))
+
+
+class EmployeeManager(models.Manager):
+    def get_queryset(self) -> EmployeeQuerySet:
+        return EmployeeQuerySet(self.model, using=self._db)
+
+    def filter_by_rule(self, rule: Predicate[Any, models.Q]) -> EmployeeQuerySet:
+        return self.get_queryset().filter_by_rule(rule)
+
+
+class Employee(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+    is_admin = models.BooleanField(default=False)
+
+    objects = EmployeeManager()
+
+    def __str__(self) -> str:
+        return self.name
+```
+
+```python
+# rules.py
+from typing import Any
+
+from pyspecification import ObjectRulesRegistry
+from django.db.models import Q
+
+
+registry = ObjectRulesRegistry[Any, Q](operator="bitwise")
+
+
+@registry.rule()
+def is_admin(_: Any) -> Q:
+    return Q(is_admin=True)
+
+
+@registry.rule()
+def name__eq(_: Any, value: str) -> Q:
+    return Q(name=value)
+
+
+@registry.rule()
+def age__gte(_: Any, value: int) -> Q:
+    return Q(age__gte=value)
+
+
+@registry.rule()
+def age__lte(_: Any, value: int) -> Q:
+    return Q(age__lte=value)
+```
+
+```python
+# views.py
+from typing import Any
+
+from django.db.models import Q
+from django.http import HttpRequest, HttpResponse
+from pyspecification import Predicate, PredicateCompiler
+
+from .rules import registry
+from .models import Employee
+
+
+FILTER_RULE = {
+    "operator": "any",
+    "expressions": [
+        {
+            "name": "is_admin",
+            "args": [],
+            "kwargs": {},
+            "inverse": False,
+        },
+        {
+            "operator": "all",
+            "expressions": [
+                {
+                    "name": "name__eq",
+                    "args": ["admin"],
+                    "kwargs": {},
+                    "inverse": False,
+                },
+                {
+                    "name": "age__gte",
+                    "args": [18],
+                    "kwargs": {},
+                    "inverse": False,
+                },
+            ]
+        }
+    ]
+}
+
+compiler = PredicateCompiler[Any, Q](
+    registry.rules,
+    lambda _: Predicate(lambda _: Q(), operator="bitwise"),
+)
+
+def filter_employees(request: HttpRequest) -> HttpResponse:
+    predicate = compiler.compile(FILTER_RULE)
+    employees = Employee.objects.filter_by_rule(predicate)
+    return HttpResponse(f"Employees: {employees}")
+```
+
+The model, rule, and view snippets can live in their normal Django app
+modules. No Django settings or model changes are required beyond the standard
+Django project setup.
+
+This pattern is especially useful when you want:
+
+- declarative Django queryset filters
+- reusable admin and dashboard filter rules
+- object-level permissions backed by Django `Q` expressions
+
+---
+
 ## Custom processors
 
 Rules can apply argument processors to coerce values before evaluation.

{pyspecification-2.0.0 → pyspecification-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyspecification"
-version = "2.0.0"
+version = "2.0.2"
 description = "A lightweight, typed Python library for composing business rules as reusable, executable predicates."
 readme = "README.md"
 requires-python = ">=3.12"

{pyspecification-2.0.0 → pyspecification-2.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "pyspecification"
-version = "2.0.0"
+version = "2.0.2"
 description = "A lightweight, typed Python library for composing business rules as reusable, executable predicates."
 readme = "README.md"
 authors = [{ name = "aaltatan", email = "a.altatan@gmail.com" }]

{pyspecification-2.0.0 → pyspecification-2.0.2}/src/pyspecification/registry.py

@@ -172,12 +172,12 @@ class ObjectRulesRegistry[T, R: ReturnType]:
     ) -> ObjectRuleFn[T, R, P]:
         rule_name = _process_rule_name(fn, name)
 
-        if hidden:
-            self._hidden.add(rule_name)
-
         if rule_name in self._rules:
             raise RuleAlreadyRegisteredError(rule_name)
 
+        if hidden:
+            self._hidden.add(rule_name)
+
         @wraps(fn)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> Predicate[T, R]:
             processed_args, processed_kwargs = process_arguments(processors, *args, **kwargs)
@@ -364,12 +364,12 @@ class SubscriptableRulesRegistry[T, K, R: ReturnType]:
     ) -> SubscriptableRuleFn[T, K, R, P]:
         rule_name = _process_rule_name(fn, name)
 
-        if hidden:
-            self._hidden.add(rule_name)
-
         if rule_name in self._rules:
             raise RuleAlreadyRegisteredError(rule_name)
 
+        if hidden:
+            self._hidden.add(rule_name)
+
         @wraps(fn)
         def wrapper(key: K, *args: P.args, **kwargs: P.kwargs) -> Predicate[T, R]:
 

{pyspecification-2.0.0 → pyspecification-2.0.2}/src/pyspecification/rules.py

@@ -168,7 +168,7 @@ def subscriptable_rule[T, K, R: ReturnType, **P](
                         check_key_existence
                         and isinstance(obj, list)
                         and isinstance(key, int)
-                        and len(obj) <= key
+                        and not (-len(obj) <= key < len(obj))
                     ),
                     lambda: check_key_existence and isinstance(obj, dict) and key not in obj,
                 ]