deepdiff-rust 0.1.0__cp39-abi3-macosx_11_0_arm64.whl

deepdiff_rust/__init__.py

@@ -0,0 +1,6 @@
+"""Rust-backed DeepDiff-compatible comparison engine."""
+
+from ._native import MAX_DEPTH_CEILING, MaxDepthError, __version__, diff_json
+from ._diff import DeepDiff
+
+__all__ = ["DeepDiff", "diff_json", "MaxDepthError", "MAX_DEPTH_CEILING", "__version__"]

deepdiff_rust/__init__.pyi

@@ -0,0 +1,91 @@
+from collections.abc import Iterable
+from re import Pattern
+from typing import Any
+
+__version__: str
+
+class MaxDepthError(ValueError):
+    """Raised when diffing two values would need to recurse past the configured ``max_depth``."""
+
+MAX_DEPTH_CEILING: int
+
+class DeepDiff(dict[str, Any]):
+    """A drop-in ``deepdiff.DeepDiff``: the differences between ``t1`` and ``t2`` as a dict."""
+
+    t1: Any
+    t2: Any
+    verbose_level: int
+
+    def __init__(
+        self,
+        t1: Any,
+        t2: Any,
+        *,
+        ignore_order: bool = ...,
+        max_depth: int | None = ...,
+        verbose_level: int = ...,
+        view: str = ...,
+        exclude_paths: str | Iterable[str] | None = ...,
+        exclude_regex_paths: str | Pattern[str] | Iterable[str | Pattern[str]] | None = ...,
+        include_paths: str | Iterable[str] | None = ...,
+        exclude_types: Iterable[type] | None = ...,
+        ignore_private_variables: bool = ...,
+        significant_digits: int | None = ...,
+        number_format_notation: str = ...,
+        math_epsilon: float | None = ...,
+        use_log_scale: bool = ...,
+        log_scale_similarity_threshold: float = ...,
+        ignore_nan_inequality: bool = ...,
+        ignore_string_case: bool = ...,
+        ignore_numeric_type_changes: bool = ...,
+        ignore_string_type_changes: bool = ...,
+        ignore_type_in_groups: Any = ...,
+        ignore_type_subclasses: bool = ...,
+        truncate_datetime: str | None = ...,
+        ignore_uuid_types: bool = ...,
+        use_enum_value: bool = ...,
+        threshold_to_diff_deeper: float = ...,
+        cutoff_distance_for_pairs: float = ...,
+        cutoff_intersection_for_pairs: float = ...,
+        zip_ordered_iterables: bool = ...,
+        get_deep_distance: bool = ...,
+        group_by: Any = ...,
+        group_by_sort_key: Any = ...,
+        report_repetition: bool = ...,
+        max_diffs: int | None = ...,
+        max_passes: int = ...,
+        custom_operators: list[Any] | None = ...,
+        exclude_obj_callback: Any | None = ...,
+        exclude_obj_callback_strict: Any | None = ...,
+        include_obj_callback: Any | None = ...,
+        include_obj_callback_strict: Any | None = ...,
+        iterable_compare_func: Any | None = ...,
+    ) -> None: ...
+    def to_dict(self, verbose_level: int | None = ...) -> dict[str, Any]:
+        """The differences as a plain dict, with ``type_changes`` types as type objects."""
+
+    def to_json(
+        self,
+        default_mapping: dict[type, Any] | None = ...,
+        force_use_builtin_json: bool = ...,
+        verbose_level: int | None = ...,
+        **kwargs: Any,
+    ) -> str:
+        """The differences as JSON; extra keyword arguments go to ``json.dumps``."""
+
+    @property
+    def affected_paths(self) -> set[str]:
+        """The paths of every difference in this result."""
+
+    @property
+    def affected_root_keys(self) -> set[Any]:
+        """The root keys, indices or attribute names the differences sit under."""
+
+def diff_json(
+    a: str,
+    b: str,
+    ignore_order: bool = ...,
+    max_depth: int | None = ...,
+) -> str:
+    """Diffs two JSON documents and returns a ``DeepDiff``-compatible JSON report string (``verbose_level=2`` shape)."""
+

