geojson-diff 0.1.0__py3-none-any.whl

geojson_diff/render/text.py

@@ -0,0 +1,85 @@
+"""Human-readable terminal output (ANSI colours optional)."""
+
+from __future__ import annotations
+
+import re
+
+from ..core import DiffResult
+from . import describe_change, format_area, format_length
+
+__all__ = ["render_text"]
+
+_COLORS = {
+    "added": "\x1b[32m",
+    "removed": "\x1b[31m",
+    "modified": "\x1b[33m",
+    "moved": "\x1b[36m",
+    "unchanged": "\x1b[2m",
+    "bold": "\x1b[1m",
+    "dim": "\x1b[2m",
+}
+_RESET = "\x1b[0m"
+_CONTROL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+
+
+def _clean(text: str) -> str:
+    """Neutralise control characters so data cannot inject terminal escapes."""
+    return _CONTROL.sub(lambda m: "\\x%02x" % ord(m.group()), text)
+
+
+_SYMBOLS = {
+    "added": "+",
+    "removed": "-",
+    "modified": "~",
+    "moved": ">",
+    "unchanged": "=",
+}
+
+
+def render_text(result: DiffResult, color: bool = False, show_unchanged: bool = False) -> str:
+    """Plain-text report; ``color=True`` adds ANSI escape codes."""
+
+    def paint(text: str, style: str) -> str:
+        return f"{_COLORS[style]}{text}{_RESET}" if color else text
+
+    c = result.counts
+    lines: list[str] = [
+        paint(_clean(f"geojson-diff {result.old_name} -> {result.new_name}"), "bold"),
+        f"{result.old_count} -> {result.new_count} features: "
+        + ", ".join(
+            paint(f"{c.get(s, 0)} {s}", s) if c.get(s, 0) else f"0 {s}"
+            for s in ("added", "removed", "modified", "moved", "unchanged")
+        ),
+        paint(
+            f"matched by {', '.join(result.options.strategies())}; "
+            f"tolerance {result.options.tolerance}",
+            "dim",
+        ),
+    ]
+    for warning in result.warnings:
+        lines.append(paint(_clean(f"warning: {warning}"), "modified"))
+    shown = [ch for ch in result.changes if show_unchanged or ch.status != "unchanged"]
+    if not result.has_changes:
+        lines.append("")
+        lines.append("No changes.")
+    if shown:
+        lines.append("")
+    width = max((len(ch.key) for ch in shown), default=0)
+    for change in shown:
+        head = f"{_SYMBOLS[change.status]} {change.status:<9} {change.key:<{width}}"
+        if change.geometry_type:
+            head += f"  {change.geometry_type}"
+        lines.append(paint(_clean(head.rstrip()), change.status))
+        for detail in describe_change(change):
+            lines.append(_clean(f"      {detail}"))
+    if result.has_changes:
+        box = result.bbox
+        units = result.units
+        lines.append("")
+        if box:
+            lines.append("bbox of changes: [" + ", ".join(f"{v:.6f}" for v in box) + "]")
+        lines.append(
+            f"area delta {format_area(result.area_delta, units, True)}, "
+            f"length delta {format_length(result.length_delta, units, True)}"
+        )
+    return "\n".join(lines) + "\n"

geojson_diff/tolerance.py

