pyspecification 0.1.0__py3-none-any.whl

pyspecification/__init__.py

@@ -0,0 +1,32 @@
+from .compilers import ExpressionWrapperDict, PredicateCompiler, PredicateDict
+from .exceptions import (
+    CompilationError,
+    ProcessArgumentError,
+    RuleAlreadyRegisteredError,
+    RuleKeyDoesNotExistError,
+    RuleNotRegisteredError,
+)
+from .json_schema import get_json_schema
+from .predicate import OperatorType, Predicate
+from .registry import ObjectRulesRegistry, SubscriptableRulesRegistry
+from .rules import object_rule, subscriptable_rule
+from .schemas import RuleSchema
+
+__all__ = [
+    "CompilationError",
+    "ExpressionWrapperDict",
+    "ObjectRulesRegistry",
+    "OperatorType",
+    "Predicate",
+    "PredicateCompiler",
+    "PredicateDict",
+    "ProcessArgumentError",
+    "RuleAlreadyRegisteredError",
+    "RuleKeyDoesNotExistError",
+    "RuleNotRegisteredError",
+    "RuleSchema",
+    "SubscriptableRulesRegistry",
+    "get_json_schema",
+    "object_rule",
+    "subscriptable_rule",
+]

pyspecification/compilers.py

@@ -0,0 +1,177 @@
+from collections.abc import Callable
+from typing import Any, Literal, TypedDict, TypeGuard
+
+from .exceptions import CompilationError
+from .predicate import Predicate, ReturnType
+
+type ExpressionDict = ExpressionWrapperDict | PredicateDict
+
+
+PREDICATE_DICT_KEYS = {"name", "args", "kwargs", "inverse"}
+EXPRESSION_WRAPPER_DICT_KEYS = {"operator", "expressions", "inverse"}
+
+
+class PredicateDict(TypedDict):
+    """A dictionary representation of a predicate."""
+
+    name: str
+    args: list[Any]
+    kwargs: dict[str, Any]
+    inverse: bool
+
+
+class ExpressionWrapperDict(TypedDict):
+    """A dictionary representation of an expression."""
+
+    operator: Literal["and", "or"]
+    expressions: list["ExpressionWrapperDict | PredicateDict"]
+    inverse: bool
+
+
+def is_predicate_dict(d: ExpressionDict | dict[str, Any]) -> TypeGuard[PredicateDict]:
+    return all(key in d for key in PREDICATE_DICT_KEYS) and len(d) == len(PREDICATE_DICT_KEYS)
+
+
+def is_expression_wrapper_dict(
+    d: ExpressionDict | dict[str, Any],
+) -> TypeGuard[ExpressionWrapperDict]:
+    return all(key in d for key in EXPRESSION_WRAPPER_DICT_KEYS) and len(d) == len(
+        EXPRESSION_WRAPPER_DICT_KEYS
+    )
+
+
+class PredicateCompiler[T, R: ReturnType]:
+    """A compiler for predicates.
+
+    Args:
+        rules (dict[str, Callable[..., Predicate[Any, Any]]]): The rules to use for compiling.
+        initial_predicate_factory (Callable[[ExpressionWrapperDict], Predicate[Any, Any]]): The factory to use for creating initial predicates.
+
+    Example:
+    ```python
+    from pyspecification import Predicate, PredicateCompiler, object_rule
+
+
+    @object_rule
+    def is_admin(user: User) -> bool:
+        return user.is_admin
+
+
+    @object_rule
+    def name__istartswith(user: User, value: str) -> bool:
+        return user.name.lower().startswith(value.lower())
+
+
+    @object_rule
+    def age__between(user: User, min_age: int, max_age: int) -> bool:
+        return user.age >= min_age and user.age <= max_age
+
+
+    def main() -> None:
+        rules = {
+            "is_admin": is_admin,
+            "name__istartswith": name__istartswith,
+            "age__between": age__between,
+        }
+
+        compiler = PredicateCompiler(
+            rules,
+            lambda schema: Predicate(lambda _: schema["operator"] == "and"),
+        )
+
+        rule_data = {
+            "operator": "or",
+            "inverse": False,
+            "expressions": [
+                {
+                    "name": "is_admin",
+                    "inverse": False,
+                    "args": [],
+                    "kwargs": {},
+                },
+                {
+                    "operator": "and",
+                    "inverse": False,
+                    "expressions": [
+                        {
+                            "name": "name__istartswith",
+                            "inverse": False,
+                            "args": ["admin"],
+                            "kwargs": {},
+                        },
+                        {
+                            "name": "age__between",
+                            "inverse": False,
+                            "args": [18, 30],
+                            "kwargs": {},
+                        },
+                    ],
+                },
+            ],
+        }
+
+        predicate = compiler.compile(rule_data)
+
+        assert all(predicate(user) for user in users)
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+    """  # noqa: E501
+
+    def __init__(
+        self,
+        rules: dict[str, Callable[..., Predicate[T, R]]],
+        initial_predicate_factory: Callable[[ExpressionWrapperDict], Predicate[T, R]],
+    ) -> None:
+        self._rules = rules
+        self._initial_predicate_factory = initial_predicate_factory
+
+    def compile(self, expression: ExpressionDict) -> Predicate[T, R]:
+        """Compiles an expression into a predicate."""
+        if is_expression_wrapper_dict(expression):
+            return self._compile_wrapper(expression)
+
+        if is_predicate_dict(expression):
+            return self._compile_single(expression)
+
+        msg = (
+            f"Invalid expression type: {expression}\n"
+            f"Expected one of\n"
+            "{'expressions': list[ExpressionDict], 'inverse': bool, 'operator': Literal['and', 'or']}\n"  # noqa: E501
+            "or \n{'name': str, 'inverse': bool, 'args': list, 'kwargs': dict}"
+        )
+        raise CompilationError(msg)
+
+    def _compile_single(self, single: PredicateDict) -> Predicate[T, R]:
+        if single["name"] not in self._rules:
+            msg = (
+                f"Rule '{single['name']}' is not found\n"
+                f"Available rules: {', '.join(self._rules.keys())}"
+            )
+            raise CompilationError(msg)
+
+        predicate = self._rules[single["name"]](*single["args"], **single["kwargs"])
+
+        if single["inverse"]:
+            predicate = ~predicate
+
+        return predicate
+
+    def _compile_wrapper(self, wrapper: ExpressionWrapperDict) -> Predicate[T, R]:
+        predicate = self._initial_predicate_factory(wrapper)
+
+        for expression in wrapper["expressions"]:
+            compiled_predicate = self.compile(expression)
+
+            if wrapper["operator"] == "and":
+                predicate &= compiled_predicate
+            else:
+                predicate |= compiled_predicate
+
+        if wrapper["inverse"]:
+            predicate = ~predicate
+
+        return predicate