deepdiff_rust/_callbacks.py

@@ -0,0 +1,111 @@
+"""DeepDiff callback helpers: Level, activity, object-callback skip."""
+
+from collections.abc import Mapping
+
+from ._paths import _elements
+
+
+class Level:
+    """Minimal DeepDiff-compatible level for operators and iterable_compare_func."""
+
+    __slots__ = ("t1", "t2", "_path")
+
+    def __init__(self, t1, t2, path="root"):
+        self.t1 = t1
+        self.t2 = t2
+        self._path = path
+
+    def path(self):
+        return self._path
+
+
+def callbacks_active(
+    *,
+    custom_operators=None,
+    exclude_obj_callback=None,
+    exclude_obj_callback_strict=None,
+    include_obj_callback=None,
+    include_obj_callback_strict=None,
+    iterable_compare_func=None,
+):
+    return any(
+        (
+            custom_operators,
+            exclude_obj_callback,
+            exclude_obj_callback_strict,
+            include_obj_callback,
+            include_obj_callback_strict,
+            iterable_compare_func,
+        )
+    )
+
+
+def _child(obj, seg):
+    if isinstance(obj, Mapping):
+        return obj[seg]
+    if isinstance(seg, int) and isinstance(obj, (list, tuple)):
+        return obj[seg]
+    return getattr(obj, seg)
+
+
+def resolve(root, path):
+    if path == "root":
+        return root
+    cur = root
+    for seg in _elements(path):
+        cur = _child(cur, seg)
+    return cur
+
+
+def compose_skip(
+    base_skip,
+    t1,
+    t2,
+    *,
+    exclude_obj_callback=None,
+    exclude_obj_callback_strict=None,
+    include_obj_callback=None,
+    include_obj_callback_strict=None,
+):
+    """Retain-filter skip plus DeepDiff object-callback branch of `_skip_this`."""
+    if not any(
+        (
+            exclude_obj_callback,
+            exclude_obj_callback_strict,
+            include_obj_callback,
+            include_obj_callback_strict,
+        )
+    ):
+        return base_skip
+
+    def skip_obj(path):
+        try:
+            o1, o2 = resolve(t1, path), resolve(t2, path)
+        except (KeyError, IndexError, AttributeError, TypeError):
+            o1 = o2 = None
+        if exclude_obj_callback and (
+            exclude_obj_callback(o1, path) or exclude_obj_callback(o2, path)
+        ):
+            return True
+        if exclude_obj_callback_strict and (
+            exclude_obj_callback_strict(o1, path)
+            and exclude_obj_callback_strict(o2, path)
+        ):
+            return True
+        if include_obj_callback and path != "root":
+            return not (
+                include_obj_callback(o1, path) or include_obj_callback(o2, path)
+            )
+        if include_obj_callback_strict and path != "root":
+            return not (
+                include_obj_callback_strict(o1, path)
+                and include_obj_callback_strict(o2, path)
+            )
+        return False
+
+    def skip(prefixes, typed):
+        if base_skip and base_skip(prefixes, typed):
+            return True
+        return any(skip_obj(path) for path in prefixes)
+
+    return skip

deepdiff_rust/_diff.py

