structmatch 0.1.0__tar.gz

structmatch-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: structmatch
+Version: 0.1.0
+Summary: Deep structural matching, diffing, and pattern matching for Python
+Author: Teja
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

structmatch-0.1.0/README.md

@@ -0,0 +1,94 @@
+# structmatch
+
+Deep structural matching, diffing, and pattern matching for Python. Zero dependencies.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from structmatch import eq, diff, match, ANY, GT, LT, BETWEEN
+
+# Deep equality
+eq({"a": [1, 2]}, {"a": [1, 2]})  # True
+
+# Approximate matching
+eq(3.14159, 3.14160, tolerance=0.001)  # True
+
+# Order-independent lists
+eq([1, 2, 3], [3, 2, 1], ignore_order=True)  # True
+
+# Ignore specific keys
+eq({"a": 1, "id": 999}, {"a": 1, "id": 1}, ignore_keys=["id"])  # True
+
+# Case-insensitive strings
+eq("Hello", "hello", case_sensitive=False)  # True
+
+# Type coercion (int == float)
+eq(1, 1.0, type_coerce=True)  # True
+
+# Deep diff
+result = diff({"a": 1, "b": 2}, {"a": 1, "b": 20, "c": 3})
+print(result.added)    # {"c": 3}
+print(result.changed)  # {"b": (2, 20)}
+
+# Pattern matching
+match({"status": 200, "count": 5}, {
+    "status": GT(199),
+    "count": BETWEEN(1, 10),
+})  # True
+
+match(42, ANY)  # True
+match("hello@example.com", REGEX(r"@"))  # True
+```
+
+## Schema Validation
+
+```python
+from structmatch import Schema
+
+UserSchema = Schema({
+    "name": str,
+    "age": int,
+    "tags": [str],
+    "metadata": {str: object},
+})
+
+UserSchema.validate({"name": "Alice", "age": 30, "tags": ["admin"], "metadata": {"key": "val"}})  # True
+```
+
+## Custom Comparators
+
+```python
+from structmatch import eq, Comparator
+
+class DateTimeWithin(Comparator):
+    def __init__(self, seconds):
+        self.seconds = seconds
+    def matches(self, a, b):
+        return abs((a - b).total_seconds()) < self.seconds
+
+eq({"created": now}, {"created": later}, comparators=[DateTimeWithin(5)])
+```
+
+## All Comparators
+
+| Comparator | Matches |
+|---|---|
+| `ANY` | Anything |
+| `TYPE(t)` | Any value of type `t` |
+| `GT(n)` | `value > n` |
+| `LT(n)` | `value < n` |
+| `GE(n)` | `value >= n` |
+| `LE(n)` | `value <= n` |
+| `BETWEEN(a, b)` | `a <= value <= b` |
+| `REGEX(pattern)` | String matches regex |
+| `NOT(comp)` | Negates another comparator |
+
+## License
+
+MIT

structmatch-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "structmatch"
+version = "0.1.0"
+description = "Deep structural matching, diffing, and pattern matching for Python"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Teja"}]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "hypothesis", "pytest-cov"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

structmatch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

structmatch-0.1.0/src/structmatch/__init__.py

@@ -0,0 +1,40 @@
+"""structmatch — Deep structural matching, diffing, and pattern matching for Python."""
+
+from .core import eq, diff, match
+from .comparators import (
+    Comparator,
+    ANY,
+    TYPE,
+    GT,
+    LT,
+    GE,
+    LE,
+    BETWEEN,
+    REGEX,
+    NOT,
+)
+from .diff import DiffResult
+from .schema import Schema, SchemaError
+from .options import MatchOptions
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "eq",
+    "diff",
+    "match",
+    "ANY",
+    "TYPE",
+    "GT",
+    "LT",
+    "GE",
+    "LE",
+    "BETWEEN",
+    "REGEX",
+    "NOT",
+    "Comparator",
+    "DiffResult",
+    "Schema",
+    "SchemaError",
+    "MatchOptions",
+]

structmatch-0.1.0/src/structmatch/comparators.py

@@ -0,0 +1,106 @@
+"""Pattern-matching comparators."""
+
+from __future__ import annotations
+import re
+from abc import ABC, abstractmethod
+
+
+class Comparator(ABC):
+    """Base class for custom comparators."""
+
+    @abstractmethod
+    def matches(self, a, b) -> bool:
+        ...
+
+    def __call__(self, a, b) -> bool:
+        return self.matches(a, b)
+
+
+class ANY(Comparator):
+    """Matches anything."""
+
+    def matches(self, a, b) -> bool:
+        return True
+
+
+class TYPE(Comparator):
+    """Matches any value of a given type."""
+
+    def __init__(self, expected_type):
+        self.expected_type = expected_type
+
+    def matches(self, a, b) -> bool:
+        return isinstance(b, self.expected_type)
+
+
+class GT(Comparator):
+    """Matches if b > value."""
+
+    def __init__(self, value):
+        self.value = value
+
+    def matches(self, a, b) -> bool:
+        return b > self.value
+
+
+class LT(Comparator):
+    """Matches if b < value."""
+
+    def __init__(self, value):
+        self.value = value
+
+    def matches(self, a, b) -> bool:
+        return b < self.value
+
+
+class GE(Comparator):
+    """Matches if b >= value."""
+
+    def __init__(self, value):
+        self.value = value
+
+    def matches(self, a, b) -> bool:
+        return b >= self.value
+
+
+class LE(Comparator):
+    """Matches if b <= value."""
+
+    def __init__(self, value):
+        self.value = value
+
+    def matches(self, a, b) -> bool:
+        return b <= self.value
+
+
+class BETWEEN(Comparator):
+    """Matches if low <= b <= high."""
+
+    def __init__(self, low, high):
+        self.low = min(low, high)
+        self.high = max(low, high)
+
+    def matches(self, a, b) -> bool:
+        return self.low <= b <= self.high
+
+
+class REGEX(Comparator):
+    """Matches if b (string) matches the regex pattern."""
+
+    def __init__(self, pattern: str):
+        self.pattern = re.compile(pattern)
+
+    def matches(self, a, b) -> bool:
+        if not isinstance(b, str):
+            return False
+        return bool(self.pattern.search(b))
+
+
+class NOT(Comparator):
+    """Negates another comparator."""
+
+    def __init__(self, comparator: Comparator):
+        self.comparator = comparator
+
+    def matches(self, a, b) -> bool:
+        return not self.comparator.matches(a, b)

structmatch-0.1.0/src/structmatch/core.py

@@ -0,0 +1,177 @@
+"""Core functions: eq(), diff(), match()."""
+
+from __future__ import annotations
+from .options import MatchOptions
+from .diff import DiffResult, diff as _diff
+from .utils import (
+    _is_numeric,
+    _within_tolerance,
+    _compare_strings,
+    _filter_keys,
+    _is_dataclass_like,
+    _get_fields,
+    _is_comparator,
+    _as_multiset,
+    _hashable,
+)
+from .comparators import Comparator
+
+
+def _deep_eq(va, vb, opts: MatchOptions) -> bool:
+    """Recursive deep equality."""
+    # Check custom comparators first
+    for comp in opts.comparators:
+        if comp.matches(va, vb):
+            return True
+
+    # Handle type coercion: int/float interop
+    if opts.type_coerce and _is_numeric(va, vb) and _within_tolerance(va, vb, opts.tolerance):
+        return True
+
+    # Type mismatch (but handle dataclass/NamedTuple equality)
+    type_a = type(va)
+    type_b = type(vb)
+    if type_a != type_b:
+        if opts.type_coerce and _is_numeric(va, vb) and _within_tolerance(va, vb, opts.tolerance):
+            return True
+        return False
+
+    # None
+    if va is None:
+        return vb is None
+
+    # Booleans
+    if isinstance(va, bool):
+        return va == vb
+
+    # Strings
+    if isinstance(va, str):
+        return _compare_strings(va, vb, opts.case_sensitive)
+
+    # Numbers
+    if _is_numeric(va, vb):
+        return _within_tolerance(va, vb, opts.tolerance)
+
+    # Dicts
+    if isinstance(va, dict):
+        if len(va) != len(vb):
+            return False
+        va_f = _filter_keys(va, opts.ignore_keys)
+        vb_f = _filter_keys(vb, opts.ignore_keys)
+        if len(va_f) != len(vb_f):
+            return False
+        if set(va_f) != set(vb_f):
+            return False
+        for k in va_f:
+            if not _deep_eq(va_f[k], vb_f[k], opts):
+                return False
+        return True
+
+    # Lists / tuples
+    if isinstance(va, (list, tuple)):
+        if type(va) != type(vb):
+            return False
+        if len(va) != len(vb):
+            return False
+        if opts.ignore_order and isinstance(va, list):
+            return _as_multiset(va) == _as_multiset(vb)
+        return all(_deep_eq(a, b, opts) for a, b in zip(va, vb))
+
+    # Sets
+    if isinstance(va, set):
+        return va == vb
+
+    # Dataclasses / NamedTuples / objects with __dict__
+    if _is_dataclass_like(va):
+        fa = _get_fields(va)
+        fb = _get_fields(vb)
+        if fa is not None and fb is not None:
+            return _deep_eq(fa, fb, opts)
+
+    # Objects with __dict__ (but not dataclasses)
+    if not isinstance(va, (type, bool, int, float, str, list, tuple, set, dict)):
+        fa = _get_fields(va)
+        fb = _get_fields(vb)
+        if fa is not None and fb is not None and type(va) == type(vb):
+            return _deep_eq(fa, fb, opts)
+
+    # Fallback to ==
+    return va == vb
+
+
+def eq(a, b, *, tolerance: float = 0.0, ignore_order: bool = False,
+       ignore_keys: list[str] | None = None, case_sensitive: bool = True,
+       type_coerce: bool = False, comparators: list[Comparator] | None = None) -> bool:
+    """Deep structural equality comparison."""
+    opts = MatchOptions(
+        tolerance=tolerance,
+        ignore_order=ignore_order,
+        ignore_keys=ignore_keys,
+        case_sensitive=case_sensitive,
+        type_coerce=type_coerce,
+        comparators=comparators,
+    )
+    return _deep_eq(a, b, opts)
+
+
+def diff(a, b, **opts) -> DiffResult:
+    """Compute a deep diff between two structures."""
+    return _diff(a, b, **opts)
+
+
+def _deep_match(value, pattern, opts: MatchOptions) -> bool:
+    """Check if value matches a pattern (which may contain comparators)."""
+    # Pattern is a comparator (check FIRST, before any type checks)
+    if _is_comparator(pattern):
+        if isinstance(pattern, type):
+            pattern = pattern()
+        return pattern.matches(value, value)
+
+    # None value
+    if value is None:
+        if pattern is None or pattern is type(None):
+            return True
+        if isinstance(pattern, type):
+            return False
+        return False
+
+    # Pattern is a type
+    if isinstance(pattern, type):
+        if pattern is type(None):
+            return value is None
+        if pattern in (int, float):
+            return _is_numeric(value, value) and isinstance(value, pattern)
+        return isinstance(value, pattern)
+
+    # Both dicts
+    if isinstance(pattern, dict) and isinstance(value, dict):
+        value_f = _filter_keys(value, opts.ignore_keys)
+        for key, sub_pattern in pattern.items():
+            if key not in value_f:
+                return False
+            if not _deep_match(value_f[key], sub_pattern, opts):
+                return False
+        return True
+
+    # Both lists/tuples
+    if isinstance(pattern, (list, tuple)) and isinstance(value, (list, tuple)):
+        if len(pattern) != len(value):
+            return False
+        return all(_deep_match(v, p, opts) for v, p in zip(value, pattern))
+
+    # String pattern with case sensitivity
+    if isinstance(pattern, str) and isinstance(value, str):
+        return _compare_strings(pattern, value, opts.case_sensitive)
+
+    # Numeric with tolerance
+    if _is_numeric(pattern, value) or _is_numeric(value, pattern):
+        return _within_tolerance(pattern, value, opts.tolerance)
+
+    # Literal match
+    return pattern == value
+
+
+def match(obj, pattern, **opts) -> bool:
+    """Pattern matching: check if obj matches the given pattern."""
+    options = MatchOptions(**opts)
+    return _deep_match(obj, pattern, options)

structmatch-0.1.0/src/structmatch/diff.py

@@ -0,0 +1,203 @@
+"""Deep diff engine."""
+
+from __future__ import annotations
+from .options import MatchOptions
+from .utils import (
+    _is_numeric,
+    _within_tolerance,
+    _compare_strings,
+    _filter_keys,
+    _is_dataclass_like,
+    _get_fields,
+)
+
+
+class DiffResult:
+    """Result of a deep diff between two structures."""
+
+    __slots__ = ("added", "removed", "changed", "type_changes", "path_changes")
+
+    def __init__(
+        self,
+        added: dict | None = None,
+        removed: dict | None = None,
+        changed: dict | None = None,
+        type_changes: dict | None = None,
+        path_changes: list | None = None,
+    ):
+        self.added = added if added is not None else {}
+        self.removed = removed if removed is not None else {}
+        self.changed = changed if changed is not None else {}
+        self.type_changes = type_changes if type_changes is not None else {}
+        self.path_changes = path_changes if path_changes is not None else []
+
+    def has_changes(self) -> bool:
+        return bool(self.added or self.removed or self.changed or self.type_changes or self.path_changes)
+
+    def __bool__(self) -> bool:
+        return self.has_changes()
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.added:
+            parts.append(f"added={self.added}")
+        if self.removed:
+            parts.append(f"removed={self.removed}")
+        if self.changed:
+            parts.append(f"changed={self.changed}")
+        if self.type_changes:
+            parts.append(f"type_changes={self.type_changes}")
+        if self.path_changes:
+            parts.append(f"path_changes={self.path_changes}")
+        return f"DiffResult({', '.join(parts)})"
+
+    def __eq__(self, other):
+        if not isinstance(other, DiffResult):
+            return NotImplemented
+        return (
+            self.added == other.added
+            and self.removed == other.removed
+            and self.changed == other.changed
+            and self.type_changes == other.type_changes
+        )
+
+
+def _diff_dicts(a: dict, b: dict, opts: MatchOptions, path: str = "") -> DiffResult:
+    added = {}
+    removed = {}
+    changed = {}
+    type_changes = {}
+    path_changes = []
+
+    a_filtered = _filter_keys(a, opts.ignore_keys)
+    b_filtered = _filter_keys(b, opts.ignore_keys)
+
+    all_keys = set(a_filtered) | set(b_filtered)
+    for key in all_keys:
+        key_path = f"{path}.{key}" if path else key
+        if key not in a_filtered:
+            added[key] = b_filtered[key]
+        elif key not in b_filtered:
+            removed[key] = a_filtered[key]
+        else:
+            va = a_filtered[key]
+            vb = b_filtered[key]
+            child = _diff_values(va, vb, opts, key_path)
+            if child is None:
+                continue
+            if isinstance(child, dict):
+                if "sub_diff" in child:
+                    sub = child["sub_diff"]
+                    # Merge sub_diff into current
+                    added.update({f"{key}.{k}" if k in added else k: v for k, v in sub.added.items()})
+                    removed.update({f"{key}.{k}" if k in removed else k: v for k, v in sub.removed.items()})
+                    changed.update({f"{key}.{k}" if k in changed else k: v for k, v in sub.changed.items()})
+                    type_changes.update({f"{key}.{k}" if k in type_changes else k: v for k, v in sub.type_changes.items()})
+                    path_changes.extend(sub.path_changes)
+                elif "type_change" in child:
+                    type_changes[key] = child["type_change"]
+                elif "set_diff" in child:
+                    changed[key] = (va, vb)
+            elif isinstance(child, tuple):
+                changed[key] = child
+
+    return DiffResult(added=added, removed=removed, changed=changed, type_changes=type_changes, path_changes=path_changes)
+
+
+def _diff_sequences(a, b, opts: MatchOptions, path: str = "") -> DiffResult:
+    if opts.ignore_order:
+        # If same elements (multiset), no changes
+        from .utils import _as_multiset
+        if _as_multiset(a) == _as_multiset(b):
+            return DiffResult()
+
+    path_changes = []
+    max_len = max(len(a), len(b))
+    for i in range(max_len):
+        idx_path = f"{path}[{i}]"
+        if i >= len(a):
+            path_changes.append({"path": idx_path, "change": "added", "value": b[i]})
+        elif i >= len(b):
+            path_changes.append({"path": idx_path, "change": "removed", "value": a[i]})
+        else:
+            child = _diff_values(a[i], b[i], opts, idx_path)
+            if child is not None:
+                if isinstance(child, dict) and "type_change" in child:
+                    path_changes.append({"path": idx_path, "change": "type_change", "from": child["type_change"][0], "to": child["type_change"][1]})
+                elif isinstance(child, tuple):
+                    path_changes.append({"path": idx_path, "change": "changed", "from": child[0], "to": child[1]})
+                elif isinstance(child, dict) and "sub_diff" in child:
+                    path_changes.append({"path": idx_path, "change": "sub_diff", "details": child["sub_diff"]})
+                else:
+                    path_changes.append({"path": idx_path, "change": "changed", "from": a[i], "to": b[i]})
+
+    return DiffResult(path_changes=path_changes)
+
+
+def _diff_values(va, vb, opts: MatchOptions, path: str = ""):
+    """Returns None if equal, a tuple (old, new) if changed, or dict with type_change."""
+    type_a = type(va)
+    type_b = type(vb)
+
+    if type_a != type_b:
+        if opts.type_coerce and _is_numeric(va, vb) and _within_tolerance(va, vb, opts.tolerance):
+            return None
+        return {"type_change": (type_a, type_b)}
+
+    if isinstance(va, dict):
+        sub = _diff_dicts(va, vb, opts, path)
+        if sub.has_changes():
+            return {"sub_diff": sub}
+        return None
+
+    if isinstance(va, str):
+        if not _compare_strings(va, vb, opts.case_sensitive):
+            return (va, vb)
+        return None
+
+    if _is_numeric(va, vb):
+        if _within_tolerance(va, vb, opts.tolerance):
+            return None
+        return (va, vb)
+
+    if isinstance(va, (list, tuple)):
+        sub = _diff_sequences(va, vb, opts, path)
+        if sub.has_changes():
+            return {"sub_diff": sub}
+        return None
+
+    if isinstance(va, set):
+        extra_a = va - vb
+        extra_b = vb - va
+        if extra_a or extra_b:
+            return {"set_diff": {"removed": extra_a, "added": extra_b}}
+        return None
+
+    if _is_dataclass_like(va):
+        fa = _get_fields(va)
+        fb = _get_fields(vb)
+        return _diff_dicts(fa, fb, opts, path)
+
+    if va == vb:
+        return None
+    return (va, vb)
+
+
+def diff(a, b, **opts) -> DiffResult:
+    """Compute a deep diff between two structures."""
+    options = MatchOptions(**opts)
+    result = _diff_values(a, b, options)
+    if result is None:
+        return DiffResult()
+    if isinstance(result, dict):
+        if "sub_diff" in result:
+            return result["sub_diff"]
+        if "type_change" in result:
+            return DiffResult(type_changes={"root": result["type_change"]})
+        if "set_diff" in result:
+            return DiffResult(
+                added={"root_set_added": result["set_diff"]["added"]},
+                removed={"root_set_removed": result["set_diff"]["removed"]},
+            )
+        return DiffResult(changed={"root": (a, b)})
+    return DiffResult(changed={"root": result})

structmatch-0.1.0/src/structmatch/options.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+
+class MatchOptions:
+    """Options controlling comparison behavior."""
+
+    __slots__ = (
+        "tolerance",
+        "ignore_order",
+        "ignore_keys",
+        "case_sensitive",
+        "type_coerce",
+        "comparators",
+    )
+
+    def __init__(
+        self,
+        tolerance: float = 0.0,
+        ignore_order: bool = False,
+        ignore_keys: set[str] | None = None,
+        case_sensitive: bool = True,
+        type_coerce: bool = False,
+        comparators: list | None = None,
+    ):
+        self.tolerance = tolerance
+        self.ignore_order = ignore_order
+        self.ignore_keys = frozenset(ignore_keys) if ignore_keys else frozenset()
+        self.case_sensitive = case_sensitive
+        self.type_coerce = type_coerce
+        self.comparators = comparators or []
+
+    def update(self, **kwargs) -> MatchOptions:
+        """Return a new MatchOptions with updated fields."""
+        d = {
+            "tolerance": self.tolerance,
+            "ignore_order": self.ignore_order,
+            "ignore_keys": set(self.ignore_keys) if self.ignore_keys else None,
+            "case_sensitive": self.case_sensitive,
+            "type_coerce": self.type_coerce,
+            "comparators": list(self.comparators),
+        }
+        d.update(kwargs)
+        return MatchOptions(**d)