python-jsonlogic 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

jsonlogic/__init__.py

@@ -0,0 +1,3 @@
+from .core import JSONLogicExpression, JSONLogicSyntaxError, Operator
+
+__all__ = ("JSONLogicExpression", "JSONLogicSyntaxError", "Operator")

jsonlogic/_compat.py

@@ -1,8 +1,12 @@
 import sys
 
-if sys.version_info >= (3, 12):
-    from typing import Self, TypeAlias, TypeAliasType
+if sys.version_info >= (3, 13):
+    from types import NoneType
+    from typing import Self, TypeAlias, TypeIs, TypeVarTuple, Unpack
 else:
-    from typing_extensions import Self, TypeAlias, TypeAliasType
+    from typing_extensions import Self, TypeAlias, TypeIs, TypeVarTuple, Unpack
 
-__all__ = ("Self", "TypeAlias", "TypeAliasType")
+    NoneType = type(None)
+
+
+__all__ = ("NoneType", "Self", "TypeAlias", "TypeIs", "TypeVarTuple", "Unpack")

jsonlogic/core.py

@@ -1,3 +1,7 @@
+"""Base structures of the library. The two classes defined, :class:`Operator` and :class:`JSONLogicExpression`,
+can be extended to provide extra functionality.
+"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -6,13 +10,15 @@ from typing import TYPE_CHECKING, Any
 
 from ._compat import Self, TypeAlias
 from .json_schema.types import AnyType, JSONSchemaType
-from .typing import JSON, JSONLogicPrimitive, OperatorArgument
+from .typing import JSON, JSONLogicPrimitive, JSONObject, OperatorArgument
 
 if TYPE_CHECKING:
-    # This is a hack to make pyright think `TypeAlias` comes from `typing`
+    # This is a hack to make Pylance think `TypeAlias` comes from `typing`
     from typing import TypeAlias
 
+    from .evaluation import EvaluationContext
     from .registry import OperatorRegistry
+    from .typechecking import TypecheckContext
 
 
 @dataclass
@@ -31,43 +37,96 @@ class Operator(ABC):
     @classmethod
     @abstractmethod
     def from_expression(cls, operator: str, arguments: list[OperatorArgument]) -> Self:
-        """Return an instance of the operator from the list of provided arguments."""
+        """Return an instance of the operator from the list of provided arguments.
+
+        Args:
+            operator: The ID of the operator, as provided by the :class:`~jsonlogic.registry.OperatorRegistry`.
+            arguments: The list of the arguments for this operator. Subclasses are responsible
+                for checking the correct number of arguments and optionally the types.
+        """
 
     @abstractmethod
-    def apply(self, data: JSON) -> Any:
-        pass
+    def evaluate(self, context: EvaluationContext) -> Any:
+        """Evaluate the operator with the provided data."""
 
-    def typecheck(self, data_schema: dict[str, Any]) -> JSONSchemaType:
+    def typecheck(self, context: TypecheckContext) -> JSONSchemaType:
         """Typecheck the operator (and all children) given the data schema."""
 
         return AnyType()
 
 
-NormalizedExpression: TypeAlias = "dict[str, list[JSONLogicExpression]]"
+class JSONLogicSyntaxError(Exception):
+    """A syntax error when building an operator tree from a :class:`JSONLogicExpression`."""
+
+    def __init__(self, message: str, /) -> None:
+        self.message = message
+
+
+ExprArgument: TypeAlias = "JSONLogicPrimitive | JSONLogicExpression | list[ExprArgument]"
+
+NormalizedExpression: TypeAlias = "dict[str, list[ExprArgument]]"
 
 
 @dataclass
 class JSONLogicExpression:
-    expression: JSONLogicPrimitive | NormalizedExpression
+    """A parsed and normalized JSON Logic expression.
+
+    The underlying structure of an expression is a single item dictionary,
+    mapping the operator key to a list of arguments.
+
+    All JSON Logic expressions should be instantiated using the :meth:`from_json` constructor::
+
+        expr = JSONLogicExpression.from_json({"op": ...})
+    """
+
+    expression: NormalizedExpression
+
+    @classmethod
+    def _parse_impl(cls, json: JSON) -> ExprArgument:
+        if isinstance(json, dict):
+            return cls.from_json(json)
+        if isinstance(json, list):
+            return [cls._parse_impl(s) for s in json]
+        return json
 
     @classmethod
-    def from_json(cls, json: JSON) -> Self:  # TODO disallow list?
+    def from_json(cls, json: JSONObject) -> Self:
+        """Build a JSON Logic expression from JSON data.
+
+        Operator arguments are recursively normalized to a :class:`list`::
+
+            expr = JSONLogicExpression.from_json({"var": "varname"})
+            assert expr.expression == {"var": ["varname"]}
+        """
         if not isinstance(json, dict):
-            return cls(expression=json)
+            raise ValueError("The root node of the expression must be a dict")
 
         operator, op_args = next(iter(json.items()))
         if not isinstance(op_args, list):
             op_args = [op_args]
 
-        sub_expressions = [cls.from_json(op_arg) for op_arg in op_args]
+        return cls({operator: [cls._parse_impl(arg) for arg in op_args]})
+
+    def _as_op_impl(self, op_arg: ExprArgument, operator_registry: OperatorRegistry) -> OperatorArgument:
+        if isinstance(op_arg, JSONLogicExpression):
+            return op_arg.as_operator_tree(operator_registry)
+        if isinstance(op_arg, list):
+            return [self._as_op_impl(sub_arg, operator_registry) for sub_arg in op_arg]
+        return op_arg
+
+    def as_operator_tree(self, operator_registry: OperatorRegistry) -> Operator:
+        """Return a recursive tree of operators, using the provided registry as a reference.
 