pyspecification/constants.py

@@ -0,0 +1 @@
+RESERVED_WORDS = ("name", "expressions", "operator", "inverse", "args", "kwargs")

pyspecification/exceptions.py

@@ -0,0 +1,27 @@
+class RuleNotRegisteredError(Exception):
+    """Exception raised when a rule is not registered in registry class."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Rule '{name}' is not registered")
+
+
+class RuleAlreadyRegisteredError(Exception):
+    """Exception raised when a rule is already registered in registry class."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Rule '{name}' is already registered")
+
+
+class RuleKeyDoesNotExistError(Exception):
+    """Exception raised when a key does not exist in the object of rule."""
+
+    def __init__(self, key: str, rule_name: str) -> None:
+        super().__init__(f"Key '{key}' does not exist in the object of rule '{rule_name}'")
+
+
+class CompilationError(Exception):
+    """Exception raised when a rule compilation fails."""
+
+
+class ProcessArgumentError(Exception):
+    """Exception raised when a process argument fails in registry class."""

pyspecification/json_schema.py

@@ -0,0 +1,64 @@
+from collections.abc import Callable
+from inspect import get_annotations
+from typing import Any
+
+from pydantic import TypeAdapter
+
+
+def get_json_schema(rule: Callable[..., Any]) -> dict[str, Any]:
+    """Get the JSON schema for a rule.
+
+    Args:
+        rule (Callable): The rule to get the JSON schema for.
+
+    Returns:
+        dict: The JSON schema for the rule.
+
+    Example:
+    ```python
+    from pyspecification import get_json_schema, object_rule
+
+
+    @object_rule
+    def is_admin(user: User) -> bool:
+        return user.is_admin
+
+
+    @object_rule
+    def name__istartswith(user: User, value: str) -> bool:
+        return user.name.lower().startswith(value.lower())
+
+
+    @object_rule
+    def age__between(user: User, min_age: int, max_age: int) -> bool:
+        return user.age >= min_age and user.age <= max_age
+
+
+    def main() -> None:
+        schema = get_json_schema(is_admin)
+        print(schema)
+        # {"return": {"type": "boolean"}}
+
+        schema = get_json_schema(name__istartswith)
+        print(schema)
+        # {"value": {"type": "string"}, "return": {"type": "boolean"}}
+
+        schema = get_json_schema(age__between)
+        print(schema)
+        # {
+        #     "min_age": {"type": "integer"},
+        #     "max_age": {"type": "integer"},
+        #     "return": {"type": "boolean"},
+        # }
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+    """
+    return {
+        arg: TypeAdapter(typ).json_schema()
+        for idx, (arg, typ) in enumerate(get_annotations(rule).items())
+        if idx > 0
+    }

pyspecification/predicate.py

