geojson-diff 0.1.0__tar.gz

geojson_diff-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+### Added
+- **Diff engine** (`geojson_diff.diff`): compares two GeoJSON FeatureCollections,
+  GeoJSONSeq (RFC 8142) or newline-delimited GeoJSON files feature by feature and
+  classifies every feature as `added`, `removed`, `modified` (properties only),
+  `moved` (geometry changed beyond the tolerance) or `unchanged`.
+- **Matching strategies**, chainable in order: feature `id`, property `key`(s)
+  (composite and dotted nested keys), normalised geometry `hash` and `spatial`
+  (centroid proximity plus attribute similarity with a deterministic greedy
+  assignment). `auto` uses `key` when keys are given, else `id` then `hash`.
+- **Property diff**: nested objects and arrays with RFC 6901 paths, JSON type
+  tracking (`integer -> number`), `--strict-types`, ignored properties.
+- **Geometry diff**: tolerance in metres (haversine) or degrees, Hausdorff
+  distance (pure Python, early-break), vertex added/removed/moved counts,
+  centroid shift, area and length deltas (spherical), bounding box of changes;
+  ring rotation, orientation and collinear extra vertices do not count as changes.
+- **Outputs**: coloured terminal text, JSON-Patch-like machine output, Markdown
+  for pull-request comments (optional `geojson` map block), a GeoJSON diff layer
+  styled with simplestyle-spec properties and a self-contained HTML report with a
+  Leaflet before/after map. All data values are escaped.
+- **Git integration**: `geojson-diff --textconv` and `geojson-diff --git`
+  (external diff driver) plus the `git-geojson-diff REV1 [REV2] PATH` helper.
+- **CI**: exit codes 0 / 1 / 2, `--fail-on removed,moved:5`, `--exit-zero` and a
+  GitHub Actions example that posts the Markdown summary on pull requests.
+- **Streaming reader**: features are decoded one at a time; with an indexable first
+  strategy the new file is streamed against an index of the old one.
+- Optional `shapely` extra for topological equality and symmetric-difference area.
+
+[Unreleased]: https://github.com/YusufEminoglu/geojson_diff_sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/YusufEminoglu/geojson_diff_sdk/releases/tag/v0.1.0

geojson_diff-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "yusufeminoglu@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "geojson-diff"
+version: "0.1.0"
+date-released: "2026-11-08"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/geojson_diff_sdk"
+url: "https://pypi.org/project/geojson-diff/"
+abstract: "Feature-level diffs of GeoJSON datasets for code review, pull requests and data pipelines, with tolerance-aware geometry comparison, typed property diffs, text/JSON/Markdown/GeoJSON/HTML reports, a git diff driver and CI exit codes."
+keywords:
+  - geojson
+  - diff
+  - gis
+  - git
+  - code review
+  - data pipelines

geojson_diff-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geojson_diff-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/geojson_diff/py.typed
+recursive-include src/geojson_diff *.py
+recursive-include tests *.py
+recursive-include examples *.geojson *.yml

geojson_diff-0.1.0/PKG-INFO

@@ -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