@@ -0,0 +1,285 @@
+"""The `DeepDiff` result: a `dict` of findings, like `deepdiff.DeepDiff`."""
+
+import ast
+import datetime
+import decimal
+import json
+import uuid
+
+from . import _native
+from ._callbacks import callbacks_active, compose_skip
+from ._dual import run_dual
+from ._group_by import group_pair
+from ._options import native_options
+from ._paths import skip_filter
+from ._view import build_tree, pretty_from_tree, tree_as_result
+
+_BUILTIN_TYPES = {
+    t.__name__: t
+    for t in (
+        type(None), bool, int, float, str, list, tuple, set, frozenset, dict,
+        datetime.datetime, datetime.date, datetime.time, datetime.timedelta,
+        bytes, complex, decimal.Decimal, uuid.UUID,
+    )
+}
+
+
+def _check_verbose_level(verbose_level):
+    if verbose_level not in (0, 1, 2):
+        raise ValueError("verbose_level should be 0, 1, or 2.")
+    return verbose_level
+
+
+_NOT_PRESENT = object()
+
+
+def _root_key(path):
+    """The key, index or attribute name right after `root` in a rendered path."""
+    rest = path[len("root"):]
+    if rest.startswith("."):
+        ends = [i for i in (rest.find(".", 1), rest.find("[")) if i > 0]
+        return rest[1 : min(ends, default=len(rest))]
+    # ponytail: tries each "]" until the key parses as a literal; a key whose
+    # repr is not a Python literal is skipped.
+    end = rest.find("]")
+    while end != -1:
+        try:
+            return ast.literal_eval(rest[1:end])
+        except (ValueError, SyntaxError):
+            end = rest.find("]", end + 1)
+    return _NOT_PRESENT
+
+
+class DeepDiff(dict):
+    """A drop-in `deepdiff.DeepDiff`: the differences between `t1` and `t2` as a dict."""
+
+    def __init__(
+        self, t1, t2, *, ignore_order=False, max_depth=None, verbose_level=1, view="text",
+        exclude_paths=None, exclude_regex_paths=None, include_paths=None, exclude_types=None,
+        ignore_private_variables=True, significant_digits=None, number_format_notation="f",
+        math_epsilon=None, use_log_scale=False, log_scale_similarity_threshold=0.1,
+        ignore_nan_inequality=False, ignore_string_case=False, ignore_numeric_type_changes=False,
+        ignore_string_type_changes=False, ignore_type_in_groups=None, ignore_type_subclasses=False,
+        truncate_datetime=None, ignore_uuid_types=False, use_enum_value=False,
+        threshold_to_diff_deeper=0.33, cutoff_distance_for_pairs=0.3,
+        cutoff_intersection_for_pairs=0.7, zip_ordered_iterables=False, get_deep_distance=False,
+        group_by=None, group_by_sort_key=None, report_repetition=False, max_diffs=None,
+        max_passes=10000000, custom_operators=None, exclude_obj_callback=None,
+        exclude_obj_callback_strict=None, include_obj_callback=None,
+        include_obj_callback_strict=None, iterable_compare_func=None,
+    ):
+        if view not in ("text", "tree"):
+            raise NotImplementedError(
+                f"view={view!r} is not supported yet; only view='text' and view='tree' are."
+            )
+        self.view = view
+        self.verbose_level = _check_verbose_level(verbose_level)
+        if not 0 <= float(cutoff_distance_for_pairs) <= 1:
+            raise ValueError("cutoff_distance_for_pairs needs to be a positive float max 1.")
+        if t1 is t2 and group_by is None:
+            self.t1 = t1
+            self.t2 = t2
+            self._native = None
+            self._bridge = None
+            self.tree = {}
+            super().__init__()
+            return
+        t1, t2 = group_pair(t1, t2, group_by, group_by_sort_key)
+        self.t1 = t1
+        self.t2 = t2
+        self.custom_operators = custom_operators or []
+        self.exclude_obj_callback = exclude_obj_callback
+        self.exclude_obj_callback_strict = exclude_obj_callback_strict
+        self.include_obj_callback = include_obj_callback
+        self.include_obj_callback_strict = include_obj_callback_strict
+        self.iterable_compare_func = iterable_compare_func
+        self._callbacks_active = callbacks_active(
+            custom_operators=custom_operators,
+            exclude_obj_callback=exclude_obj_callback,
+            exclude_obj_callback_strict=exclude_obj_callback_strict,
+            include_obj_callback=include_obj_callback,
+            include_obj_callback_strict=include_obj_callback_strict,
+            iterable_compare_func=iterable_compare_func,
+        )
+        exclude_types = tuple(exclude_types) if exclude_types else None
+        if custom_operators or iterable_compare_func:
+            def native_factory(a, b):
+                return dict(
+                    _native.DeepDiff(
+                        a, b,
+                        ignore_order=ignore_order, max_depth=max_depth,
+                        exclude_types=exclude_types,
+                        ignore_private_variables=ignore_private_variables,
+                        use_enum_value=use_enum_value,
+                        threshold_to_diff_deeper=float(threshold_to_diff_deeper or 0),
+                        cutoff_distance_for_pairs=float(cutoff_distance_for_pairs),
+                        cutoff_intersection_for_pairs=float(cutoff_intersection_for_pairs),
+                        zip_ordered_iterables=zip_ordered_iterables,
+                        get_deep_distance=False, report_repetition=report_repetition,
+                        max_diffs=max_diffs, max_passes=max_passes,
+                        **native_options(
+                            _BUILTIN_TYPES, significant_digits=significant_digits,
+                            number_format_notation=number_format_notation,
+                            math_epsilon=math_epsilon, use_log_scale=use_log_scale,
+                            log_scale_similarity_threshold=log_scale_similarity_threshold,
+                            ignore_nan_inequality=ignore_nan_inequality,
+                            ignore_string_case=ignore_string_case,
+                            ignore_numeric_type_changes=ignore_numeric_type_changes,
+                            ignore_string_type_changes=ignore_string_type_changes,
+                            ignore_type_in_groups=ignore_type_in_groups,
+                            ignore_type_subclasses=ignore_type_subclasses,
+                            truncate_datetime=truncate_datetime,
+                            ignore_uuid_types=ignore_uuid_types,
+                        ),
+                    ).to_dict(verbose_level)
+                )
+            self._native = None
+            self._bridge = None
+            self._finish_init(run_dual(self, t1, t2, native_factory))
+            return
+        skip = skip_filter(exclude_paths, include_paths, exclude_regex_paths, exclude_types)
+        skip = compose_skip(
+            skip, t1, t2,
+            exclude_obj_callback=exclude_obj_callback,
+            exclude_obj_callback_strict=exclude_obj_callback_strict,
+            include_obj_callback=include_obj_callback,
+            include_obj_callback_strict=include_obj_callback_strict,
+        )
+        self._bridge = None
+        self._native = _native.DeepDiff(
+            t1, t2, ignore_order=ignore_order, max_depth=max_depth, exclude_types=exclude_types,
+            ignore_private_variables=ignore_private_variables, skip=skip, use_enum_value=use_enum_value,
+            threshold_to_diff_deeper=float(threshold_to_diff_deeper or 0),
+            cutoff_distance_for_pairs=float(cutoff_distance_for_pairs),
+            cutoff_intersection_for_pairs=float(cutoff_intersection_for_pairs),
+            zip_ordered_iterables=zip_ordered_iterables, get_deep_distance=get_deep_distance,
+            report_repetition=report_repetition, max_diffs=max_diffs, max_passes=max_passes,
+            **native_options(
+                _BUILTIN_TYPES, significant_digits=significant_digits,
+                number_format_notation=number_format_notation, math_epsilon=math_epsilon,
+                use_log_scale=use_log_scale,
+                log_scale_similarity_threshold=log_scale_similarity_threshold,
+                ignore_nan_inequality=ignore_nan_inequality, ignore_string_case=ignore_string_case,
+                ignore_numeric_type_changes=ignore_numeric_type_changes,
+                ignore_string_type_changes=ignore_string_type_changes,
+                ignore_type_in_groups=ignore_type_in_groups,
+                ignore_type_subclasses=ignore_type_subclasses,
+                truncate_datetime=truncate_datetime, ignore_uuid_types=ignore_uuid_types,
+            ),
+        )
+        self._finish_init(self.to_dict())
+
+    def _finish_init(self, report):
+        """Store text report, build `.tree`, and optionally switch to view='tree'."""
+        text = dict(report)
+        self.tree = build_tree(text, self.verbose_level)
+        if self.view == "tree":
+            super().__init__(tree_as_result(self.tree))
+        else:
+            super().__init__(text)
+
+    def to_dict(self, verbose_level=None):
+        """The differences as a plain dict, with `type_changes` types as type objects."""
+        if self._native is None:
+            if self._bridge is not None:
+                return self._bridge.to_dict(verbose_level=self._level(verbose_level))
+            if getattr(self, "view", "text") == "tree":
+                # Rebuild a text-shaped dict from levels when asked.
+                out = {}
+                for key, levels in self.tree.items():
+                    if key.endswith(("_added", "_removed")) and self._level(verbose_level) < 2:
+                        out[key] = [level.path() for level in levels]
+                    elif key in ("values_changed", "type_changes"):
+                        out[key] = {
+                            level.path(): {
+                                "old_value": level.t1,
+                                "new_value": level.t2,
+                                **(
+                                    {"old_type": type(level.t1), "new_type": type(level.t2)}
+                                    if key == "type_changes"
+                                    else {}
+                                ),
+                            }
+                            for level in levels
+                        }
+                    else:
+                        out[key] = {
+                            level.path(): level.t2 if key.endswith("_added") else level.t1
+                            for level in levels
+                        }
+                return out
+            return dict(self)
+        report = self._native.to_dict(self._level(verbose_level))
+        if "type_changes" in report:
+            classes = {**_BUILTIN_TYPES, **self._native._types}
+            for change in report["type_changes"].values():
+                for key in ("old_type", "new_type"):
+                    change[key] = classes.get(change[key], change[key])
+        if self._native.deep_distance is not None:
+            report["deep_distance"] = self._native.deep_distance
+        return report
+
+    def to_json(self, default_mapping=None, force_use_builtin_json=False, verbose_level=None, **kwargs):
+        """The differences as JSON; extra keyword arguments go to `json.dumps`."""
+        if default_mapping is not None:
+            raise NotImplementedError("default_mapping is not supported yet.")
+        if self._native is None:
+            if self._bridge is not None:
+                return self._bridge.to_json(verbose_level=self._level(verbose_level), **kwargs)
+            return json.dumps(self.to_dict(verbose_level), **kwargs) if kwargs else json.dumps(self.to_dict(verbose_level))
+        text = self._native.to_json(self._level(verbose_level))
+        if self._native.deep_distance is not None:
+            report = json.loads(text)
+            report["deep_distance"] = self._native.deep_distance
+            return json.dumps(report, **kwargs)
+        return json.dumps(json.loads(text), **kwargs) if kwargs else text
+
+    @property
+    def affected_paths(self):
+        """The paths of every difference in this result."""
+        paths = set()
+        for key, findings in self.items():
+            if key == "deep_distance":
+                continue
+            if getattr(self, "view", "text") == "tree":
+                paths.update(level.path() for level in findings)
+            elif isinstance(findings, dict):
+                paths.update(findings)
+            else:
+                paths.update(findings)
+        return paths
+
+    @property
+    def affected_root_keys(self):
+        """The root keys, indices or attribute names the differences sit under."""
+        report = self.to_dict(2)
+        keys = set()
+        for findings in report.values():
+            if isinstance(findings, dict):
+                keys.update(_root_key(path) for path in findings)
+            else:
+                keys.update(_root_key(path) for path in findings)
+        keys.discard(_NOT_PRESENT)
+        return keys
+
+    def pretty(self, prefix=None):
+        """Human-readable multi-line summary of the differences."""
+        tree = getattr(self, "tree", None) or build_tree(self.to_dict(), self.verbose_level)
+        return pretty_from_tree(tree, self.verbose_level, prefix)
+
+    def custom_report_result(self, report_type, level, extra_info=None):
+        path = level.path()
+        payload = dict(extra_info or {})
+        if report_type == "values_changed":
+            payload.setdefault("old_value", level.t1)
+            payload.setdefault("new_value", level.t2)
+        bucket = getattr(self, "_walk_report", self).setdefault(report_type, {})
+        bucket[path] = payload
+        if self._native is None and getattr(self, "_bridge", None) is None:
+            self.setdefault(report_type, {})[path] = payload
+
+    def _report_result(self, report_type, change_level, local_tree=None):
+        self.custom_report_result(report_type, change_level)
+
+    def _level(self, verbose_level):
+        return self.verbose_level if verbose_level is None else _check_verbose_level(verbose_level)

