geojson-diff 0.1.0__py3-none-any.whl

geojson_diff/__init__.py

@@ -0,0 +1,60 @@
+"""geojson-diff: feature-level diffs of GeoJSON datasets for reviews, PRs and pipelines.
+
+>>> from geojson_diff import diff
+>>> result = diff("old.geojson", "new.geojson", keys=["parcel_id"], tolerance="0.5m")  # doctest: +SKIP
+>>> result.counts  # doctest: +SKIP
+{'added': 2, 'removed': 1, 'modified': 3, 'moved': 1, 'unchanged': 6}
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .core import (
+    STATUSES,
+    DiffOptions,
+    DiffResult,
+    FeatureChange,
+    GeometryDiff,
+    compare_features,
+    compare_geometry,
+    diff,
+)
+from .geometry import (
+    geometry_area,
+    geometry_hash,
+    geometry_length,
+    hausdorff_distance,
+    haversine,
+)
+from .io import GeoJSONError, iter_features, load_features
+from .properties import PropertyChange, diff_properties
+from .render import render
+from .render.layer import diff_layer
+from .tolerance import Tolerance, parse_tolerance
+
+__all__ = [
+    "STATUSES",
+    "DiffOptions",
+    "DiffResult",
+    "FeatureChange",
+    "GeoJSONError",
+    "GeometryDiff",
+    "PropertyChange",
+    "Tolerance",
+    "__version__",
+    "compare_features",
+    "compare_geometry",
+    "diff",
+    "diff_layer",
+    "diff_properties",
+    "geometry_area",
+    "geometry_hash",
+    "geometry_length",
+    "hausdorff_distance",
+    "haversine",
+    "iter_features",
+    "load_features",
+    "parse_tolerance",
+    "render",
+]

geojson_diff/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m geojson_diff``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

geojson_diff/_shapely.py

@@ -0,0 +1,80 @@
+"""Optional exact geometry operations backed by shapely (``pip install geojson-diff[shapely]``)."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+__all__ = ["HAS_SHAPELY", "exact_equal", "symmetric_difference_area"]
+
+try:  # pragma: no cover - depends on the environment
+    import shapely
+    from shapely.geometry import shape
+
+    HAS_SHAPELY = True
+except ImportError:  # pragma: no cover - depends on the environment
+    HAS_SHAPELY = False
+
+_M_PER_DEG = math.pi * 6371008.8 / 180.0
+
+
+def _require() -> None:
+    if not HAS_SHAPELY:  # pragma: no cover - depends on the environment
+        raise ImportError("this feature needs shapely: pip install 'geojson-diff[shapely]'")
+
+
+def _project(obj: Any, lat0: float) -> Any:
+    k = math.cos(math.radians(lat0)) * _M_PER_DEG
+    if isinstance(obj, list) and obj and isinstance(obj[0], (int, float)):
+        return [obj[0] * k, obj[1] * _M_PER_DEG] + list(obj[2:])
+    if isinstance(obj, list):
+        return [_project(o, lat0) for o in obj]
+    return obj
+
+
+def _local(geom: dict[str, Any], lat0: float | None) -> dict[str, Any]:
+    if lat0 is None:
+        return geom
+    if geom.get("type") == "GeometryCollection":
+        members: list[dict[str, Any]] = [_local(g, lat0) for g in geom.get("geometries") or []]
+        return {"type": "GeometryCollection", "geometries": members}
+    return {
+        "type": geom["type"],
+        "coordinates": _project(geom.get("coordinates"), lat0),
+    }
+
+
+def _lat0(*geoms: dict[str, Any]) -> float:
+    lats: list[float] = []
+    for geom in geoms:
+        b = shape(geom).bounds
+        if b and not any(math.isnan(v) for v in b):
+            lats.extend([b[1], b[3]])
+    return (min(lats) + max(lats)) / 2.0 if lats else 0.0
+
+
+def symmetric_difference_area(
+    old: dict[str, Any], new: dict[str, Any], geographic: bool = True
+) -> float | None:
+    """Area of ``old XOR new`` in square metres (lon/lat, local projection) or CRS units.
+
+    Returns ``None`` for non-areal geometries or when shapely cannot compute it.
+    """
+    _require()
+    lat0 = _lat0(old, new) if geographic else None
+    a, b = shape(_local(old, lat0)), shape(_local(new, lat0))
+    if a.area == 0.0 and b.area == 0.0:
+        return None
+    try:
+        return float(a.symmetric_difference(b).area)
+    except Exception:  # pragma: no cover - invalid geometries
+        try:
+            return float(shapely.make_valid(a).symmetric_difference(shapely.make_valid(b)).area)
+        except Exception:
+            return None
+
+
+def exact_equal(old: dict[str, Any], new: dict[str, Any]) -> bool:
+    """Topological equality (same point set) according to shapely."""
+    _require()
+    return bool(shape(old).equals(shape(new)))

