jeval 0.1.0__py3-none-any.whl

jeval/__init__.py

@@ -0,0 +1,18 @@
+"""Evaluate JSON values against expected checks."""
+
+from jeval.case import Case, Check, CaseError
+from jeval.evaluate import evaluate, get_path, PathError
+from jeval.result import CheckResult, Result
+
+__version__ = "0.1.0"
+__all__ = [
+    "Case",
+    "CaseError",
+    "Check",
+    "CheckResult",
+    "PathError",
+    "Result",
+    "evaluate",
+    "get_path",
+    "__version__",
+]

jeval/__main__.py

@@ -0,0 +1,4 @@
+from jeval.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jeval/case.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+OPS = (
+    "eq",
+    "neq",
+    "contains",
+    "regex",
+    "exists",
+    "type",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "length",
+)
+
+
+class CaseError(ValueError):
+    """Raised when a case or check document is invalid."""
+
+
+@dataclass(frozen=True)
+class Check:
+    """A single assertion against a path in the actual value."""
+
+    op: str
+    path: str = "$"
+    value: Any = None
+    message: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.op not in OPS:
+            raise CaseError(f"unknown check op {self.op!r}; expected one of {', '.join(OPS)}")
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Check:
+        if not isinstance(data, dict):
+            raise CaseError("check must be an object")
+        if "op" not in data:
+            raise CaseError("check is missing 'op'")
+        unknown = set(data) - {"op", "path", "value", "message"}
+        if unknown:
+            raise CaseError(f"check has unknown fields: {', '.join(sorted(unknown))}")
+        return cls(
+            op=str(data["op"]),
+            path=str(data.get("path", "$")),
+            value=data.get("value"),
+            message=data.get("message"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"op": self.op, "path": self.path}
+        if self.value is not None:
+            payload["value"] = self.value
+        if self.message:
+            payload["message"] = self.message
+        return payload
+
+
+@dataclass
+class Case:
+    """One evaluation case: optional expected value plus checks."""
+
+    id: str
+    checks: list[Check] = field(default_factory=list)
+    expected: Any = None
+    actual: Any = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], default_id: str = "case") -> Case:
+        if not isinstance(data, dict):
+            raise CaseError("case must be an object")
+        raw_checks = data.get("checks", [])
+        if raw_checks is None:
+            raw_checks = []
+        if not isinstance(raw_checks, list):
+            raise CaseError("checks must be a list")
+        metadata = data.get("metadata") or {}
+        if not isinstance(metadata, dict):
+            raise CaseError("metadata must be an object")
+        unknown = set(data) - {"id", "checks", "expected", "actual", "metadata", "name"}
+        if unknown:
+            raise CaseError(f"case has unknown fields: {', '.join(sorted(unknown))}")
+        case_id = str(data.get("id") or data.get("name") or default_id)
+        return cls(
+            id=case_id,
+            checks=[Check.from_dict(item) for item in raw_checks],
+            expected=data.get("expected"),
+            actual=data.get("actual"),
+            metadata=metadata,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"id": self.id}
+        if self.checks:
+            payload["checks"] = [check.to_dict() for check in self.checks]
+        if self.expected is not None:
+            payload["expected"] = self.expected
+        if self.actual is not None:
+            payload["actual"] = self.actual
+        if self.metadata:
+            payload["metadata"] = self.metadata
+        return payload

jeval/cli.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, TextIO
+
+from jeval import __version__
+from jeval.case import Case, CaseError
+from jeval.evaluate import evaluate
+from jeval.result import Result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="jeval",
+        description="Evaluate one JSON case against an actual value.",
+    )
+    parser.add_argument("case", help="Path to a JSON case file")
+    parser.add_argument(
+        "--actual",
+        help="Actual JSON value (string). Overrides actual in the case file.",
+    )
+    parser.add_argument(
+        "--actual-file",
+        help="Path to a JSON file with the actual value.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="as_json",
+        help="Print the result as JSON.",
+    )
+    parser.add_argument("--version", action="version", version=f"jeval {__version__}")
+    args = parser.parse_args(argv)
+
+    try:
+        case = _load_case(Path(args.case))
+        actual = _load_actual(args.actual, args.actual_file)
+        result = evaluate(case, actual) if actual is not _UNSET else evaluate(case)
+    except (OSError, json.JSONDecodeError, CaseError, ValueError) as exc:
+        print(f"jeval: {exc}", file=sys.stderr)
+        return 2
+
+    _print_result(result, as_json=args.as_json, stream=sys.stdout)
+    return 0 if result.ok else 1
+
+
+_UNSET = object()
+
+
+def _load_case(path: Path) -> Case:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data, list):
+        raise CaseError("jeval expects a single case object, not a list; use jevals for suites")
+    return Case.from_dict(data, default_id=path.stem)
+
+
+def _load_actual(actual: str | None, actual_file: str | None) -> Any:
+    if actual and actual_file:
+        raise ValueError("use either --actual or --actual-file, not both")
+    if actual is not None:
+        return json.loads(actual)
+    if actual_file is not None:
+        return json.loads(Path(actual_file).read_text(encoding="utf-8"))
+    return _UNSET
+
+
+def _print_result(result: Result, as_json: bool, stream: TextIO) -> None:
+    if as_json:
+        json.dump(result.to_dict(), stream, indent=2)
+        stream.write("\n")
+        return
+    stream.write(result.summary() + "\n")