deepdiff_rust/_dual.py

@@ -0,0 +1,130 @@
+"""Native dual walk for custom_operators and iterable_compare_func."""
+
+from collections.abc import Mapping, Sequence
+
+from ._callbacks import Level
+
+_SENTINEL = object()
+
+
+def _is_seq(x):
+    return isinstance(x, Sequence) and not isinstance(x, (str, bytes, bytearray))
+
+
+def _remap(path, prefix):
+    if path == "root":
+        return prefix
+    return prefix + path[4:]
+
+
+def _merge_native(into, native_dict, prefix):
+    for category, findings in native_dict.items():
+        if category == "deep_distance":
+            continue
+        bucket = into.setdefault(category, {})
+        if isinstance(findings, dict):
+            for path, payload in findings.items():
+                bucket[_remap(path, prefix)] = payload
+        else:
+            bucket.update(findings)
+
+
+def _matching_pairs(t1, t2, level, compare_func):
+    if compare_func is None:
+        from itertools import zip_longest
+        return [
+            ((i, i), (x, y))
+            for i, (x, y) in enumerate(zip_longest(t1, t2, fillvalue=_SENTINEL))
+        ]
+    matches = []
+    y_matched = set()
+    for i, x in enumerate(t1):
+        found = False
+        for j, y in enumerate(t2):
+            if j in y_matched:
+                continue
+            try:
+                ok = compare_func(x, y, level)
+            except Exception:
+                ok = False
+            if ok:
+                y_matched.add(j)
+                matches.append(((i, j), (x, y)))
+                found = True
+                break
+        if not found:
+            matches.append(((i, -1), (x, _SENTINEL)))
+    for j, y in enumerate(t2):
+        if j not in y_matched:
+            matches.append(((-1, j), (_SENTINEL, y)))
+    return matches
+
+
+def walk_diff(diff_instance, t1, t2, path, native_factory):
+    level = Level(t1, t2, path)
+    for operator in diff_instance.custom_operators:
+        if operator.match(level) and operator.give_up_diffing(level, diff_instance):
+            return
+    if _skip_obj(diff_instance, t1, t2, path):
+        return
+    if t1 is t2:
+        return
+    if isinstance(t1, Mapping) and isinstance(t2, Mapping):
+        _walk_mapping(diff_instance, t1, t2, path, native_factory)
+        return
+    if _is_seq(t1) and _is_seq(t2):
+        _walk_seq(diff_instance, t1, t2, path, native_factory)
+        return
+    _merge_native(diff_instance._walk_report, native_factory(t1, t2), path)
+
+
+def _skip_obj(diff_instance, t1, t2, path):
+    ex = diff_instance.exclude_obj_callback
+    if ex and (ex(t1, path) or ex(t2, path)):
+        return True
+    exs = diff_instance.exclude_obj_callback_strict
+    if exs and exs(t1, path) and exs(t2, path):
+        return True
+    inc = diff_instance.include_obj_callback
+    if inc and path != "root" and not (inc(t1, path) or inc(t2, path)):
+        return True
+    incs = diff_instance.include_obj_callback_strict
+    if incs and path != "root" and not (incs(t1, path) and incs(t2, path)):
+        return True
+    return False
+
+
+def _walk_mapping(diff_instance, t1, t2, path, native_factory):
+    for key in set(t1) | set(t2):
+        child = f"{path}[{key!r}]"
+        if key in t1 and key in t2:
+            walk_diff(diff_instance, t1[key], t2[key], child, native_factory)
+        elif key in t1:
+            diff_instance._walk_report.setdefault("dictionary_item_removed", {})[child] = t1[key]
+        else:
+            diff_instance._walk_report.setdefault("dictionary_item_added", {})[child] = t2[key]
+
+
+def _walk_seq(diff_instance, t1, t2, path, native_factory):
+    level = Level(t1, t2, path)
+    pairs = _matching_pairs(t1, t2, level, diff_instance.iterable_compare_func)
+    for (i, j), (x, y) in pairs:
+        if x is _SENTINEL:
+            child = f"{path}[{j}]"
+            diff_instance._walk_report.setdefault("iterable_item_added", {})[child] = y
+        elif y is _SENTINEL:
+            child = f"{path}[{i}]"
+            diff_instance._walk_report.setdefault("iterable_item_removed", {})[child] = x
+        else:
+            moved = i != j and diff_instance.iterable_compare_func
+            child = f"{path}[{j if moved else i}]"
+            if moved and diff_instance.verbose_level > 1:
+                bucket = diff_instance._walk_report.setdefault("iterable_item_moved", {})
+                bucket[f"{path}[{i}]"] = {"new_path": f"{path}[{j}]", "value": y}
+            walk_diff(diff_instance, x, y, child, native_factory)
+
+
+def run_dual(diff_instance, t1, t2, native_factory):
+    diff_instance._walk_report = {}
+    walk_diff(diff_instance, t1, t2, "root", native_factory)
+    return diff_instance._walk_report

