jsonology 0.1.0__py3-none-any.whl

jsonology/__init__.py

@@ -0,0 +1,6 @@
+"""jsonology — evaluate a strict, tiny JSON DSL against a ``$``-rooted context object."""
+
+from jsonology.core import EvaluationError, ExpressionSyntaxError, evaluate
+
+__all__ = ["EvaluationError", "ExpressionSyntaxError", "evaluate"]
+__version__ = "0.1.0"

jsonology/core.py

@@ -0,0 +1,232 @@
+"""Core evaluator for the jsonology expression DSL.
+
+Implements the confirmed spec (see SPEC.md): a strict, tiny JSON DSL with
+``$``-rooted paths, six comparisons, a lazy ``if``, and short-circuiting
+``and``/``or``/``not``. Two exceptions, and only two: ``ExpressionSyntaxError``
+for malformed expressions, ``EvaluationError`` for undefined operations.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from typing import Any
+
+__all__ = ["EvaluationError", "ExpressionSyntaxError", "evaluate"]
+
+
+class ExpressionSyntaxError(Exception):
+    """The expression is not well-formed: structure, arity, unknown operator, bad JSON text."""
+
+
+class EvaluationError(Exception):
+    """The expression is well-formed but an operation is undefined (e.g. cross-type ordering)."""
+
+
+_COMPARISONS = {"==", "!=", "<", "<=", ">", ">="}
+_LOGICAL = {"if", "and", "or", "not"}
+_OPERATORS = _COMPARISONS | _LOGICAL
+
+# operator -> (minimum arity, maximum arity); math.inf means "no maximum"
+_ARITY: dict[str, tuple[int, float]] = {op: (2, 2) for op in _COMPARISONS}
+_ARITY.update({"if": (3, 3), "not": (1, 1), "and": (1, math.inf), "or": (1, math.inf)})
+
+
+def evaluate(expression: Any, data: Any) -> Any:
+    """Evaluate a jsonology expression against ``data``.
+
+    ``expression`` may be an already-parsed Python object or a raw JSON string.
+    A string that is ``"$"`` or starts with ``"$."`` is a path, not JSON text;
+    any other string is parsed as JSON, and a parse failure raises
+    :class:`ExpressionSyntaxError`.
+
+    Neither ``expression`` nor ``data`` is mutated; the function is stateless
+    and thread-safe. Raises :class:`ExpressionSyntaxError` for malformed
+    expressions and :class:`EvaluationError` for undefined operations
+    (ordering across types, with null, or between booleans).
+    """
+    if isinstance(expression, str) and expression != "$" and not expression.startswith("$."):
+        try:
+            expression = json.loads(expression)
+        except ValueError as exc:
+            raise ExpressionSyntaxError(f"expression string is not valid JSON: {exc}") from exc
+    try:
+        return _eval(expression, data, "$")
+    except RecursionError:
+        raise ExpressionSyntaxError("expression too deeply nested") from None
+
+
+def _eval(node: Any, data: Any, path: str) -> Any:
+    """Recursively evaluate one expression node, located at ``path`` in the tree."""
+    if node is None or isinstance(node, (bool, int, float)):
+        return node
+    if isinstance(node, str):
+        return _resolve_path(node, data) if node == "$" or node.startswith("$.") else node
+    if isinstance(node, Mapping):
+        if len(node) != 1:
+            raise ExpressionSyntaxError(
+                f"operator object must have exactly one key, got {len(node)}: "
+                f"{_snippet(node)} (at {path})"
+            )
+        op, args = next(iter(node.items()))
+        if op not in _OPERATORS:
+            raise ExpressionSyntaxError(f"unknown operator {op!r} (at {path})")
+        if not isinstance(args, (list, tuple)):
+            raise ExpressionSyntaxError(
+                f"arguments of {op!r} must be a list, got {_snippet(args)} (at {path})"
+            )
+        low, high = _ARITY[op]
+        if not low <= len(args) <= high:
+            expectation = f"exactly {low}" if low == high else f"at least {low}"
+            raise ExpressionSyntaxError(
+                f"operator {op!r} takes {expectation} argument(s), got {len(args)} (at {path})"
+            )
+        if op in _COMPARISONS:
+            left = _eval(args[0], data, f"{path}.{op}[0]")
+            right = _eval(args[1], data, f"{path}.{op}[1]")
+            return _compare(op, left, right, f"{path}.{op}")
+        if op == "if":
+            branch = 1 if _truthy(_eval(args[0], data, f"{path}.if[0]")) else 2
+            return _eval(args[branch], data, f"{path}.if[{branch}]")
+        if op in ("and", "or"):
+            want_truthy = op == "or"
+            for i, arg in enumerate(args):
+                if _truthy(_eval(arg, data, f"{path}.{op}[{i}]")) is want_truthy:
+                    return want_truthy
+            return not want_truthy
+        return not _truthy(_eval(args[0], data, f"{path}.not[0]"))
+    raise ExpressionSyntaxError(
+        f"expression must be a JSON scalar, a '$.'-prefixed path string, or a "
+        f"single-key operator object, got {_snippet(node)} (at {path})"
+    )
+
+
+def _resolve_path(path: str, data: Any) -> Any:
+    """Resolve a ``$``-rooted path; any missing segment evaluates to None."""
+    if path == "$":
+        return data
+    current = data
+    for segment in path[2:].split("."):
+        if isinstance(current, Mapping):
+            if segment in current:
+                current = current[segment]
+            else:
+                return None
+        elif isinstance(current, (list, tuple)):
+            # isdecimal, not isdigit: isdigit() admits characters int() rejects
+            # (e.g. superscript '²'), which would crash. Decimal digits are
+            # exactly the segments int() can parse.
+            if segment.isdecimal() and int(segment) < len(current):
+                current = current[int(segment)]
+            else:
+                return None
+        else:
+            return None
+    return current
+
+
+def _truthy(value: Any) -> bool:
+    """Python-style truthiness: false, null, 0, "", [], {} are falsy; else truthy."""
+    if value is None or isinstance(value, bool):
+        return bool(value)
+    if isinstance(value, (int, float)):
+        return value != 0
+    if isinstance(value, (str, list, tuple, Mapping)):
+        return len(value) > 0
+    return bool(value)
+
+
+def _compare(op: str, left: Any, right: Any, path: str) -> bool:
+    if op == "==":
+        return _equal(left, right)
+    if op == "!=":
+        return not _equal(left, right)
+    order = _ordered(left, right, op, path)
+    if op == "<":
+        return order < 0
+    if op == "<=":
+        return order <= 0
+    if op == ">":
+        return order > 0
+    return order >= 0
+
+
+def _ordered(left: Any, right: Any, op: str, path: str) -> int:
+    """Return -1/0/1 for two numbers or two strings; raise for anything else."""
+    if left is None or right is None or isinstance(left, bool) or isinstance(right, bool):
+        raise EvaluationError(
+            f"operator {op!r} is undefined for {_snippet(left)} and {_snippet(right)}: "
+            f"ordering is undefined for booleans and null (at {path})"
+        )
+    both_numbers = isinstance(left, (int, float)) and isinstance(right, (int, float))
+    both_strings = isinstance(left, str) and isinstance(right, str)
+    # Out-of-contract, same-type pairs (e.g. two datetimes) fall through to
+    # Python semantics. In-contract families that Python would happily order
+    # (lists compare lexicographically!) must NOT slip through: arrays,
+    # objects, booleans and null always raise.
+    both_other = (
+        _family(left) == "other" and _family(right) == "other" and type(left) is type(right)
+    )
+    if not (both_numbers or both_strings or both_other):
+        raise EvaluationError(
+            f"operator {op!r} is undefined for {_snippet(left)} and {_snippet(right)}: "
+            f"ordering requires two numbers or two strings (at {path})"
+        )
+    try:
+        if left < right:
+            return -1
+        if right < left:
+            return 1
+        return 0
+    except TypeError as exc:
+        raise EvaluationError(
+            f"operator {op!r} is undefined for {_snippet(left)} and {_snippet(right)}: "
+            f"{exc} (at {path})"
+        ) from exc
+
+
+def _family(value: Any) -> str:
+    """The JSON type family of a value; ``bool`` is deliberately not ``number``."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, (list, tuple)):
+        return "array"
+    if isinstance(value, Mapping):
+        return "object"
+    return "other"
+
+
+def _equal(left: Any, right: Any) -> bool:
+    """Strict, deep, structural equality; cross-type (incl. bool vs number) is False."""
+    left_family, right_family = _family(left), _family(right)
+    if left_family != right_family:
+        return False
+    if left_family == "array":
+        return len(left) == len(right) and all(
+            _equal(a, b) for a, b in zip(left, right, strict=True)
+        )
+    if left_family == "object":
+        return left.keys() == right.keys() and all(_equal(v, right[k]) for k, v in left.items())
+    if left_family == "other":
+        return type(left) is type(right) and bool(left == right)
+    return bool(left == right)
+
+
+def _snippet(value: Any, limit: int = 40) -> str:
+    """A short, crash-proof rendering of a value for error messages."""
+    try:
+        text = json.dumps(value, default=repr)
+    except RecursionError:
+        return "<deeply nested value>"
+    except (TypeError, ValueError):
+        text = repr(value)
+    if len(text) > limit:
+        text = text[: limit - 1] + "…"
+    return text