geojson_diff/cli.py

@@ -0,0 +1,374 @@
+"""Command-line interface: ``geojson-diff`` and ``git-geojson-diff``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from typing import TextIO
+
+from . import __version__
+from .core import DiffOptions, DiffResult, diff
+from .io import GeoJSONError, Source
+from .render import FORMATS, render
+
+__all__ = ["EXIT_CHANGES", "EXIT_ERROR", "EXIT_OK", "git_main", "main", "parse_fail_on"]
+
+EXIT_OK = 0
+EXIT_CHANGES = 1
+EXIT_ERROR = 2
+
+_CATEGORIES = ("added", "removed", "modified", "moved")
+_EXTENSIONS = {
+    ".json": "json",
+    ".md": "md",
+    ".markdown": "md",
+    ".geojson": "geojson",
+    ".html": "html",
+    ".htm": "html",
+    ".txt": "text",
+}
+
+
+def parse_fail_on(spec: str | None) -> dict[str, int]:
+    """Parse ``removed,modified`` or ``removed:10,moved:0`` into allowed counts.
+
+    Each listed category fails the run when its count exceeds the number
+    after the colon (default 0). ``any`` stands for all four categories.
+    """
+    if not spec:
+        return {}
+    limits: dict[str, int] = {}
+    for item in spec.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        name, _, raw = item.partition(":")
+        name = name.strip().lower()
+        try:
+            allowed = int(raw) if raw.strip() else 0
+        except ValueError:
+            raise ValueError(f"invalid --fail-on threshold in {item!r}") from None
+        if allowed < 0:
+            raise ValueError(f"--fail-on threshold must be >= 0 in {item!r}")
+        names = _CATEGORIES if name in ("any", "all", "changed") else (name,)
+        for n in names:
+            if n not in _CATEGORIES:
+                raise ValueError(
+                    f"unknown --fail-on category {name!r}; use {', '.join(_CATEGORIES)} or any"
+                )
+            limits[n] = allowed
+    return limits
+
+
+def exit_code(result: DiffResult, fail_on: dict[str, int]) -> int:
+    """0 when nothing (relevant) changed, 1 otherwise."""
+    if not fail_on:
+        return EXIT_CHANGES if result.has_changes else EXIT_OK
+    for name, allowed in fail_on.items():
+        if result.counts.get(name, 0) > allowed:
+            return EXIT_CHANGES
+    return EXIT_OK
+
+
+def _add_diff_options(parser: argparse.ArgumentParser) -> None:
+    m = parser.add_argument_group("matching")
+    m.add_argument(
+        "-k",
+        "--key",
+        action="append",
+        default=[],
+        metavar="PROP",
+        help="match on property PROP (repeat or comma-separate for a composite key; "
+        "dotted for nested; 'id' falls back to the feature id, '@id' is the feature id)",
+    )
+    m.add_argument(
+        "-m",
+        "--match",
+        default="auto",
+        metavar="STRATEGIES",
+        help="comma-separated chain of id, key, hash, spatial (default: auto = key if --key "
+        "is given, else id,hash)",
+    )
+    m.add_argument(
+        "--max-distance",
+        default="50m",
+        metavar="DIST",
+        help="spatial matching: maximum centroid distance (default 50m)",
+    )
+    m.add_argument(
+        "--attribute-weight",
+        type=float,
+        default=0.5,
+        metavar="W",
+        help="spatial matching: weight of attribute similarity in [0, 1] (default 0.5)",
+    )
+    m.add_argument(
+        "--min-score",
+        type=float,
+        default=0.5,
+        metavar="S",
+        help="spatial matching: minimum pair score in [0, 1] (default 0.5)",
+    )
+    m.add_argument(
+        "--precision",
+        type=int,
+        default=7,
+        metavar="N",
+        help="decimals kept when hashing geometries (default 7)",
+    )
+    c = parser.add_argument_group("comparison")
+    c.add_argument(
+        "-t",
+        "--tolerance",
+        default="0",
+        metavar="TOL",
+        help="geometry tolerance, e.g. 0.5m, 10cm, 1e-6deg (default 0: exact)",
+    )
+    c.add_argument(
+        "--crs",
+        choices=("auto", "geographic", "projected"),
+        default="auto",
+        help="coordinate type (default auto: lon/lat when all coordinates fit)",
+    )
+    c.add_argument(
+        "-i",
+        "--ignore-property",
+        action="append",
+        default=[],
+        metavar="PROP",
+        help="ignore property PROP (repeatable, dotted for nested keys)",
+    )
+    c.add_argument(
+        "--strict-types",
+        action="store_true",
+        help="treat 1 and 1.0 as different values",
+    )
+    c.add_argument(
+        "--shapely",
+        action="store_true",
+        help="use shapely (optional extra) for exact equality and symmetric-difference area",
+    )
+    o = parser.add_argument_group("output")
+    o.add_argument("-f", "--format", choices=FORMATS, help="output format (default text)")
+    o.add_argument("-o", "--output", metavar="FILE", help="write the report to FILE")
+    o.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="colour text output (default auto: when stdout is a terminal)",
+    )
+    o.add_argument("--show-unchanged", action="store_true", help="list unchanged features too")
+    o.add_argument("--max-rows", type=int, default=100, metavar="N", help="rows in md tables")
+    o.add_argument("--title", default="", help="title for md/html reports")
+    o.add_argument(
+        "--md-map",
+        action="store_true",
+        help="append a ```geojson map block to md output (GitHub renders it)",
+    )
+    o.add_argument("-q", "--quiet", action="store_true", help="print nothing; exit code only")
+    x = parser.add_argument_group("exit status")
+    x.add_argument(
+        "--fail-on",
+        metavar="LIST",
+        help="exit 1 only when these categories exceed their thresholds, "
+        "e.g. 'removed,modified' or 'removed:10,moved:0' (default: any change)",
+    )
+    x.add_argument("--exit-zero", action="store_true", help="always exit 0 unless an error occurs")
+
+
+def _options(args: argparse.Namespace) -> DiffOptions:
+    keys: list[str] = []
+    for item in args.key:
+        keys.extend(k.strip() for k in item.split(",") if k.strip())
+    geographic = {"auto": None, "geographic": True, "projected": False}[args.crs]
+    return DiffOptions(
+        match=args.match,
+        keys=keys,
+        tolerance=args.tolerance,
+        geographic=geographic,
+        precision=args.precision,
+        strict_types=args.strict_types,
+        ignore_properties=list(args.ignore_property),
+        max_distance=args.max_distance,
+        attribute_weight=args.attribute_weight,
+        min_score=args.min_score,
+        keep_unchanged=args.show_unchanged,
+        use_shapely=args.shapely,
+    )
+
+
+def _enable_windows_ansi() -> None:  # pragma: no cover - Windows console only
+    if os.name != "nt":
+        return
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.GetStdHandle(-11)
+        mode = ctypes.c_uint32()
+        if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    except Exception:
+        pass
+
+
+def _use_color(choice: str, stream: TextIO) -> bool:
+    if choice == "always":
+        return True
+    if choice == "never":
+        return False
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+def _emit(text: str, output: str | None) -> None:
+    if output:
+        with open(output, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+        return
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            if sys.stdout.isatty():
+                reconfigure(errors="replace")
+            else:  # pipes and redirections (CI logs, '> report.md') get UTF-8
+                reconfigure(encoding="utf-8")
+        except Exception:  # pragma: no cover - exotic streams
+            pass
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+def _report(result: DiffResult, args: argparse.Namespace, force_text: bool = False) -> None:
+    fmt = args.format
+    if fmt is None and args.output and not force_text:
+        fmt = _EXTENSIONS.get(os.path.splitext(args.output)[1].lower(), "text")
+    fmt = fmt or "text"
+    if fmt == "text":
+        color = False if args.output else _use_color(args.color, sys.stdout)
+        if color:
+            _enable_windows_ansi()
+        text = render(result, "text", color=color, show_unchanged=args.show_unchanged)
+    elif fmt == "md":
+        text = render(
+            result,
+            "md",
+            max_rows=args.max_rows,
+            title=args.title,
+            include_map=args.md_map,
+        )
+    elif fmt == "html":
+        text = render(result, "html", title=args.title)
+    elif fmt == "geojson":
+        text = render(result, "geojson", include_unchanged=args.show_unchanged)
+    else:
+        text = render(result, "json")
+    if not args.quiet:
+        _emit(text, args.output)
+
+
+def _run(old: Source, new: Source, args: argparse.Namespace) -> int:
+    fail_on = parse_fail_on(args.fail_on)
+    result = diff(old, new, _options(args))
+    _report(result, args)
+    if args.exit_zero:
+        return EXIT_OK
+    return exit_code(result, fail_on)
+
+
+def _error(prog: str, exc: BaseException) -> int:
+    sys.stderr.write(f"{prog}: error: {exc}\n")
+    return EXIT_ERROR
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="geojson-diff",
+        description="Diff two GeoJSON FeatureCollections (or GeoJSONSeq files) feature by "
+        "feature. Exit status: 0 no changes, 1 changes, 2 error.",
+        epilog="Git: 'geojson-diff --textconv FILE' prints a diff-friendly rendering; "
+        "'geojson-diff --git ...' is an external diff driver (diff.<name>.command).",
+    )
+    parser.add_argument("paths", nargs="*", metavar="PATH", help="OLD and NEW files ('-' = stdin)")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--textconv",
+        action="store_true",
+        help="print a stable line-per-attribute rendering of one file (git textconv)",
+    )
+    mode.add_argument(
+        "--git",
+        action="store_true",
+        help="act as a git external diff driver (git passes 7 or 9 arguments)",
+    )
+    _add_diff_options(parser)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point of ``geojson-diff``."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.textconv:
+            if len(args.paths) != 1:
+                parser.error("--textconv takes exactly one file")
+            from .git import textconv
+
+            _emit(textconv(args.paths[0], args.precision), args.output)
+            return EXIT_OK
+        if args.git:
+            from .git import driver_sources
+
+            old_path, new_path, old, new = driver_sources(list(args.paths))
+            result = diff(old, new, _options(args))
+            result.old_name, result.new_name = f"a/{old_path}", f"b/{new_path}"
+            _report(result, args)
+            # git aborts the whole diff when an external driver exits non-zero.
+            return EXIT_OK
+        if len(args.paths) != 2:
+            parser.error("expected two files: OLD NEW")
+        return _run(args.paths[0], args.paths[1], args)
+    except (GeoJSONError, OSError, ValueError, KeyError, TypeError) as exc:
+        return _error("geojson-diff", exc)
+
+
+def git_main(argv: Sequence[str] | None = None) -> int:
+    """Entry point of ``git-geojson-diff REV1 [REV2] PATH``."""
+    parser = argparse.ArgumentParser(
+        prog="git-geojson-diff",
+        description="Diff a GeoJSON file between two git revisions (REV2 defaults to the "
+        "working tree). Also available as 'git geojson-diff'. Exit status: 0 no changes, "
+        "1 changes, 2 error.",
+    )
+    parser.add_argument("revs", nargs="+", metavar="ARG", help="REV1 [REV2] PATH")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    _add_diff_options(parser)
+    args = parser.parse_args(argv)
+    if len(args.revs) not in (2, 3):
+        parser.error("expected REV1 [REV2] PATH")
+    from .git import read_revision
+
+    try:
+        path = args.revs[-1]
+        old = read_revision(args.revs[0], path)
+        if len(args.revs) == 3:
+            new = read_revision(args.revs[1], path)
+        else:
+            new = path
+        return _run(old, new, args)
+    except (GeoJSONError, OSError, ValueError, KeyError, TypeError) as exc:
+        return _error("git-geojson-diff", exc)
+    except Exception as exc:  # subprocess timeouts and the like
+        return _error("git-geojson-diff", exc)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())