@@ -0,0 +1,142 @@
+# ruff: noqa: PGH003, SLF001
+
+from collections.abc import Callable
+from typing import Any, Literal, Protocol
+
+type OperatorType = Literal["bitwise", "logical"]
+
+
+class ReturnType(Protocol):
+    def __and__(self, value: Any, /) -> Any: ...
+    def __or__(self, value: Any, /) -> Any: ...
+    def __invert__(self) -> Any: ...
+
+
+class Predicate[T, R: ReturnType]:
+    """A predicate is a function that takes an object of type T and returns a value of type R.
+
+    Args:
+        fn (Callable[[T], R]): The function to wrap.
+        operator (Literal["bitwise", "logical"]): The operator to use for combining predicates.
+        description (str, optional): A description of the predicate. Defaults to None.
+
+    Example:
+    ```python
+    from pyspecification import Predicate
+
+
+    def is_admin(user: User) -> bool:
+        return user.is_admin
+
+
+    def name__istartswith(user: User, value: str) -> bool:
+        return user.name.lower().startswith(value.lower())
+
+
+    def age__between(user: User, min_age: int, max_age: int) -> bool:
+        return user.age >= min_age and user.age <= max_age
+
+
+    is_admin: Predicate[User, bool] = Predicate(
+        is_admin,
+        operator="logical",
+    )
+    name__istartswith: Predicate[User, bool] = Predicate(
+        name__istartswith,
+        operator="logical",
+    )
+    age__between: Predicate[User, bool] = Predicate(
+        age__between,
+        operator="logical",
+    )
+
+
+    rule = is_admin | (name__istartswith("admin") & age__between(18, 30))
+
+
+    def main() -> None:
+        assert rule(User(name="Abdullah", age=18, is_admin=True))
+        assert rule(User(name="Abdullah", age=16, is_admin=True))
+        assert rule(User(name="admin", age=20, is_admin=False))
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+    """
+
+    def __init__(
+        self,
+        fn: Callable[[T], R],
+        /,
+        *,
+        operator: OperatorType,
+        description: str | None = None,
+    ) -> None:
+        self._fn = fn
+        self._description = description
+        self._operator = operator
+
+    def __call__(self, obj: T) -> R:
+        return self._fn(obj)
+
+    def __and__(self, other: "Predicate[T, R]") -> "Predicate[T, R]":
+        self._insure_matching_operators(other)
+
+        if self._operator == "bitwise":
+            return Predicate(
+                lambda obj: self(obj) & other(obj),
+                description=f"({self} & {other})",
+                operator="bitwise",
+            )
+
+        return Predicate(
+            lambda obj: self(obj) and other(obj),
+            description=f"({self} AND {other})",
+            operator="logical",
+        )
+
+    def __or__(self, other: "Predicate[T, R]") -> "Predicate[T, R]":
+        self._insure_matching_operators(other)
+
+        if self._operator == "bitwise":
+            return Predicate(
+                lambda obj: self(obj) | other(obj),
+                description=f"({self} | {other})",
+                operator="bitwise",
+            )
+
+        return Predicate(
+            lambda obj: self(obj) or other(obj),
+            description=f"({self} OR {other})",
+            operator="logical",
+        )
+
+    def __invert__(self) -> "Predicate[T, R]":
+        if self._operator == "bitwise":
+            return Predicate(
+                lambda obj: ~self(obj),
+                description=f"~{self}",
+                operator="bitwise",
+            )
+
+        return Predicate(
+            lambda obj: not self(obj),  # type: ignore
+            description=f"NOT {self}",
+            operator="logical",
+        )
+
+    def __str__(self) -> str:
+        return self._description or self._fn.__name__ or "Predicate"
+
+    def __repr__(self) -> str:
+        return f"Predicate({self})"
+
+    def _insure_matching_operators(self, other: "Predicate[T, R]") -> None:
+        if self._operator != other._operator:
+            msg = (
+                "Cannot combine predicates with different operators:"
+                f" {self._operator} != {other._operator}"
+            )
+            raise ValueError(msg)

pyspecification/processors.py

@@ -0,0 +1,43 @@
+from collections.abc import Callable
+from typing import Any
+
+from .exceptions import ProcessArgumentError
+
+type ProcessFn = Callable[[Any], Any]
+
+
+DEFAULT_PROCESSORS: tuple[ProcessFn, dict[str, ProcessFn]] = (lambda value: value, {})
+
+
+def process_arguments(
+    processors: tuple[ProcessFn, dict[str, ProcessFn]],
+    *args: Any,
+    **kwargs: Any,
+) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    default_fn, processors_map = processors
+
+    processed_args = []
+    current_arg = None
+
+    try:
+        for arg in args:
+            current_arg = arg
+            processed_args.append(default_fn(arg))
+    except Exception as e:
+        msg = f"Argument '{current_arg}' failed to process, {e}"
+        raise ProcessArgumentError(msg) from e
+
+    processed_kwargs = {}
+    current_key, current_value = None, None
+
+    try:
+        for key, value in kwargs.items():
+            current_key, current_value = key, value
+            processed_kwargs[key] = processors_map.get(key, default_fn)(value)
+    except Exception as e:
+        msg = (
+            f"Keyword argument '{current_key}' with value '{current_value}' failed to process, {e}"
+        )
+        raise ProcessArgumentError(msg) from e
+
+    return tuple(processed_args), processed_kwargs