jeval/evaluate.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from jeval.case import Case, Check
+from jeval.result import CheckResult, Result
+
+_MISSING = object()
+
+_TYPE_NAMES = {
+    "string": str,
+    "str": str,
+    "number": (int, float),
+    "int": int,
+    "float": float,
+    "boolean": bool,
+    "bool": bool,
+    "null": type(None),
+    "array": list,
+    "list": list,
+    "object": dict,
+    "dict": dict,
+}
+
+
+class PathError(KeyError):
+    """Raised when a dotted path cannot be resolved."""
+
+
+def get_path(data: Any, path: str) -> Any:
+    """Return the value at a dotted path (`$`, `$.a.b`, `items.0.name`)."""
+    if path in ("", "$", ".", "$."):
+        return data
+    if path.startswith("$."):
+        path = path[2:]
+    elif path.startswith("$"):
+        path = path[1:]
+    current = data
+    walked: list[str] = []
+    for part in path.split("."):
+        if part == "":
+            continue
+        walked.append(part)
+        current = _step(current, part, ".".join(walked))
+    return current
+
+
+def _step(current: Any, part: str, display: str) -> Any:
+    if isinstance(current, dict):
+        if part not in current:
+            raise PathError(f"path {display!r} not found")
+        return current[part]
+    if isinstance(current, list):
+        if not part.isdigit():
+            raise PathError(f"path {display!r} is not a list index")
+        index = int(part)
+        if index >= len(current):
+            raise PathError(f"path {display!r} is out of range")
+        return current[index]
+    raise PathError(f"path {display!r} cannot be resolved on {type(current).__name__}")
+
+
+def evaluate(case: Case, actual: Any | None = _MISSING) -> Result:
+    """Run a case's checks against `actual` (or `case.actual`)."""
+    if actual is _MISSING:
+        value = case.actual
+    else:
+        value = actual
+
+    checks = list(case.checks)
+    if not checks:
+        checks = [Check(op="eq", path="$", value=case.expected)]
+
+    results = [_run_check(check, value) for check in checks]
+    return Result(case_id=case.id, ok=all(item.ok for item in results), checks=results)
+
+
+def _run_check(check: Check, actual_root: Any) -> CheckResult:
+    try:
+        if check.op == "exists":
+            try:
+                get_path(actual_root, check.path)
+                present = True
+            except PathError:
+                present = False
+            expected = True if check.value is None else bool(check.value)
+            ok = present is expected
+            message = (
+                f"{check.op} {check.path} {'present' if present else 'missing'}"
+                if ok
+                else f"{check.op} {check.path} expected {'present' if expected else 'missing'}, got {'present' if present else 'missing'}"
+            )
+            return CheckResult(
+                op=check.op,
+                path=check.path,
+                ok=ok,
+                message=check.message or message,
+                expected=expected,
+                actual=present,
+            )
+
+        observed = get_path(actual_root, check.path)
+    except PathError as exc:
+        return CheckResult(
+            op=check.op,
+            path=check.path,
+            ok=False,
+            message=check.message or str(exc),
+            expected=check.value,
+            actual=None,
+        )
+
+    ok, detail = _compare(check.op, observed, check.value)
+    if ok:
+        message = detail or f"{check.op} {check.path}"
+    else:
+        message = detail or (
+            f"{check.op} {check.path} expected {check.value!r}, got {observed!r}"
+        )
+    return CheckResult(
+        op=check.op,
+        path=check.path,
+        ok=ok,
+        message=check.message or message,
+        expected=check.value,
+        actual=observed,
+    )
+
+
+def _compare(op: str, observed: Any, expected: Any) -> tuple[bool, str]:
+    if op == "eq":
+        ok = observed == expected
+        return ok, f"eq {observed!r} == {expected!r}" if ok else f"eq expected {expected!r}, got {observed!r}"
+    if op == "neq":
+        ok = observed != expected
+        return ok, f"neq {observed!r} != {expected!r}" if ok else f"neq expected not {expected!r}, got {observed!r}"
+    if op == "contains":
+        ok = _contains(observed, expected)
+        return ok, (
+            f"contains {expected!r} in {observed!r}"
+            if ok
+            else f"contains expected {expected!r} in {observed!r}"
+        )
+    if op == "in":
+        try:
+            ok = observed in expected
+        except TypeError:
+            ok = False
+        return ok, (
+            f"in {observed!r} in {expected!r}"
+            if ok
+            else f"in expected {observed!r} to be in {expected!r}"
+        )
+    if op == "regex":
+        if not isinstance(observed, str) or not isinstance(expected, str):
+            return False, "regex requires string actual and value"
+        ok = re.search(expected, observed) is not None
+        return ok, (
+            f"regex {expected!r} matched {observed!r}"
+            if ok
+            else f"regex {expected!r} did not match {observed!r}"
+        )
+    if op == "type":
+        name = str(expected).lower()
+        if name not in _TYPE_NAMES:
+            return False, f"type unknown type name {expected!r}"
+        ok = isinstance(observed, _TYPE_NAMES[name]) and not (
+            name in {"number", "int"} and isinstance(observed, bool)
+        )
+        if name == "number" and isinstance(observed, bool):
+            ok = False
+        return ok, (
+            f"type {check_type_name(observed)} is {name}"
+            if ok
+            else f"type expected {name}, got {check_type_name(observed)}"
+        )
+    if op in {"gt", "gte", "lt", "lte"}:
+        try:
+            ops = {
+                "gt": observed > expected,
+                "gte": observed >= expected,
+                "lt": observed < expected,
+                "lte": observed <= expected,
+            }
+            ok = bool(ops[op])
+        except TypeError:
+            return False, f"{op} cannot compare {observed!r} with {expected!r}"
+        return ok, (
+            f"{op} {observed!r} {op} {expected!r}"
+            if ok
+            else f"{op} expected {observed!r} {op} {expected!r}"
+        )
+    if op == "length":
+        try:
+            length = len(observed)
+        except TypeError:
+            return False, f"length {type(observed).__name__} has no length"
+        ok = length == expected
+        return ok, (
+            f"length {length} == {expected}"
+            if ok
+            else f"length expected {expected}, got {length}"
+        )
+    return False, f"unknown op {op!r}"
+
+
+def check_type_name(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "float"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _contains(observed: Any, expected: Any) -> bool:
+    if isinstance(observed, str):
+        return str(expected) in observed
+    if isinstance(observed, dict):
+        return expected in observed
+    if isinstance(observed, list):
+        return expected in observed
+    return False

jeval/result.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    op: str
+    path: str
+    ok: bool
+    message: str
+    expected: Any = None
+    actual: Any = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "op": self.op,
+            "path": self.path,
+            "ok": self.ok,
+            "message": self.message,
+            "expected": self.expected,
+            "actual": self.actual,
+        }
+
+
+@dataclass
+class Result:
+    case_id: str
+    ok: bool
+    checks: list[CheckResult] = field(default_factory=list)
+
+    @property
+    def failed(self) -> list[CheckResult]:
+        return [item for item in self.checks if not item.ok]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.case_id,
+            "ok": self.ok,
+            "checks": [item.to_dict() for item in self.checks],
+            "failed": [item.to_dict() for item in self.failed],
+        }
+
+    def summary(self) -> str:
+        if self.ok:
+            return f"PASS  {self.case_id}"
+        lines = [f"FAIL  {self.case_id}"]
+        for item in self.failed:
+            lines.append(f"      {item.message}")
+        return "\n".join(lines)