@@ -0,0 +1,86 @@
+"""Distance tolerances such as ``0.5m``, ``2 cm`` or ``1e-6deg``."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Union
+
+__all__ = ["Tolerance", "parse_tolerance"]
+
+_UNIT_FACTORS = {
+    "m": ("m", 1.0),
+    "meter": ("m", 1.0),
+    "meters": ("m", 1.0),
+    "metre": ("m", 1.0),
+    "metres": ("m", 1.0),
+    "km": ("m", 1000.0),
+    "cm": ("m", 0.01),
+    "mm": ("m", 0.001),
+    "ft": ("m", 0.3048),
+    "deg": ("deg", 1.0),
+    "degree": ("deg", 1.0),
+    "degrees": ("deg", 1.0),
+    "°": ("deg", 1.0),
+    "": ("deg", 1.0),
+}
+
+_PATTERN = re.compile(r"^\s*([0-9]*\.?[0-9]+(?:[eE][-+]?[0-9]+)?)\s*([a-zA-Z°]*)\s*$")
+
+
+@dataclass(frozen=True)
+class Tolerance:
+    """A non-negative distance tolerance.
+
+    ``unit`` is ``"m"`` (metres, measured with the haversine formula for
+    longitude/latitude data) or ``"deg"`` (raw coordinate units: degrees for
+    RFC 7946 data, CRS units for projected data).
+    """
+
+    value: float = 0.0
+    unit: str = "m"
+
+    def __post_init__(self) -> None:
+        if self.unit not in ("m", "deg"):
+            raise ValueError(f"unknown tolerance unit {self.unit!r}; use 'm' or 'deg'")
+        if not self.value >= 0.0:  # also rejects NaN
+            raise ValueError("tolerance must be a non-negative number")
+
+    @property
+    def is_metric(self) -> bool:
+        """True when the tolerance is expressed in metres."""
+        return self.unit == "m"
+
+    def __str__(self) -> str:
+        if self.value == 0.0:
+            return "0 (exact)"
+        value = f"{self.value:g}"
+        return f"{value} m" if self.unit == "m" else f"{value} deg"
+
+
+ToleranceLike = Union[Tolerance, str, float, int, None]
+
+
+def parse_tolerance(value: ToleranceLike) -> Tolerance:
+    """Parse ``"0.5m"``, ``"10 cm"``, ``"1km"``, ``"1e-6deg"`` or a bare number.
+
+    A bare number (or a string without unit) is interpreted in coordinate
+    units (degrees for longitude/latitude data).
+    """
+    if value is None:
+        return Tolerance(0.0, "m")
+    if isinstance(value, Tolerance):
+        return value
+    if isinstance(value, bool):
+        raise ValueError("tolerance must be a number or a string such as '0.5m'")
+    if isinstance(value, (int, float)):
+        return Tolerance(float(value), "deg")
+    match = _PATTERN.match(str(value))
+    if not match:
+        raise ValueError(f"invalid tolerance {value!r}; expected e.g. '0.5m', '10cm' or '1e-6deg'")
+    number, unit = match.groups()
+    key = unit.lower()
+    if key not in _UNIT_FACTORS:
+        raise ValueError(f"unknown tolerance unit {unit!r} in {value!r}")
+    canonical, factor = _UNIT_FACTORS[key]
+    return Tolerance(float(number) * factor, canonical)

geojson_diff-0.1.0.dist-info/METADATA

@@ -0,0 +1,478 @@
+Metadata-Version: 2.4
+Name: geojson-diff
+Version: 0.1.0
+Summary: Feature-level diffs of GeoJSON datasets for code review, pull requests and data pipelines: text, JSON, Markdown, GeoJSON and HTML map reports, git diff driver and CI exit codes.
+Author-email: Yusuf Eminoğlu <yusufeminoglu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/geojson_diff_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/geojson_diff_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/geojson_diff_sdk/issues
+Project-URL: Documentation, https://github.com/YusufEminoglu/geojson_diff_sdk#readme
+Project-URL: Changelog, https://github.com/YusufEminoglu/geojson_diff_sdk/blob/main/CHANGELOG.md
+Keywords: geojson,diff,gis,geospatial,git,code-review,pull-request,data-pipeline,ci,geojsonseq,hausdorff,leaflet,change-detection,data-quality
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: shapely
+Requires-Dist: shapely>=2.0.0; extra == "shapely"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# geojson-diff
+
+[![CI](https://github.com/YusufEminoglu/geojson_diff_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/geojson_diff_sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/geojson-diff.svg)](https://pypi.org/project/geojson-diff/)
+[![Python](https://img.shields.io/pypi/pyversions/geojson-diff.svg)](https://pypi.org/project/geojson-diff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Feature-level diffs of GeoJSON datasets** for GIS and data teams that review
+changes in git, pull requests and data pipelines.
+
+A line diff of a GeoJSON file tells you that line 18 412 changed. `geojson-diff`
+tells you that parcel `1042` got a new height, bus stop `77` moved 21 m, three
+buildings were removed and one was added - and it can say so in your terminal, in a
+pull-request comment, on a map, or through an exit code that fails a CI job.
+
+- Diffs **FeatureCollections, GeoJSONSeq (RFC 8142) and newline-delimited GeoJSON**.
+- Matches features **by id, by property key(s), by geometry hash or spatially**
+  (proximity + attribute similarity, deterministic assignment), in a chain.
+- Classifies **added / removed / modified / moved / unchanged**.
+- **Typed, nested property diffs** with JSON Pointer paths.
+- **Tolerance-aware geometry diffs** in metres (haversine) or degrees: Hausdorff
+  distance, vertex-level change counts, area and length deltas, bbox of changes.
+- Outputs **text** (coloured on a TTY), **JSON** (patch-like), **Markdown** (PR
+  comments), a **GeoJSON diff layer** (simplestyle, renders on GitHub) and a
+  self-contained **HTML report with a Leaflet map**.
+- **Git diff driver / textconv**, a `git-geojson-diff REV1 REV2 PATH` helper and
+  **CI exit codes** with `--fail-on` thresholds.
+- **Pure Python standard library**, streaming reader, typed (`py.typed`). Optional
+  `shapely` extra for exact equality and symmetric-difference areas.
+
+## Installation
+
+```bash
+pip install geojson-diff
+pip install "geojson-diff[shapely]"   # optional: exact equality + symmetric-difference area
+```
+
+Python 3.9 or newer. No required dependencies.
+
+## Quick start
+
+```bash
+geojson-diff old.geojson new.geojson [--key id] [--tolerance 0.5m] \
+    [--format text|json|md|geojson|html] [-o out]
+```
+
+Using the two files in [`examples/`](examples):
+
+```console
+$ geojson-diff parcels_v1.geojson parcels_v2.geojson --tolerance 0.5m
+geojson-diff parcels_v1.geojson -> parcels_v2.geojson
+5 -> 5 features: 1 added, 1 removed, 1 modified, 1 moved, 2 unchanged
+matched by id, hash; tolerance 0.5 m
+
++ added     6  Point
+      name: "New cafe"
+      amenity: "cafe"
+- removed   3  Polygon
+      name: "Old shed"
+      height: 3
+~ modified  1  Polygon
+      height: 12 -> 14.5 (integer -> number)
+      tags.use: "residential" -> "mixed"
+      + tags.levels: 4
+> moved     4  LineString
+      + surface: "asphalt"
+      geometry: Hausdorff 21.0 m, centroid shift 5.6 m, vertices 1 moved (4 -> 4), length +3.3 m
+
+bbox of changes: [29.000000, 41.000000, 29.004500, 41.001800]
+area delta -93.5 m2, length delta -35.7 m
+$ echo $?
+1
+```
+
+Bus stop `2` was nudged by about 9 cm, which is inside the 0.5 m tolerance, so it is
+reported as unchanged. Without `--tolerance` the comparison is exact and the stop
+shows up as `moved`.
+
+## How features are classified
+
+| Status | Meaning |
+|---|---|
+| `added` | only in the new file |
+| `removed` | only in the old file |
+| `modified` | matched, properties (or the feature `id`) changed, geometry within tolerance |
+| `moved` | matched, geometry changed beyond the tolerance (property changes are listed too) |
+| `unchanged` | matched, nothing changed |
+
+A geometry is **unchanged** when both versions have the same layout and every vertex
+stayed within the tolerance, or - when the vertex layout differs - when the Hausdorff
+distance between them is within the tolerance. Rotating a ring's start vertex,
+flipping its orientation or inserting a collinear vertex therefore does not count
+as a change. Z values are compared against the tolerance value in metres (exactly
+for degree tolerances).
+
+### Tolerances
+
+| `--tolerance` | Meaning |
+|---|---|
+| `0` (default) | exact comparison |
+| `0.5m`, `10cm`, `5mm`, `1km`, `2ft` | metres; haversine on longitude/latitude data |
+| `1e-6deg`, `0.00001°`, `0.00001` | coordinate units (degrees for RFC 7946 data) |
+
+Longitude/latitude data is detected automatically; projected data (coordinates
+outside +-180/+-90, or `--crs projected`) is measured in CRS units and reported with
+`units` instead of metres.
+
+### Matching strategies
+
+`--match` takes an ordered chain; features that one strategy cannot match are offered
+to the next.
+
+| Strategy | Matches on | Notes |
+|---|---|---|
+| `id` | the feature's top-level `id` | `1` and `"1"` are the same key |
+| `key` | one or more properties (`--key parcel_id`, `--key block --key lot`) | dotted paths for nested keys (`meta.ref`); `id` falls back to the feature id, `@id` always means the feature id |
+| `hash` | a normalised geometry hash | rounded to `--precision` decimals (7); insensitive to ring start, orientation and part order |
+| `spatial` | centroid proximity + attribute similarity | `--max-distance 50m`, `--attribute-weight 0.5`, `--min-score 0.5`; same geometry family only |
+| `auto` (default) | `key` if `--key` is given, else `id` then `hash` | |
+
+Spatial matching scores every candidate pair as
+`(1 - w) * (1 - distance / max_distance) + w * similarity` and assigns pairs greedily
+by score, then distance, then input order, so the result is always the same for the
+same inputs. Duplicate keys are paired in input order and reported as warnings.
+
+```bash
+geojson-diff old.geojson new.geojson --key parcel_id
+geojson-diff old.geojson new.geojson --key block,lot --ignore-property updated_at
+geojson-diff old.geojson new.geojson --match id,hash,spatial --max-distance 25m
+```
+
+### Property diffs
+
+Nested objects are compared key by key and equal-length arrays element by element;
+paths are RFC 6901 JSON Pointers (`/properties/tags/0`). `1` and `1.0` are equal
+unless `--strict-types` is given; `true` and `1`, or `"1"` and `1`, never are, and
+type changes are reported (`integer -> number`). `--ignore-property` (repeatable,
+dotted for nested keys) skips noisy attributes such as timestamps.
+
+## Output formats
+
+`--format` (or the extension of `-o`) selects the output:
+
+| Format | Use |
+|---|---|
+| `text` | terminal; coloured when stdout is a TTY (`--color`, `NO_COLOR`, `FORCE_COLOR`) |
+| `json` | machine-readable, JSON-Patch-like |
+| `md` | pull-request comments and CI job summaries |
+| `geojson` | a diff layer for QGIS, geojson.io or GitHub's map viewer |
+| `html` | a single-file report with a Leaflet before/after map |
+
+### Markdown
+
+```console
+$ geojson-diff parcels_v1.geojson parcels_v2.geojson -t 0.5m -f md
+```
+
+```markdown
+### GeoJSON diff: parcels&#95;v1.geojson → parcels&#95;v2.geojson
+
+**4 feature changes** (5 → 5 features; matched by id, hash; tolerance 0.5 m)
+
+| Added | Removed | Modified | Moved | Unchanged |
+|---:|---:|---:|---:|---:|
+| 1 | 1 | 1 | 1 | 2 |
+
+bbox of changes 29.000000, 41.000000, 29.004500, 41.001800 · area Δ -93.5 m² · length Δ -35.7 m
+
+<details open><summary>Feature changes (4)</summary>
+
+| Change | Feature | Geometry | Details |
+|---|---|---|---|
+| added | 6 | Point | name: "New cafe"<br>amenity: "cafe" |
+| removed | 3 | Polygon | name: "Old shed"<br>height: 3 |
+| modified | 1 | Polygon | height: 12 → 14.5 (integer → number)<br>tags.use: "residential" → "mixed"<br>+ tags.levels: 4 |
+| moved | 4 | LineString | + surface: "asphalt"<br>geometry: Hausdorff 21.0 m, centroid shift 5.6 m, vertices 1 moved (4 → 4), length +3.3 m |
+
+</details>
+
+<sub>Generated by geojson-diff</sub>
+```
+
+Every data value is escaped (HTML entities for Markdown syntax, `@` and `#`), so a
+property value cannot inject markup, links, table columns or user mentions.
+`--md-map` appends the diff layer as a ` ```geojson ` block, which GitHub renders as
+an interactive map; `--max-rows` limits the table.
+
+### JSON
+
+```console
+$ geojson-diff parcels_v1.geojson parcels_v2.geojson -t 0.5m -f json
+```
+
+The document holds `options`, a `summary` and one entry per change. Property changes
+use JSON Patch vocabulary with the old value and JSON types added:
+
+```json
+{
+  "op": "modify",
+  "status": "modified",
+  "key": "1",
+  "old_index": 0,
+  "new_index": 0,
+  "matched_by": "id",
+  "patch": [
+    {"op": "replace", "path": "/properties/height", "old": 12, "old_type": "integer",
+     "value": 14.5, "new_type": "number"},
+    {"op": "replace", "path": "/properties/tags/use", "old": "residential",
+     "old_type": "string", "value": "mixed", "new_type": "string"},
+    {"op": "add", "path": "/properties/tags/levels", "value": 4, "new_type": "integer"}
+  ],
+  "geometry": {"changed": false, "old_type": "Polygon", "new_type": "Polygon",
+               "units": "m", "vertices": 4},
+  "area_delta": 0.0,
+  "length_delta": 0.0,
+  "bbox": [29.001, 41.001, 29.0014, 41.0013]
+}
+```
+
+`moved` entries add `{"op": "replace", "path": "/geometry", ...}` to the patch and a
+`geometry` block with `hausdorff`, `max_vertex_shift`, `centroid_shift`,
+`vertices_added/removed/moved`, `area_old/new/delta`, `length_old/new/delta`, `bbox`
+and (with `--shapely`) `symmetric_difference_area`. `added` / `removed` entries carry
+the whole feature.
+
+### GeoJSON diff layer
+
+`-f geojson` writes a FeatureCollection in which every changed feature is styled with
+[simplestyle-spec](https://github.com/mapbox/simplestyle-spec) properties (`stroke`,
+`fill`, `fill-opacity`, `marker-color`, `title`, `description`) - green for added,
+red for removed, orange for modified, blue for moved, with a grey `before` outline for
+moved features. GitHub renders `.geojson` files with that styling. The change itself
+is described by `diff:status`, `diff:role` (`change` or `before`), `diff:key`,
+`diff:changed` and `diff:hausdorff`.
+
+### HTML report
+
+```bash
+geojson-diff old.geojson new.geojson -t 0.5m -o review.html
+```
+
+A single file with summary cards, a Leaflet map (before and after layers, popups) and
+a table of changes. Leaflet 1.9.4 is loaded from unpkg with Subresource Integrity and
+OpenStreetMap tiles are attributed. Data is embedded as escaped JSON and rendered
+with `textContent`, and the table is HTML-escaped, so hostile property values cannot
+run script. The OpenStreetMap tile servers may refuse requests from `file://` pages
+that send no referrer; serve the report over HTTP (for example as a CI artifact or
+`python -m http.server`) or pass your own tile server through the Python API
+(`render(result, "html", tiles=..., attribution=...)`).
+
+## Git integration
+
+### Readable `git diff` with a textconv filter
+
+`--textconv` prints a stable, line-per-attribute rendering (features sorted by id,
+properties sorted by key, coordinates rounded), so the ordinary line diff becomes
+meaningful. Tell git which files to treat this way in `.gitattributes`:
+
+```gitattributes
+*.geojson  diff=geojson
+*.geojsons diff=geojson
+```
+
+and define the `geojson` diff driver once in your git configuration (run this
+yourself; it is per repository unless you add `--global`):
+
+```bash
+git config diff.geojson.textconv "geojson-diff --textconv"
+git config diff.geojson.cachetextconv true
+```
+
+### Feature-level `git diff` with an external diff driver
+
+Instead of (or as well as) textconv, git can hand both versions to `geojson-diff`:
+
+```bash
+git config diff.geojson.command "geojson-diff --git --tolerance 0.5m"
+git diff                 # uses the driver for *.geojson
+git log -p --ext-diff -- data/parcels.geojson
+git diff --no-ext-diff   # plain line diff when you need it
+```
+
+Git calls the command with `path old-file old-hex old-mode new-file new-hex new-mode`
+(nine arguments for renames); `/dev/null` stands for the missing side of an added or
+deleted file. In this mode `geojson-diff` always exits 0 unless the input is broken,
+because git aborts the whole diff when an external driver fails. Any option can be
+added to the command (`--key`, `--format md`, ...).
+
+### Diffing revisions: `git-geojson-diff`
+
+```bash
+git-geojson-diff HEAD~1 HEAD data/parcels.geojson
+git-geojson-diff main data/parcels.geojson             # main vs. working tree
+git geojson-diff v1.2 v1.3 data/parcels.geojson --format html -o review.html
+```
+
+Because the script is on your `PATH` as `git-geojson-diff`, git also runs it as
+`git geojson-diff`. A file missing at one revision counts as empty, so added and
+deleted files work. It takes every `geojson-diff` option and uses the same exit codes.
+
+## CI usage
+
+| Exit code | Meaning |
+|---|---|
+| `0` | no changes (or none above the `--fail-on` thresholds) |
+| `1` | changes found |
+| `2` | error (unreadable or invalid input, bad arguments) |
+
+```bash
+geojson-diff old.geojson new.geojson --fail-on removed            # fail only on removals
+geojson-diff old.geojson new.geojson --fail-on removed:10,moved:0 # allow up to 10 removals
+geojson-diff old.geojson new.geojson --fail-on any:5 -q           # any category above 5
+geojson-diff old.geojson new.geojson --exit-zero -f md >> "$GITHUB_STEP_SUMMARY"
+```
+
+`--fail-on` takes `added`, `removed`, `modified`, `moved` or `any`, each with an
+optional `:N` allowance (exit 1 when the count exceeds N; default 0).
+
+### GitHub Actions: post the summary on pull requests
+
+[`examples/github-actions/geojson-diff.yml`](examples/github-actions/geojson-diff.yml)
+diffs every changed `*.geojson` file between the pull-request base and head, posts a
+single Markdown comment (updated on later pushes), copies it to the job summary and
+fails the check when features were removed. The core of it:
+
+```yaml
+      - name: Diff changed GeoJSON files
+        id: diff
+        shell: bash
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          set +e  # exit status 1 means "changes found", not a failure of this step
+          status=0
+          : > geojson-diff.md
+          while IFS= read -r -d '' path; do
+            git-geojson-diff "$BASE_SHA" HEAD "$path" \
+              --format md --title "GeoJSON diff: $path" \
+              --tolerance 0.5m --fail-on removed --max-rows 50 >> geojson-diff.md
+            rc=$?
+            echo >> geojson-diff.md
+            if [ "$rc" -eq 2 ]; then echo "::error file=$path::geojson-diff failed"; status=2; fi
+            if [ "$rc" -eq 1 ] && [ "$status" -eq 0 ]; then status=1; fi
+          done < <(git diff -z --name-only "$BASE_SHA" HEAD -- '*.geojson' '*.geojsons')
+          cat geojson-diff.md >> "$GITHUB_STEP_SUMMARY"
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+      - name: Post the summary on the pull request
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: gh pr comment "$PR" --body-file geojson-diff.md --edit-last --create-if-none
+```
+
+The checkout needs `fetch-depth: 0` and the job `pull-requests: write`; see the full
+file for the remaining steps.
+
+## Python API
+
+```python
+from geojson_diff import DiffOptions, diff, render, diff_layer
+
+result = diff(
+    "old.geojson",
+    "new.geojson",
+    keys=["parcel_id"],              # or match=["id", "hash", "spatial"]
+    tolerance="0.5m",
+    ignore_properties=["updated_at"],
+)
+
+print(result.counts)        # e.g. {'added': 1, 'removed': 1, 'modified': 1, 'moved': 1, 'unchanged': 2}
+print(result.has_changes, result.bbox, result.area_delta)
+
+for change in result.changes:            # unchanged features are kept with keep_unchanged=True
+    print(change.status, change.key, change.matched_by)
+    for prop in change.properties:
+        print("  ", prop.op, prop.path, prop.old, "->", prop.new, prop.old_type, prop.new_type)
+    if change.geometry and change.geometry.changed:
+        print("   hausdorff", change.geometry.hausdorff, "m")
+
+markdown = render(result, "md", max_rows=50)
+html = render(result, "html", title="Parcel update 2026-11")
+layer = diff_layer(result)                    # dict, ready for json.dump
+payload = result.to_dict()                    # the JSON output as a dict
+```
+
+`diff()` accepts paths, `"-"` (stdin), open files, parsed GeoJSON objects or plain
+iterables of features. Lower-level helpers are public as well:
+`compare_features`, `compare_geometry`, `diff_properties`, `hausdorff_distance`,
+`haversine`, `geometry_area`, `geometry_length`, `geometry_hash`, `iter_features`,
+`parse_tolerance`.
+
+## Large files
+
+The reader decodes one feature at a time: the `features` array of a
+FeatureCollection is streamed, as are GeoJSONSeq and newline-delimited files. The
+old file is indexed by key; when the first strategy is `id`, `key` or `hash`, the new
+file is streamed against that index and unchanged features are dropped as soon as
+they are compared, so memory grows with the old file plus the changes. Geometry
+metrics are computed only for geometries that actually changed. On a laptop, two
+66 MB FeatureCollections with 100 000 polygons each diff in about 8 seconds, most of
+it JSON decoding.
+
+## Optional shapely extra
+
+With `pip install "geojson-diff[shapely]"` and `--shapely` (`use_shapely=True`):
+
+- with an exact tolerance (`0`), geometries are compared for topological equality
+  (`shapely.equals`), and
+- moved polygons report `symmetric_difference_area` (square metres via a local
+  projection for longitude/latitude data).
+
+## Limitations
+
+- The Hausdorff distance is measured from every vertex to the other geometry's
+  segments in both directions. It is exact for points; for lines and polygons it can
+  slightly underestimate when the farthest point lies inside an edge rather than at a
+  vertex.
+- Areas use a spherical model (WGS84 semi-major axis), accurate to well under 1 % for
+  the parcel- to city-scale changes reviewed in practice.
+- `moved` means "geometry changed beyond tolerance"; a reshaped polygon is `moved` too.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev,shapely]"
+python -m pytest --cov=geojson_diff
+python -m ruff check . && python -m ruff format --check src tests
+python -m mypy src
+```
+
+## License and citation
+
+MIT License - see [LICENSE](LICENSE). If you use `geojson-diff` in research, please
+cite it using [CITATION.cff](CITATION.cff).
+
+Author: Yusuf Eminoğlu

geojson_diff-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+geojson_diff/__init__.py,sha256=dOEg1Pw1JxbULmu4N1sDGIjUbW_hHoX8Fr9Sr5Gk6tk,1386
+geojson_diff/__main__.py,sha256=XkAN6lVXvAInTY92AAvrqWT5DXFt_jZNad0PKgMPl9U,87
+geojson_diff/_shapely.py,sha256=2PhboAt6g9nMti4cHLmkFWxU_TdQrwwX_QprwSA0ZFA,2729
+geojson_diff/cli.py,sha256=dvBbCKn6RLzq5VwgHq8EFeFm501fJ4K-sWbSjirUiNk,12946
+geojson_diff/core.py,sha256=8q0biPJaQtkyXFulqQhCMFpP_6Gg3apqc-AjGLAC6Eo,23302
+geojson_diff/geometry.py,sha256=JmPZ0bPgpQ6rzcZHwG5u6XDVmEy-PMaseOAfn9qbtM8,15358
+geojson_diff/git.py,sha256=xFvW1sBvKOlvop-Ot9IPV0G6hmCdd56eiMma70BEn9c,4475
+geojson_diff/io.py,sha256=4JGfrYv4F4WonSuUE8lT6opSweMT3sUWHJAGbwCwDaQ,9114
+geojson_diff/matching.py,sha256=UABOR2v3YumHSpSHgXmeFBVujrcwLFNSw7R6iQ4n0MI,7489
+geojson_diff/properties.py,sha256=S1br5awlPE3boUTiO1IqVV8oDg6Mg1pCfAf6xJgqpJc,6809
+geojson_diff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+geojson_diff/tolerance.py,sha256=4NXLeMhmoM48o3VkKfirpv6X56MfRfbUeOlGyHDMjbg,2709
+geojson_diff/render/__init__.py,sha256=BPSFZzlgT6kOyERzfw4kX3RTJzLrRSe0jXLrUv7tqGk,5218
+geojson_diff/render/html.py,sha256=qPJhWUWRsKukKfTSvfmiNG14c6X_qx_Lk66n2Iot4ZI,9175
+geojson_diff/render/layer.py,sha256=Yis37Qisz7uBmVY9vSKAMcJN5EnbNYRpcPE2WQ4gHTY,3883
+geojson_diff/render/machine.py,sha256=ujN85ejtKuoRe5e_gzksGX2aSBORjMYH7coc0WX1lDc,651
+geojson_diff/render/markdown.py,sha256=I4OLKY2IQ5kla5Zy7SMN7ltRxEYMwMmFGhYSwjCOor0,4982
+geojson_diff/render/text.py,sha256=HzsHINxBnZW6gbiPcXbSbTu5LxKH-kzFr1Q_GATj25E,2791
+geojson_diff-0.1.0.dist-info/licenses/LICENSE,sha256=Z9meOk3opsRgHOqC5mA4B8NjZoU5WU1Kqhn82FL4ICs,1072
+geojson_diff-0.1.0.dist-info/METADATA,sha256=4qsdgHG_2onZWKm9iWMf3lYmv2jqi1J7EsIDvmY0rJM,20378
+geojson_diff-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+geojson_diff-0.1.0.dist-info/entry_points.txt,sha256=lbXwh6LungdWgTDcvpW07SfebZ2OwnUrVhME6J3_jtk,100
+geojson_diff-0.1.0.dist-info/top_level.txt,sha256=NmzaTZ_Xyr3dSayx7gRNX3onkpg3V5Ih2jQgU5j1B-0,13
+geojson_diff-0.1.0.dist-info/RECORD,,

geojson_diff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

geojson_diff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+geojson-diff = geojson_diff.cli:main
+git-geojson-diff = geojson_diff.cli:git_main