deepdiff_rust/_group_by.py

@@ -0,0 +1,55 @@
+"""`group_by`: a list of dicts regrouped into a dict before the diff, as DeepDiff does."""
+
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+
+
+def _key(row, group_by):
+    return group_by(row) if callable(group_by) else row.pop(group_by)
+
+
+def _add(result, key, row, sort_key):
+    if sort_key is None:
+        result[key] = row
+    elif row not in result.setdefault(key, []):
+        result[key].append(row)
+
+
+def _group(item, group_by, sort_key):
+    """DeepDiff's `_group_iterable_to_dict`; raises `KeyError` or `ValueError` when it cannot."""
+    level1, level2 = group_by, None
+    if isinstance(group_by, (list, tuple)):
+        level1, level2 = group_by[0], group_by[1] if len(group_by) > 1 else None
+    if not isinstance(item, Iterable) or isinstance(item, Mapping):
+        raise ValueError(f"Unable to group by {group_by}")
+    result = {}
+    for row in deepcopy(item):
+        if not isinstance(row, Mapping):
+            raise ValueError(f"Unable to group by {level1}: {row!r} is not a dictionary.")
+        key1 = _key(row, level1)
+        if level2:
+            _add(result.setdefault(key1, {}), _key(row, level2), row, sort_key)
+        else:
+            _add(result, key1, row, sort_key)
+    if sort_key is not None:
+        groups = [g for sub in result.values() for g in sub.values()] if level2 else result.values()
+        for rows in groups:
+            rows.sort(key=sort_key)
+    return result
+
+
+def group_pair(t1, t2, group_by, group_by_sort_key):
+    """`(t1, t2)` grouped, or both unchanged when either side cannot be grouped."""
+    if not group_by:
+        return t1, t2
+    sort_key = group_by_sort_key
+    if sort_key is not None and not callable(sort_key):
+        name = sort_key
+
+        def sort_key(row):
+            return row[name]
+
+    try:
+        return _group(t1, group_by, sort_key), _group(t2, group_by, sort_key)
+    except (KeyError, ValueError):
+        return t1, t2