snapline-engine 0.1.10__tar.gz

snapline_engine-0.1.10/.gitignore

@@ -0,0 +1,5 @@
+/*.iml
+.idea
+dist/
+build/
+*.egg-info/

snapline_engine-0.1.10/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: snapline-engine
+Version: 0.1.10
+Summary: Deep JSON reconciliation engine for Snapline
+Project-URL: Homepage, https://github.com/vaagatech/snapline-python
+Project-URL: Repository, https://github.com/vaagatech/snapline-python
+Author-email: VaagaTech <info@vaagatech.com>
+License-Expression: MIT
+Keywords: reconciliation,snapline,snapshot,testing
+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
+Requires-Python: >=3.10

snapline_engine-0.1.10/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snapline-engine"
+version = "0.1.10"
+description = "Deep JSON reconciliation engine for Snapline"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "VaagaTech", email = "info@vaagatech.com" }]
+keywords = ["snapline", "testing", "snapshot", "reconciliation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vaagatech/snapline-python"
+Repository = "https://github.com/vaagatech/snapline-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["snapline"]

snapline_engine-0.1.10/snapline/engine/__init__.py

@@ -0,0 +1,26 @@
+from .apply_data_mapping import apply_data_mapping, map_field_value
+from .apply_transformations import apply_transformations
+from .assert_against_file import assert_against_file
+from .compare_objects import compare_objects
+from .diff_values import diff_values
+from .io.load_json_file import load_json_file
+from .reconcile import reconcile
+from .strip_fields import strip_fields
+from .utils.deep_clone import deep_clone
+from .utils.is_plain_object import is_plain_object
+from .utils.stable_stringify import stable_stringify
+
+__all__ = [
+    "apply_data_mapping",
+    "apply_transformations",
+    "assert_against_file",
+    "compare_objects",
+    "deep_clone",
+    "diff_values",
+    "is_plain_object",
+    "load_json_file",
+    "map_field_value",
+    "reconcile",
+    "stable_stringify",
+    "strip_fields",
+]

snapline_engine-0.1.10/snapline/engine/apply_data_mapping.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .types import DataMappingMap, FieldMapping
+from .utils.deep_clone import deep_clone
+from .utils.is_plain_object import is_plain_object
+
+
+def map_field_value(value: Any, mapping: FieldMapping) -> Any:
+    if callable(mapping):
+        return mapping(value)
+
+    if is_plain_object(mapping):
+        key = str(value)
+        if key in mapping:
+            return mapping[key]
+
+    return value
+
+
+def apply_data_mapping(
+    data: Any,
+    data_mapping: DataMappingMap | None = None,
+) -> Any:
+    mappings = data_mapping or {}
+    if not mappings:
+        return data
+
+    def walk(value: Any) -> Any:
+        if isinstance(value, list):
+            return [walk(item) for item in value]
+
+        if not is_plain_object(value):
+            return value
+
+        result: dict[str, Any] = {}
+        for key, child in value.items():
+            mapping = mappings.get(key)
+            if mapping:
+                result[key] = map_field_value(child, mapping)
+            else:
+                result[key] = walk(child)
+        return result
+
+    return walk(deep_clone(data))

snapline_engine-0.1.10/snapline/engine/apply_transformations.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .types import TransformationMap
+from .utils.deep_clone import deep_clone
+from .utils.is_plain_object import is_plain_object
+
+
+def apply_transformations(
+    data: Any,
+    transformations: TransformationMap | None = None,
+) -> Any:
+    transforms = transformations or {}
+    if not transforms:
+        return data
+
+    def walk(value: Any) -> Any:
+        if isinstance(value, list):
+            return [walk(item) for item in value]
+
+        if not is_plain_object(value):
+            return value
+
+        result: dict[str, Any] = {}
+        for key, child in value.items():
+            transform = transforms.get(key)
+            if transform:
+                result[key] = transform(child, key, value)
+            else:
+                result[key] = walk(child)
+        return result
+
+    return walk(deep_clone(data))

snapline_engine-0.1.10/snapline/engine/assert_against_file.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .io.load_json_file import load_json_file
+from .reconcile import reconcile
+from .types import ReconcileOptions
+
+
+def assert_against_file(
+    live_data: Any,
+    expected_file_path: str | Path,
+    options: ReconcileOptions | dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    expected_data = load_json_file(expected_file_path)
+    return reconcile(live_data, expected_data, options)

snapline_engine-0.1.10/snapline/engine/compare_objects.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .diff_values import diff_values
+
+
+def compare_objects(actual: Any, expected: Any) -> dict[str, Any]:
+    diff = diff_values(actual, expected)
+    return {"match": diff is None, "diff": diff}

snapline_engine-0.1.10/snapline/engine/diff_values.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .utils.is_plain_object import is_plain_object
+from .utils.stable_stringify import stable_stringify
+
+
+def diff_values(
+    actual: Any,
+    expected: Any,
+    path_prefix: str = "",
+) -> dict[str, Any] | None:
+    if actual == expected:
+        return None
+
+    actual_type = "array" if isinstance(actual, list) else type(actual).__name__
+    expected_type = "array" if isinstance(expected, list) else type(expected).__name__
+
+    if actual_type != expected_type:
+        return {
+            "path": path_prefix or "(root)",
+            "actual": actual,
+            "expected": expected,
+            "message": f"Type mismatch: {actual_type} !== {expected_type}",
+        }
+
+    if not is_plain_object(actual) and not isinstance(actual, list):
+        return {
+            "path": path_prefix or "(root)",
+            "actual": actual,
+            "expected": expected,
+            "message": "Value mismatch",
+        }
+
+    if isinstance(actual, list) and isinstance(expected, list):
+        if len(actual) != len(expected):
+            return {
+                "path": path_prefix or "(root)",
+                "actual": len(actual),
+                "expected": len(expected),
+                "message": "Array length mismatch",
+            }
+
+        for index, (actual_item, expected_item) in enumerate(zip(actual, expected)):
+            child_path = f"{path_prefix}[{index}]" if path_prefix else f"[{index}]"
+            child_diff = diff_values(actual_item, expected_item, child_path)
+            if child_diff:
+                return child_diff
+        return None
+
+    if not is_plain_object(actual) or not is_plain_object(expected):
+        return {
+            "path": path_prefix or "(root)",
+            "actual": actual,
+            "expected": expected,
+            "message": "Value mismatch",
+        }
+
+    actual_keys = sorted(actual.keys())
+    expected_keys = sorted(expected.keys())
+
+    if stable_stringify(actual_keys) != stable_stringify(expected_keys):
+        return {
+            "path": path_prefix or "(root)",
+            "actual": actual_keys,
+            "expected": expected_keys,
+            "message": "Object key mismatch",
+        }
+
+    for key in actual_keys:
+        child_path = f"{path_prefix}.{key}" if path_prefix else key
+        child_diff = diff_values(actual[key], expected[key], child_path)
+        if child_diff:
+            return child_diff
+
+    return None

snapline_engine-0.1.10/snapline/engine/io/load_json_file.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_json_file(path: str | Path) -> Any:
+    with open(path, encoding="utf-8") as handle:
+        return json.load(handle)

snapline_engine-0.1.10/snapline/engine/reconcile.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .apply_data_mapping import apply_data_mapping
+from .apply_transformations import apply_transformations
+from .compare_objects import compare_objects
+from .strip_fields import strip_fields
+from .types import ReconcileOptions
+from .utils.deep_clone import deep_clone
+
+
+def reconcile(
+    live_data: Any,
+    expected_data: Any,
+    options: ReconcileOptions | dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    opts = options or {}
+    ignore_fields = opts.get("ignoreFields", [])
+    transformations = opts.get("transformations", {})
+    data_mapping = opts.get("dataMapping", {})
+
+    processed = deep_clone(live_data)
+    processed = strip_fields(processed, ignore_fields)
+    processed = apply_transformations(processed, transformations)
+    processed = apply_data_mapping(processed, data_mapping)
+
+    expected = deep_clone(expected_data)
+    expected = strip_fields(expected, ignore_fields)
+
+    comparison = compare_objects(processed, expected)
+    return {
+        "match": comparison["match"],
+        "processed": processed,
+        "expected": expected,
+        "diff": comparison["diff"],
+    }

snapline_engine-0.1.10/snapline/engine/strip_fields.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .utils.deep_clone import deep_clone
+from .utils.is_plain_object import is_plain_object
+
+
+def _remove_nested(target: Any, field_path: str) -> None:
+    parts = field_path.split(".")
+    cursor: Any = target if is_plain_object(target) else None
+
+    for part in parts[:-1]:
+        if not part or not is_plain_object(cursor) or part not in cursor:
+            return
+        cursor = cursor[part]
+
+    last_key = parts[-1]
+    if not last_key or cursor is None:
+        return
+
+    if is_plain_object(cursor):
+        cursor.pop(last_key, None)
+
+
+def strip_fields(data: Any, ignore_fields: list[str] | None = None) -> Any:
+    fields = ignore_fields or []
+    if not fields:
+        return data
+
+    top_level_keys = {field for field in fields if "." not in field}
+    nested_paths = [field for field in fields if "." in field]
+
+    def walk(value: Any) -> Any:
+        if isinstance(value, list):
+            return [walk(item) for item in value]
+
+        if not is_plain_object(value):
+            return value
+
+        result: dict[str, Any] = {}
+        for key, child in value.items():
+            if key in top_level_keys:
+                continue
+            result[key] = walk(child)
+
+        for field_path in nested_paths:
+            _remove_nested(result, field_path)
+
+        return result
+
+    return walk(deep_clone(data))

snapline_engine-0.1.10/snapline/engine/types.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, TypeAlias
+
+JsonValue: TypeAlias = Any
+FieldTransformation: TypeAlias = Callable[[Any, str, dict[str, Any]], Any]
+FieldMapping: TypeAlias = dict[str, Any] | Callable[[Any], Any]
+TransformationMap: TypeAlias = dict[str, FieldTransformation]
+DataMappingMap: TypeAlias = dict[str, FieldMapping]
+
+
+class DiffResult(dict):
+    """path, actual, expected, message."""
+
+    path: str
+    actual: Any
+    expected: Any
+    message: str
+
+
+class ReconcileOptions(dict):
+    ignoreFields: list[str]
+    transformations: TransformationMap
+    dataMapping: DataMappingMap
+
+
+class ReconcileResult(dict):
+    match: bool
+    processed: Any
+    expected: Any
+    diff: DiffResult | None
+
+
+class CompareResult(dict):
+    match: bool
+    diff: DiffResult | None

snapline_engine-0.1.10/snapline/engine/utils/deep_clone.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+def deep_clone(value: Any) -> Any:
+    return copy.deepcopy(value)

snapline_engine-0.1.10/snapline/engine/utils/is_plain_object.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_plain_object(value: Any) -> bool:
+    return isinstance(value, dict)

snapline_engine-0.1.10/snapline/engine/utils/stable_stringify.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def stable_stringify(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))