jeval-0.1.0.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: jeval
+Version: 0.1.0
+Summary: Evaluate JSON values against expected checks.
+Project-URL: Homepage, https://pypi.org/project/jeval/
+Project-URL: Issues, https://pypi.org/project/jeval/
+Author-email: Gabriel Tinoco <gabriel@openlayer.com>
+License-Expression: MIT
+Keywords: assertions,eval,evaluation,json,testing
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# jeval
+
+Evaluate a JSON value against expected checks. One case, one result.
+
+```bash
+pip install jeval
+```
+
+```python
+from jeval import Case, Check, evaluate
+
+result = evaluate(
+    Case(
+        id="order-total",
+        checks=[Check(path="total", op="eq", value=21)],
+    ),
+    actual={"total": 21, "currency": "USD"},
+)
+assert result.ok
+```
+
+```bash
+jeval examples/case.json --actual '{"total": 21}'
+```
+
+A case with no `checks` defaults to deep equality against `expected`.
+
+See **jevals** if you want to run a directory or file of cases and get a score.

jeval-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+jeval/__init__.py,sha256=eq2eYz2yyGQtuj77r1ED-izIZkhgM9W0IMh1N0ysALs,381
+jeval/__main__.py,sha256=ziduDfLD69A0J6gnaIW9iwmk_SgFXUDiXmQOo--CNjw,84
+jeval/case.py,sha256=3LdPFOr67pmZMR7QHxRBYgyEmVCWcHCopTarQTrJMO4,3347
+jeval/cli.py,sha256=Vwn6bbX06yXfTPBdBhNBEOVdkDd-S5vJUyDLRu2OEcE,2358
+jeval/evaluate.py,sha256=rPl9xAd1iyUWXlpKEINOGHZJob7nZBA5-7EDomzci2Q,7347
+jeval/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jeval/result.py,sha256=MqxX6PblDu_eEF1gOxTHPv7-0eaxoXNkgyUpMZtagQs,1257
+jeval-0.1.0.dist-info/METADATA,sha256=ftJSEb-mESPfB-Cd_8FB0Amnt63NwOLYZSWWkdEYB6E,1411
+jeval-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+jeval-0.1.0.dist-info/entry_points.txt,sha256=rDC_Rtrn5u8J7vPBTagnWtBjMqHFm1TetYXaRfpALDA,41
+jeval-0.1.0.dist-info/RECORD,,

jeval-0.1.0.dist-info/WHEEL

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

jeval-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jeval = jeval.cli:main