-        return cls({operator: sub_expressions})
+        Args:
+            operator_registry: The registry to use to resolve operator IDs.
 
-    def as_operator_tree(self, operator_registry: OperatorRegistry) -> JSONLogicPrimitive | Operator:
+        Returns:
+            An :class:`Operator` instance.
+        """
         if not isinstance(self.expression, dict):
             return self.expression
 
         op_id, op_args = next(iter(self.expression.items()))
         OperatorCls = operator_registry.get(op_id)
 
-        return OperatorCls.from_expression(op_id, [op_arg.as_operator_tree(operator_registry) for op_arg in op_args])
+        return OperatorCls.from_expression(op_id, [self._as_op_impl(op_arg, operator_registry) for op_arg in op_args])

jsonlogic/evaluation/__init__.py

@@ -0,0 +1,5 @@
+from .evaluation_context import EvaluationContext
+from .evaluation_settings import EvaluationSettings
+from .utils import evaluate, get_value
+
+__all__ = ("EvaluationContext", "EvaluationSettings", "evaluate", "get_value")

jsonlogic/evaluation/evaluation_context.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any, Literal, overload
+
+from jsonlogic.json_schema import cast_from_schema
+from jsonlogic.resolving import resolve_data, resolve_json_schema
+from jsonlogic.typing import JSON
+from jsonlogic.utils import DataStack
+
+from .evaluation_settings import EvaluationSettings, EvaluationSettingsDict
+
+
+class EvaluationContext:
+    """A context object used when evaluating operators.
+
+    When evaluating an :class:`~jsonlogic.core.Operator`, an instance of this
+    class should be used.
+
+    .. code-block:: pycon
+
+        >>> expr = JSONLogicExpression.from_json({"var": "/a_date"})
+        >>> root_op = expr.as_operator_tree(operator_registry)
+        >>> context = EvaluationContext(
+        ...     data={"a_date": "1970-01-01"},
+        ...     data_schema={
+        ...         "type": "object",
+        ...         "properties": {
+        ...             "a_date": {"type": "string", "format": "date"},
+        ...         },
+        ...     },
+        ... )
+        >>> root_op.evaluate(context)
+        datetime.date(1970, 1, 1)
+
+    Args:
+        root_data: The root data available during evaluation.
+        data_schema: The matching JSON Schema describing the root data. This should be the same JSON Schema
+            used during typechecking (see :paramref:`~jsonlogic.typechecking.TypecheckContext.root_data_schema`).
+        settings: Settings to be used when evaluating an :class:`~jsonlogic.core.Operator`.
+            See :class:`EvaluationSettings` for the available settings and default values.
+    """
+
+    def __init__(
+        self, root_data: JSON, data_schema: dict[str, Any] | None = None, settings: EvaluationSettingsDict | None = None
+    ) -> None:
+        self.data_stack = DataStack((root_data, data_schema))
+        self.settings = EvaluationSettings.from_dict(settings) if settings is not None else EvaluationSettings()
+
+    @overload
+    def resolve_variable(self, reference: str, *, bare: Literal[True]) -> JSON: ...
+
+    @overload
+    def resolve_variable(self, reference: str, *, bare: Literal[False] = ...) -> Any: ...
+
+    def resolve_variable(self, reference: str, *, bare: bool = False) -> JSON | Any:
+        """Resolve a variable given the string reference pointing to it.
+
+        The format of the reference should match the reference parser defined
+        in the :class:`EvaluationSettings`.
+
+        Args:
+            reference: The string reference of the variable.
+            bare: Whether the resolved value should be casted to a specific Python
+                type according to the matching JSON Schema. Note that this will only
+                be possible if a :paramref:`~EvaluationContext.data_schema` was provided.
+        """
+        parsed_reference, scope = self.settings.reference_parser(reference)
+        root_data, root_schema = self.data_stack.get(scope)
+        bare_value = resolve_data(parsed_reference, root_data)
+        if bare or root_schema is None:
+            return bare_value
+
+        schema = resolve_json_schema(parsed_reference, root_schema)
+        return cast_from_schema(bare_value, schema, self.settings.variable_casts)

jsonlogic/evaluation/evaluation_settings.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Callable, TypedDict
+
+from jsonlogic._compat import Self
+from jsonlogic.resolving import PointerReferenceParser, ReferenceParser
+
+
+def _d_variable_casts() -> dict[str, Callable[[str], Any]]:
+    return {
+        "date": date.fromisoformat,
+        "date-time": datetime.fromisoformat,
+    }
+
+
+@dataclass
+class EvaluationSettings:
+    """Settings used when evaluating an :class:`~jsonlogic.core.Operator`."""
+
+    reference_parser: ReferenceParser = field(default_factory=PointerReferenceParser)
+    """A reference parser instance to use when resolving variables.
+
+    Default: :class:`~jsonlogic.resolving.PointerReferenceParser`.
+    """
+
+    variable_casts: dict[str, Callable[[str], Any]] = field(default_factory=_d_variable_casts)
+    """A mapping between `JSON Schema formats`_ and their corresponding conversion callable.
+
+    When an operator reads variables from the provided data (such as the ``"var"`` operator),
+    such variables of type :class:`str` may be converted to a specific Python type if
+    the corresponding JSON Schema of the data was provided during evaluation.
+
+    This setting is analogous to the :attr:`~jsonlogic.typechecking.TypecheckSettings.variable_casts`
+    configuration of the :class:`~jsonlogic.typechecking.TypecheckSettings` class.
+
+    Default: :python:`{"date": date.fromisoformat, "date-time": datetime.fromisoformat}`.
+
+    .. _JSON Schema formats: https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
+    """
+
+    literal_casts: list[Callable[[str], Any]] = field(default_factory=list)
+    """A list of conversion callables to try when encountering a literal string value during evaluation.
+
+    When a literal string value is encountered in a JSON Logic expression, it might be
+    beneficial to convert it to a specific Python type.
+
+    This setting is analogous to the :attr:`~jsonlogic.typechecking.TypecheckSettings.literal_casts`
+    configuration of the :class:`~jsonlogic.typechecking.TypecheckSettings` class.
+
+    Default: :python:`[]` (no cast).
+
+    .. warning::
+
+        The order in which the conversion callables are defined matters. Each
+        callable will be applied one after the other until no exception is raised.
+    """
+
+    @classmethod
+    def from_dict(cls, dct: EvaluationSettingsDict, /) -> Self:
+        return cls(**dct)
+
+
+class EvaluationSettingsDict(TypedDict, total=False):
+    """Settings used when evaluating an :class:`~jsonlogic.core.Operator`."""
+
+    reference_parser: ReferenceParser
+    """A reference parser instance to use when resolving variables.
+
+    Default: :class:`~jsonlogic.resolving.PointerReferenceParser`.
+    """
+
+    variable_casts: dict[str, Callable[[str], Any]]
+    """A mapping between `JSON Schema formats`_ and their corresponding conversion callable.
+
+    When an operator reads variables from the provided data (such as the ``"var"`` operator),
+    such variables of type :class:`str` may be converted to a specific Python type if
+    the corresponding JSON Schema of the data was provided during evaluation.
+
+    This setting is analogous to the :attr:`~jsonlogic.typechecking.TypecheckSettings.variable_casts`
+    configuration of the :class:`~jsonlogic.typechecking.TypecheckSettings` class.
+
+    Default: :python:`{"date": date.fromisoformat, "date-time": datetime.fromisoformat}`.
+
+    .. _JSON Schema formats: https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
+    """
+
+    literal_casts: list[Callable[[str], Any]]
+    """A list of conversion callables to try when encountering a literal string value during evaluation.
+
+    When a literal string value is encountered in a JSON Logic expression, it might be
+    beneficial to convert it to a specific Python type.
+
+    This setting is analogous to the :attr:`~jsonlogic.typechecking.TypecheckSettings.literal_casts`
+    configuration of the :class:`~jsonlogic.typechecking.TypecheckSettings` class.
+
+    Default: :python:`[]` (no cast).
+
+    .. warning::
+
+        The order in which the conversion callables are defined matters. Each
+        callable will be applied one after the other until no exception is raised.
+    """

jsonlogic/evaluation/utils.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from jsonlogic.core import Operator
+from jsonlogic.typing import JSON, JSONLogicPrimitive, OperatorArgument
+
+from .evaluation_context import EvaluationContext
+from .evaluation_settings import EvaluationSettingsDict
+
+
+def evaluate(
+    operator: Operator, data: JSON, data_schema: dict[str, Any] | None, settings: EvaluationSettingsDict | None = None
+) -> Any:
+    """Helper function to evaluate an :class:`~jsonlogic.core.Operator`.
+
+    Args:
+        operator: The operator to evaluate.
+        data: The root data available during evaluation.
+        data_schema: The matching JSON Schema describing the root data. This should be the same JSON Schema
+            used during typechecking (see :paramref:`~jsonlogic.typechecking.TypecheckContext.root_data_schema`).
+        settings: Settings to be used when evaluating an :class:`~jsonlogic.core.Operator`.
+            See :class:`EvaluationSettings` for the available settings and default values.
+    Returns:
+        The evaluated value.
+    """
+    context = EvaluationContext(data, data_schema, settings)
+    return operator.evaluate(context)
+
+
+# Function analogous to :func:`jsonlogic.json_schema.from_value`
+def _cast_value(value: JSONLogicPrimitive, literal_casts: list[Callable[[str], Any]]) -> Any:
+    if isinstance(value, str):
+        for func in literal_casts:
+            try:
+                casted_value = func(value)
+            except Exception:
+                pass
+            else:
+                return casted_value
+
+    if not isinstance(value, list):
+        return value
+
+    return [_cast_value(subval, literal_casts) for subval in value]
+
+
+def get_value(obj: OperatorArgument, context: EvaluationContext) -> Any:
+    """Get the value of an operator argument.
+
+    Args:
+        obj: the object to evaluate. If this is an :class:`~jsonlogic.core.Operator`,
+            it is evaluated and the value is returned. Otherwise, it must be a
+            :data:`~jsonlogic.typing.JSONLogicPrimitive`, and the type is inferred from
+            the actual value according to the :attr:`~TypecheckSettings.literal_casts` setting.
+        context: The typecheck context.
+    """
+    if isinstance(obj, Operator):
+        return obj.evaluate(context)
+    if isinstance(obj, list):
+        return [get_value(sub_obj, context) for sub_obj in obj]
+    return _cast_value(obj, context.settings.literal_casts)

jsonlogic/json_schema/__init__.py

@@ -1,77 +1,184 @@
-from datetime import date, datetime
-from types import NoneType
+from __future__ import annotations
+
 from typing import Any, Callable, cast
 
-from jsonlogic.typing import JSONLogicPrimitive
+from jsonlogic._compat import NoneType, TypeIs
+from jsonlogic.typing import JSON, JSONLogicPrimitive
 
 from .types import (
     AnyType,
+    ArrayType,
     BooleanType,
-    DatetimeType,
-    DateType,
     IntegerType,
     JSONSchemaType,
     NullType,
     NumberType,
     StringType,
+    TupleType,
+    UnionType,
+)
+
+__all__ = (
+    "as_json_schema",
+    "cast_from_schema",
+    "from_json_schema",
+    "from_value",
 )
 
-_VALUE_TYPE_MAP: dict[type[Any], JSONSchemaType] = {
-    bool: BooleanType(),
-    float: NumberType(),
-    int: IntegerType(),
-    NoneType: NullType(),
+_VALUE_TYPE_MAP: dict[type[Any], type[JSONSchemaType]] = {
+    bool: BooleanType,
+    float: NumberType,
+    int: IntegerType,
+    NoneType: NullType,
+}
+
+_PRIMITIVES_TYPE_MAP: dict[str, type[JSONSchemaType]] = {
+    "boolean": BooleanType,
+    "number": NumberType,
+    "integer": IntegerType,
+    "null": NullType,
 }
 
-_VALUE_FORMAT_MAP: dict[Callable[[str], Any], JSONSchemaType] = {
-    datetime.fromisoformat: DatetimeType(),
-    date.fromisoformat: DateType(),
+_R_PRIMITIVES_TYPE_MAP: dict[type[JSONSchemaType], str] = {
+    **{v: k for k, v in _PRIMITIVES_TYPE_MAP.items()},
+    StringType: "string",
 }
 
 
-def from_value(value: JSONLogicPrimitive) -> JSONSchemaType:
-    if type(value) in _VALUE_TYPE_MAP:
-        return _VALUE_TYPE_MAP[type(value)]
+# Defined purely for type checking purposes:
+def _is_primitive_not_str(value: object) -> TypeIs[bool | float | None]:
+    return type(value) in _VALUE_TYPE_MAP
+
 
+def from_value(
+    value: JSONLogicPrimitive, literal_casts: dict[Callable[[str], Any], type[JSONSchemaType]]
+) -> JSONSchemaType:
     if isinstance(value, str):
-        for func, js_type in _VALUE_FORMAT_MAP.items():
+        for func, js_type in literal_casts.items():
             try:
                 func(value)
             except Exception:
                 pass
             else:
-                return js_type
+                return js_type()
 
         return StringType()
 
-    return AnyType()
+    if _is_primitive_not_str(value):
+        return _VALUE_TYPE_MAP[type(value)]()
 
+    # A design decision had to be made: we infer arrays as arrays and not as tuples,
+    # even if types are different.
+    if value:
+        return ArrayType(UnionType(*(from_value(val, literal_casts) for val in value)))
 
-_TYPE_MAP: dict[str, JSONSchemaType] = {
-    "boolean": BooleanType(),
-    "number": NumberType(),
-    "integer": IntegerType(),
-    "null": NullType(),
-}
+    # Empty array: can't infer type
+    return ArrayType(AnyType())
 
-_FORMAT_MAP: dict[str, JSONSchemaType] = {
-    "date-time": DatetimeType(),
-    "date": DateType(),
-}
 
+def from_json_schema(json_schema: dict[str, Any], variable_casts: dict[str, type[JSONSchemaType]]) -> JSONSchemaType:
+    js_types = cast("list[str] | str | None", json_schema.get("type"))
+    if js_types is None:
+        return AnyType()
 
-def from_json_schema(json_schema: dict[str, Any]) -> JSONSchemaType:
-    # TODO support for unions
-    js_type = cast(str | None, json_schema.get("type"))
-    if js_type in _TYPE_MAP:
-        return _TYPE_MAP[js_type]
+    if not isinstance(js_types, list):
+        js_types = [js_types]
 
-    if js_type == "string":
-        format = cast(str | None, json_schema.get("format"))
+    def _from_type(js_type: str, json_schema: dict[str, Any]) -> JSONSchemaType:
+        if js_type in _PRIMITIVES_TYPE_MAP:
+            return _PRIMITIVES_TYPE_MAP[js_type]()
 
-        if format in _FORMAT_MAP:
-            return _FORMAT_MAP[format]
+        if js_type == "string":
+            format = cast("str | None", json_schema.get("format"))
+            if format in variable_casts:
+                return variable_casts[format]()
 
-        return StringType()
+            return StringType()
+
+        if js_type == "array":
+            items_type = cast("dict[str, Any] | None", json_schema.get("items"))
+            if items_type is not None:
+                return ArrayType(from_json_schema(items_type, variable_casts))
+
+            prefix_items = cast("list[dict[str, Any]] | None", json_schema.get("prefixItems"))
+            min_items = cast("int | None", json_schema.get("minItems"))
+            max_items = cast("int | None", json_schema.get("maxItems"))
+            if prefix_items is not None and min_items is not None and min_items == max_items:
+                return TupleType(tuple(from_json_schema(item, variable_casts) for item in prefix_items))
+
+            return ArrayType(AnyType())
+
+        return AnyType()
+
+    return UnionType(*(_from_type(js_type, json_schema) for js_type in js_types))
+
+
+def as_json_schema(type: JSONSchemaType, variable_casts: dict[str, type[JSONSchemaType]]) -> dict[str, Any]:
+    type_class = type.__class__
+    if type_class in _R_PRIMITIVES_TYPE_MAP:
+        return {"type": _R_PRIMITIVES_TYPE_MAP[type_class]}
+
+    if isinstance(type, AnyType):
+        return {}
+
+    if isinstance(type, UnionType):
+        sub_schemas = [as_json_schema(subtype, variable_casts) for subtype in type.types]
+        types = [
+            sub_schema.pop("type")  # UnionTypes can't have any, so `"type"` is guaranteed to be present
+            for sub_schema in sub_schemas
+        ]
+        schema = {
+            "type": types[0] if len(types) == 1 else types,
+        }
+        for sub_schema in sub_schemas:
+            schema.update(sub_schema)
+        return schema
+
+    if isinstance(type, ArrayType):
+        items_type = as_json_schema(type.elements_type, variable_casts)
+        if items_type:
+            return {"type": "array", "items": items_type}
+        return {"type": "array"}
+
+    if isinstance(type, TupleType):
+        return {
+            "type": "array",
+            "minItems": len(type.tuple_types),
+            "maxItems": len(type.tuple_types),
+            "prefixItems": [as_json_schema(subtype, variable_casts) for subtype in type.tuple_types],
+        }
+
+    r_variable_casts = {v: k for k, v in variable_casts.items()}
+
+    if type_class in r_variable_casts:
+        return {"type": "string", "format": r_variable_casts[type_class]}
+
+    raise RuntimeError(f"Unable to determine JSON Schema for type {type}")
+
+
+def cast_from_schema(value: JSON, json_schema: dict[str, Any], variable_casts: dict[str, Callable[[str], Any]]) -> Any:
+    js_types = cast("list[str] | str | None", json_schema.get("type"))
+    if js_types is None:
+        return value
+
+    if not isinstance(js_types, list):
+        js_types = [js_types]
+
+    if (
+        isinstance(value, str)
+        and "string" in js_types
+        and (cast_func := variable_casts.get(json_schema.get("format")))  # type: ignore
+    ):  # fmt: skip
+        return cast_func(value)
+
+    if isinstance(value, list) and "array" in js_types:
+        items_type = cast("dict[str, Any] | None", json_schema.get("items"))
+        if items_type is not None:
+            return [cast_from_schema(val, items_type, variable_casts) for val in value]
+
+        prefix_items = cast("list[dict[str, Any]] | None", json_schema.get("prefixItems"))
+        if prefix_items is not None:  # TODO check for min/maxItems?
+            # TODO return a tuple instead? Needs decision
+            return [cast_from_schema(val, item_type, variable_casts) for val, item_type in zip(value, prefix_items)]
 
-    return AnyType()
+    return value