jsonology-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: jsonology
+Version: 0.1.0
+Summary: Evaluate a strict, tiny JSON DSL (comparisons, if, and/or/not) against a $-rooted context object
+Author: The jsonology authors
+License: MIT
+License-File: LICENSE
+Keywords: dsl,evaluator,expression,json,jsonlogic,rules
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jsonology
+
+Evaluate a strict, tiny JSON DSL against a context object.
+
+```python
+>>> from jsonology import evaluate
+>>> evaluate({"==": ["$.operation", "edit"]}, {"operation": "edit"})
+True
+>>> evaluate({"if": [{"==": ["$.operation", "edit"]}, "an edit!", "not an edit"]},
+...         {"operation": "delete"})
+'not an edit'
+```
+
+Expressions are JSON values, authored by trusted teammates, stored in rules or
+config. `jsonology` interprets them strictly and errors loudly. Zero runtime
+dependencies. Python ≥ 3.10, fully typed.
+
+## Install
+
+```bash
+pip install jsonology
+```
+
+## The language
+
+An **expression** is one of:
+
+- a JSON scalar — a literal (`5`, `5.5`, `"edit"`, `true`, `false`, `null`)
+- a string starting with `$.` — a path into the context
+- an operator object `{op: [args...]}` — where every argument is itself an expression
+
+### Operators
+
+| Operator | Arity | Semantics |
+| --- | --- | --- |
+| `==`, `!=` | exactly 2 | strict equality, no coercion |
+| `<`, `<=`, `>`, `>=` | exactly 2 | ordering: two numbers or two strings only |
+| `if` | exactly 3 | `[condition, if_true, if_false]`, **lazy** |
+| `and`, `or` | 1 or more | short-circuit, return strict booleans |
+| `not` | exactly 1 | negation of truthiness |
+
+Operator objects must have exactly one key. Bare lists are not expressions.
+Unknown operators are rejected with an error naming them.
+
+### Paths
+
+- `$.user.address.city` — dot-nested object access
+- `$.items.0` — numeric segments index lists (no negative indices)
+- a missing path evaluates to `null`, so `{"==": ["$.nickname", null]}` is the "is unset" idiom
+- `$` alone is the entire context (which may itself be a list)
+
+### Truthiness
+
+`if` conditions and `and`/`or`/`not` operands are interpreted Python-style:
+
+| Value | Truthy? |
+| --- | --- |
+| `false`, `null` | no |
+| `0` | no |
+| `""` | no |
+| `[]`, `{}` | no |
+| everything else | yes |
+
+### Strict typing
+
+- No coercion: `{"==": ["5", 5]}` is `false`.
+- `int` and `float` unify: `5 == 5.0` is `true`.
+- `bool` is its own type: `true == 1` is `false`, and ordering booleans is an error.
+- Cross-type equality is always decided, never an error: `{"==": [1, "1"]}` → `false`.
+- Ordering is only defined for two numbers or two strings; anything else —
+  cross-type, `null` on either side, booleans, lists — raises `EvaluationError`.
+  Note `{"<": ["$.missing", 5]}` raises, because a missing path is `null`.
+- Strings order lexicographically: `{"<": ["10", "9"]}` is `true`.
+- Equality is deep and structural over arrays and objects.
+
+### Laziness and short-circuiting
+
+`if` evaluates only the taken branch. `and` stops at the first falsy operand,
+`or` at the first truthy one — later operands are never evaluated (or errored):
+
+```python
+evaluate({"and": [False, {"<": [None, 1]}]}, {})   # False — the broken branch never runs
+```
+
+Because of this laziness, syntax errors inside dead branches stay silent —
+`evaluate({"if": [True, 1, {"frobnicate": [1]}]}, {})` is `1`.
+
+## API
+
+```python
+evaluate(expression, data) -> Any
+```
+
+- `expression`: an already-parsed Python object **or** a raw JSON string.
+  A string that is `"$"` or starts with `"$."` is treated as a path, not JSON
+  text; any other string is parsed as JSON and failures raise
+  `ExpressionSyntaxError`. There is **no escape hatch** for literal strings
+  that start with `$.` — they are always paths.
+- `data`: the context object (a mapping, or a list if your paths start `$.0` …).
+- Pure, stateless, thread-safe: neither `expression` nor `data` is mutated.
+
+Two exceptions, and only two:
+
+| Exception | Raised for |
+| --- | --- |
+| `ExpressionSyntaxError` | malformed DSL: structure, arity, unknown operator, invalid JSON text, nesting too deep |
+| `EvaluationError` | undefined operation during evaluation (ordering rules above) |
+
+Error messages name the offending operator and locate the failing
+subexpression within the expression tree, e.g. `$.if[0].==[1]` — "argument 1
+of the `==` at argument 0 of the `if`".
+
+```python
+>>> from jsonology import evaluate, ExpressionSyntaxError
+>>> try:
+...     evaluate('{"if": [{"==": ["$.a", {"x": 1, "y": 2}]}, 1, 2]}', {})
+... except ExpressionSyntaxError as e:
+...     print(e)
+operator object must have exactly one key, got 2: {"x": 1, "y": 2} (at $.if[0].==[1])
+```
+
+## Limitations (deliberate, v1)
+
+- No literal escape hatch for strings starting with `$.`.
+- No array or object literals: every operand is a scalar, a path, or a nested
+  operator. `{"==": ["$.tags", ["a", "b"]]}` is a syntax error (compare two
+  paths instead: `{"==": ["$.tags", "$.want"]}`), and an object literal like
+  `{"x": 1}` in operand position fails as an unknown operator `'x'`.
+- Dead `if` branches and short-circuited `and`/`or` operands are never
+  evaluated, so their syntax is not validated.
+- Context keys containing dots cannot be addressed by paths.
+- The contract is JSON types. Non-JSON Python values in `data` (datetime,
+  Decimal, …) are out of contract — same-type pairs fall through to Python
+  semantics, everything else is unspecified. For time comparisons store
+  ISO-8601 strings (lexicographic `<` does the right thing) or epoch integers.
+- No custom operators, no depth or size limits (trusted-input model).
+- No `compile()` step — expressions are interpreted directly; reach for one
+  only if profiling demands it.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+python -m pytest          # 149 cases: table-driven goldens + property-based invariants
+python -m ruff check .
+python -m mypy
+```
+
+The property suite (Hypothesis) checks the contract as invariants: only the
+two documented exceptions ever escape, `==`/ordering obey the algebraic laws
+(reflexivity, symmetry, transitivity, connexity), truthiness matches the
+reference table, path resolution matches an independent reference walk, dead
+branches never evaluate, inputs are never mutated, and JSON-text input agrees
+with object input.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

jsonology-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+jsonology/__init__.py,sha256=k9z_2XqnN-0zn23TWux9JSJElAcFMXbFmWrZVkLP4Ww,259
+jsonology/core.py,sha256=T2LEdqJYXecg46BVuliuM2x5MFSz2nzsNRF1cj98LTU,9147
+jsonology/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jsonology-0.1.0.dist-info/METADATA,sha256=OpLt5JSkzDruGapDO7jIRIraWDEODGLjRw4ug9RZ-co,7059
+jsonology-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jsonology-0.1.0.dist-info/licenses/LICENSE,sha256=84ed0FiUtfdroKBIs9yusK2POq4hk_FqkZS2OyqDi6U,1078
+jsonology-0.1.0.dist-info/RECORD,,

jsonology-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

jsonology-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The jsonology authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.