topo-tools 0.1.0__tar.gz

topo_tools-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: topo-tools
+Version: 0.1.0
+Summary: DuckDB-powered geospatial topology utilities (edge-matching, topology cleaning, more)
+Author: fieldmaps.io
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Dist: click
+Requires-Dist: duckdb>=1.5.3
+Requires-Dist: psutil
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/fieldmaps/topo-tools-py
+Project-URL: Repository, https://github.com/fieldmaps/topo-tools-py
+Project-URL: Issues, https://github.com/fieldmaps/topo-tools-py/issues
+Description-Content-Type: text/markdown
+
+# topo-tools
+
+[![CI](https://github.com/fieldmaps/topo-tools-py/actions/workflows/ci.yml/badge.svg)](https://github.com/fieldmaps/topo-tools-py/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/topo-tools)](https://pypi.org/project/topo-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/topo-tools)](https://pypi.org/project/topo-tools/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![World ADM0 boundaries extended with Voronoi-filled coastline](https://raw.githubusercontent.com/fieldmaps/topo-tools-py/main/img/wld_01.png)
+
+`topo-tools` is a collection of DuckDB-powered geospatial topology utilities
+for cleaning and reconciling administrative boundary polygons. It ships four
+tools, usable from the CLI or as a Python package:
+
+| Tool | What it does | Usage |
+| --- | --- | --- |
+| **clean** | Detects and fixes gap/overlap defects in a single polygon layer; reports slivers separately for manual review. | [`docs/clean.md`](docs/clean.md) |
+| **extend** | Fills gaps around a polygon layer (missing coastline, disputed areas, water bodies) with a Voronoi extension, producing full coverage. | [`docs/extend.md`](docs/extend.md) |
+| **match** | Fits a finer child polygon layer into a coarser parent layer, grouping and extending each child to fill gaps within its own parent. | [`docs/match.md`](docs/match.md) |
+| **change** | Compares two versions of a polygon layer and classifies every unit as unchanged, renamed, modified, split, merged, created, or removed. | [`docs/change.md`](docs/change.md) |
+
+## Installation
+
+```sh
+uv tool install topo-tools   # CLI (recommended)
+uv add topo-tools            # Python library
+```
+
+Or with pip:
+
+```sh
+pip install topo-tools
+```
+
+Each linked doc above covers that tool's CLI/Python usage, options, and examples.
+
+## Supported Formats
+
+Polygon inputs/outputs: GeoParquet (`.parquet`), GeoPackage (`.gpkg`),
+Shapefile (`.shp`), GeoJSON (`.geojson`). Output format matches input format.
+`change`'s tabular changelog is CSV or GeoParquet only; its spatial overlay
+layer supports the same four formats as the other tools.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup.

topo_tools-0.1.0/README.md

@@ -0,0 +1,43 @@
+# topo-tools
+
+[![CI](https://github.com/fieldmaps/topo-tools-py/actions/workflows/ci.yml/badge.svg)](https://github.com/fieldmaps/topo-tools-py/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/topo-tools)](https://pypi.org/project/topo-tools/)
+[![Python versions](https://img.shields.io/pypi/pyversions/topo-tools)](https://pypi.org/project/topo-tools/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![World ADM0 boundaries extended with Voronoi-filled coastline](https://raw.githubusercontent.com/fieldmaps/topo-tools-py/main/img/wld_01.png)
+
+`topo-tools` is a collection of DuckDB-powered geospatial topology utilities
+for cleaning and reconciling administrative boundary polygons. It ships four
+tools, usable from the CLI or as a Python package:
+
+| Tool | What it does | Usage |
+| --- | --- | --- |
+| **clean** | Detects and fixes gap/overlap defects in a single polygon layer; reports slivers separately for manual review. | [`docs/clean.md`](docs/clean.md) |
+| **extend** | Fills gaps around a polygon layer (missing coastline, disputed areas, water bodies) with a Voronoi extension, producing full coverage. | [`docs/extend.md`](docs/extend.md) |
+| **match** | Fits a finer child polygon layer into a coarser parent layer, grouping and extending each child to fill gaps within its own parent. | [`docs/match.md`](docs/match.md) |
+| **change** | Compares two versions of a polygon layer and classifies every unit as unchanged, renamed, modified, split, merged, created, or removed. | [`docs/change.md`](docs/change.md) |
+
+## Installation
+
+```sh
+uv tool install topo-tools   # CLI (recommended)
+uv add topo-tools            # Python library
+```
+
+Or with pip:
+
+```sh
+pip install topo-tools
+```
+
+Each linked doc above covers that tool's CLI/Python usage, options, and examples.
+
+## Supported Formats
+
+Polygon inputs/outputs: GeoParquet (`.parquet`), GeoPackage (`.gpkg`),
+Shapefile (`.shp`), GeoJSON (`.geojson`). Output format matches input format.
+`change`'s tabular changelog is CSV or GeoParquet only; its spatial overlay
+layer supports the same four formats as the other tools.
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup.

topo_tools-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "topo-tools"
+version = "0.1.0"
+description = "DuckDB-powered geospatial topology utilities (edge-matching, topology cleaning, more)"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "fieldmaps.io" }]
+requires-python = ">=3.10"
+dependencies = ["click", "duckdb>=1.5.3", "psutil"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+
+[project.urls]
+Homepage = "https://github.com/fieldmaps/topo-tools-py"
+Repository = "https://github.com/fieldmaps/topo-tools-py"
+Issues = "https://github.com/fieldmaps/topo-tools-py/issues"
+
+[project.scripts]
+topo-tools = "topo_tools.cli.main:cli"
+
+[dependency-groups]
+dev = ["import-linter", "pre-commit", "pytest", "ruff"]
+
+[build-system]
+requires = ["uv_build>=0.11.27,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.ruff]
+fix = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "D203", "D213", "S603", "S607", "S608"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN", "D103", "INP001", "S101"]
+
+[tool.importlinter]
+root_package = "topo_tools"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+id = "core-no-click"
+name = "Core modules must not import Click"
+type = "forbidden"
+source_modules = ["topo_tools.core"]
+forbidden_modules = ["click"]
+
+[[tool.importlinter.contracts]]
+id = "api-no-cli"
+name = "API modules must not import CLI"
+type = "forbidden"
+source_modules = ["topo_tools.api"]
+forbidden_modules = ["topo_tools.cli"]
+
+[[tool.importlinter.contracts]]
+id = "match-may-use-extend-not-reverse"
+name = "match may depend on extend; extend must not depend on match"
+type = "forbidden"
+source_modules = ["topo_tools.core.extend"]
+forbidden_modules = ["topo_tools.core.match"]
+
+[[tool.importlinter.contracts]]
+id = "clean-may-use-extend-not-reverse"
+name = "clean may depend on extend; extend must not depend on clean"
+type = "forbidden"
+source_modules = ["topo_tools.core.extend"]
+forbidden_modules = ["topo_tools.core.clean"]
+
+[[tool.importlinter.contracts]]
+id = "change-may-use-extend-not-reverse"
+name = "change may depend on extend; extend must not depend on change"
+type = "forbidden"
+source_modules = ["topo_tools.core.extend"]
+forbidden_modules = ["topo_tools.core.change"]

topo_tools-0.1.0/topo_tools/__init__.py

@@ -0,0 +1,6 @@
+"""topo-tools: DuckDB-powered geospatial topology utilities."""
+
+from .api import extend, match
+from .cli.main import cli
+
+__all__ = ["cli", "extend", "match"]

topo_tools-0.1.0/topo_tools/__main__.py

@@ -0,0 +1,6 @@
+"""Allows `python -m topo_tools ...`."""
+
+from .cli.main import cli
+
+if __name__ == "__main__":
+    cli()

topo_tools-0.1.0/topo_tools/api/__init__.py

@@ -0,0 +1,8 @@
+"""Public functions library callers import — no click dependency."""
+
+from .change import change
+from .clean import clean
+from .extend import extend
+from .match import match
+
+__all__ = ["change", "clean", "extend", "match"]

topo_tools-0.1.0/topo_tools/api/change.py

@@ -0,0 +1,224 @@
+"""Public API: compare two polygon layer versions and classify what changed."""
+
+import shutil
+import signal
+import tempfile
+from logging import getLogger
+from pathlib import Path
+from types import FrameType
+from typing import NoReturn
+
+from duckdb import DuckDBPyConnection
+
+from topo_tools.core.change import _01_inputs as inputs
+from topo_tools.core.change import _02_overlap as overlap
+from topo_tools.core.change import _03_classify as classify
+from topo_tools.core.change import _04_outputs as outputs
+from topo_tools.core.change._columns import detect_code_column, detect_name_column
+from topo_tools.core.change._constants import (
+    TABLE_COPY_OPTS,
+    TAU_MATCH_DEFAULT,
+    TAU_SAME_DEFAULT,
+)
+from topo_tools.core.duckdb_utils import (
+    cleanup_tmp,
+    export_debug_tables,
+    get_connection,
+    log_file,
+)
+from topo_tools.core.extend._constants import COPY_OPTS
+
+logger = getLogger(__name__)
+
+_STEP_ORDER = ["inputs", "overlap", "classify", "outputs"]
+
+_STEP_TABLES = {
+    "inputs": ["{n}_a_01", "{n}_b_01"],
+    "overlap": ["{n}_02"],
+    "classify": ["{n}_03a", "{n}_03b", "{n}_03c"],
+    "outputs": [],
+}
+
+
+def _resolve_column(
+    conn: DuckDBPyConnection, table: str, explicit: str | None, *, kind: str, side: str
+) -> str | None:
+    if explicit is not None:
+        return explicit
+    detector = detect_code_column if kind == "code" else detect_name_column
+    column = detector(conn, table)
+    if column is None:
+        msg = (
+            f"--link-by-{kind} was requested but no {kind} column could be "
+            f"auto-detected on the {side} side; pass --{kind}-column-{side} explicitly"
+        )
+        raise ValueError(msg)
+    return column
+
+
+def change(  # noqa: C901, PLR0912, PLR0913, PLR0915
+    old_path: str | Path,
+    new_path: str | Path,
+    output_path: str | Path | None = None,
+    overlay_path: str | Path | None = None,
+    *,
+    tau_match: float = TAU_MATCH_DEFAULT,
+    tau_same: float = TAU_SAME_DEFAULT,
+    link_by_code: bool = False,
+    link_by_name: bool = False,
+    link_mode: str = "either",
+    code_column_a: str | None = None,
+    code_column_b: str | None = None,
+    name_column_a: str | None = None,
+    name_column_b: str | None = None,
+    threads: int | None = None,
+    tmp_dir: str | Path | None = None,
+    overwrite: bool = False,
+    debug: bool = False,
+    step: str | None = None,
+) -> None:
+    """Compare two polygon layer versions and classify every unit's relationship.
+
+    Processes exactly one old file + one new file per call. Classifies each
+    unit as unchanged/renamed/modified/relocated/split/merge/complex/created/
+    removed, using spatial overlap (tau_match/tau_same) and, optionally,
+    code/name identity linking. Always writes two files: a tabular changelog
+    (output_path, CSV/Parquet, "_changelog" suffix if omitted) and a spatial
+    overlay layer colored by relationship_class (overlay_path, "_overlay"
+    suffix if omitted).
+    """
+    if step is not None and step not in _STEP_ORDER:
+        msg = f"step must be one of {_STEP_ORDER}, got {step!r}"
+        raise ValueError(msg)
+    if link_mode not in ("either", "both"):
+        msg = f"link_mode must be 'either' or 'both', got {link_mode!r}"
+        raise ValueError(msg)
+
+    old_path = Path(old_path)
+    new_path = Path(new_path)
+    output_path = (
+        Path(output_path)
+        if output_path is not None
+        else old_path.parent / f"{old_path.stem}_{new_path.stem}_changelog.csv"
+    )
+    if output_path.suffix not in TABLE_COPY_OPTS:
+        msg = (
+            f"output file must be one of {sorted(TABLE_COPY_OPTS)} (a tabular "
+            "format -- the changelog has no geometry column), got "
+            f"{output_path.suffix!r}"
+        )
+        raise ValueError(msg)
+    overlay_path = (
+        Path(overlay_path)
+        if overlay_path is not None
+        else output_path.with_stem(output_path.stem + "_overlay").with_suffix(
+            old_path.suffix
+        )
+    )
+    if overlay_path.suffix not in COPY_OPTS:
+        msg = (
+            f"overlay file must be one of {sorted(COPY_OPTS)}, "
+            f"got {overlay_path.suffix!r}"
+        )
+        raise ValueError(msg)
+    if output_path.exists() and not overwrite:
+        msg = f"output already exists: {output_path}"
+        raise FileExistsError(msg)
+    if overlay_path.exists() and not overwrite:
+        msg = f"output already exists: {overlay_path}"
+        raise FileExistsError(msg)
+
+    owns_tmp_dir = tmp_dir is None
+    tmp_dir_path = (
+        Path(tmp_dir)
+        if tmp_dir is not None
+        else Path(tempfile.mkdtemp(prefix="topo_tools_"))
+    )
+    tmp_dir_path.mkdir(exist_ok=True, parents=True)
+
+    # "_changelog" keeps every table/file this call creates distinct from an
+    # extend()/match()/clean() run against the same old_path/tmp_dir, same
+    # collision-avoidance reasoning as match's "_match" and clean's "_clean".
+    name = old_path.name.replace(".", "_") + "_changelog"
+    if not step:
+        cleanup_tmp(name, tmp_dir_path, parquet=True)
+
+    with log_file(name, tmp_dir_path):
+        conn = get_connection(name, tmp_dir_path, threads=threads, debug=debug)
+
+        def _interrupt(_sig: int, _frame: FrameType | None) -> NoReturn:
+            conn.interrupt()
+            raise KeyboardInterrupt
+
+        old_handler = signal.signal(signal.SIGINT, _interrupt)
+        try:
+            logger.info("starting: %s", name)
+            for s in _STEP_ORDER:
+                if step and step != s:
+                    continue
+                if debug:
+                    logger.info("=== %s ===", s)
+                if s == "inputs":
+                    inputs.main(conn, name, old_path, new_path)
+                elif s == "overlap":
+                    overlap.main(conn, name)
+                elif s == "classify":
+                    resolved_code_a = (
+                        _resolve_column(
+                            conn, f"{name}_a_01", code_column_a, kind="code", side="a"
+                        )
+                        if link_by_code
+                        else code_column_a
+                    )
+                    resolved_code_b = (
+                        _resolve_column(
+                            conn, f"{name}_b_01", code_column_b, kind="code", side="b"
+                        )
+                        if link_by_code
+                        else code_column_b
+                    )
+                    resolved_name_a = (
+                        _resolve_column(
+                            conn, f"{name}_a_01", name_column_a, kind="name", side="a"
+                        )
+                        if link_by_name
+                        else name_column_a
+                    )
+                    resolved_name_b = (
+                        _resolve_column(
+                            conn, f"{name}_b_01", name_column_b, kind="name", side="b"
+                        )
+                        if link_by_name
+                        else name_column_b
+                    )
+                    classify.main(
+                        conn,
+                        name,
+                        tau_match=tau_match,
+                        tau_same=tau_same,
+                        link_by_code=link_by_code,
+                        link_by_name=link_by_name,
+                        link_mode=link_mode,
+                        code_col_a=resolved_code_a,
+                        code_col_b=resolved_code_b,
+                        name_col_a=resolved_name_a,
+                        name_col_b=resolved_name_b,
+                    )
+                elif s == "outputs":
+                    outputs.main(conn, name, output_path, overlay_path, debug=debug)
+            if debug:
+                only = None
+                if step and step in _STEP_TABLES:
+                    only = {t.format(n=name) for t in _STEP_TABLES[step]}
+                export_debug_tables(conn, tmp_dir_path, only=only)
+            logger.info("done: %s", name)
+        finally:
+            signal.signal(signal.SIGINT, old_handler)
+            conn.close()
+            if not step and not debug:
+                cleanup_tmp(name, tmp_dir_path)
+            if owns_tmp_dir:
+                if debug:
+                    logger.info("tmp_dir preserved for --debug: %s", tmp_dir_path)
+                else:
+                    shutil.rmtree(tmp_dir_path, ignore_errors=True)

topo_tools-0.1.0/topo_tools/api/clean.py

@@ -0,0 +1,170 @@
+"""Public API: detect and fix coverage defects (gaps, overlaps) in a polygon layer."""
+
+import shutil
+import signal
+import tempfile
+from logging import getLogger
+from pathlib import Path
+from types import FrameType
+from typing import NoReturn
+
+from topo_tools.core.clean import _01_inputs as inputs
+from topo_tools.core.clean import _02_issues as issues
+from topo_tools.core.clean import _03_clean as clean_stage
+from topo_tools.core.clean import _04_outputs as outputs
+from topo_tools.core.clean._constants import SLIVER_TOLERANCE_DEFAULT_M
+from topo_tools.core.duckdb_utils import (
+    cleanup_tmp,
+    export_debug_tables,
+    get_connection,
+    log_file,
+)
+
+logger = getLogger(__name__)
+
+_STEP_ORDER = ["inputs", "issues", "clean", "outputs"]
+
+_STEP_TABLES = {
+    "inputs": ["{n}_01"],
+    "issues": ["{n}_02"],
+    "clean": ["{n}_03"],
+    "outputs": [],
+}
+
+
+def _parse_gap_width(value: str) -> tuple[str, float | None]:
+    if value in ("auto", "all"):
+        return value, None
+    try:
+        return "value", float(value)
+    except ValueError:
+        msg = f"--gap-width must be 'auto', 'all', or a number in meters, got {value!r}"
+        raise ValueError(msg) from None
+
+
+def _parse_snap_tolerance(value: str) -> tuple[str, float | None]:
+    if value == "auto":
+        return "auto", None
+    try:
+        return "value", float(value)
+    except ValueError:
+        msg = f"--snap-tolerance must be 'auto' or a number in meters, got {value!r}"
+        raise ValueError(msg) from None
+
+
+def clean(  # noqa: C901, PLR0912, PLR0913, PLR0915
+    input_path: str | Path,
+    output_path: str | Path | None = None,
+    issues_path: str | Path | None = None,
+    *,
+    gap_width: str = "all",
+    snap_tolerance: str = "auto",
+    sliver_tolerance_m: float = SLIVER_TOLERANCE_DEFAULT_M,
+    threads: int | None = None,
+    tmp_dir: str | Path | None = None,
+    overwrite: bool = False,
+    debug: bool = False,
+    step: str | None = None,
+) -> None:
+    """Detect and fix gap/overlap defects in a single polygon layer.
+
+    Processes exactly one file per call. Slivers (near-miss boundary
+    mismatches) are detected and reported but never auto-fixed -- widening
+    ST_CoverageClean's snap tolerance to force one closed re-nodes the whole
+    coverage, not just the defect site. Always writes two files: the cleaned
+    dataset (output_path, "_cleaned" suffix if omitted) and an issues report
+    (issues_path, "_issues" suffix if omitted) so a human can review flagged
+    slivers -- and any gaps left unfilled -- before deciding what to do with
+    them.
+    """
+    if step is not None and step not in _STEP_ORDER:
+        msg = f"step must be one of {_STEP_ORDER}, got {step!r}"
+        raise ValueError(msg)
+
+    parsed_gap_width = _parse_gap_width(gap_width)
+    parsed_snap_tolerance = _parse_snap_tolerance(snap_tolerance)
+
+    input_path = Path(input_path)
+    output_path = (
+        Path(output_path)
+        if output_path is not None
+        else input_path.with_stem(input_path.stem + "_cleaned")
+    )
+    issues_path = (
+        Path(issues_path)
+        if issues_path is not None
+        else output_path.with_stem(output_path.stem + "_issues")
+    )
+    if issues_path.suffix == ".shp":
+        msg = (
+            "issues file cannot be Shapefile: the issues report mixes Polygon "
+            "(gap/overlap) and LineString (sliver) geometry in one table, which "
+            "Shapefile's single-geometry-type-per-file format can't represent"
+        )
+        raise ValueError(msg)
+    if output_path.exists() and not overwrite:
+        msg = f"output already exists: {output_path}"
+        raise FileExistsError(msg)
+    if issues_path.exists() and not overwrite:
+        msg = f"output already exists: {issues_path}"
+        raise FileExistsError(msg)
+
+    owns_tmp_dir = tmp_dir is None
+    tmp_dir_path = (
+        Path(tmp_dir)
+        if tmp_dir is not None
+        else Path(tempfile.mkdtemp(prefix="topo_tools_"))
+    )
+    tmp_dir_path.mkdir(exist_ok=True, parents=True)
+
+    name = input_path.name.replace(".", "_") + "_clean"
+    if not step:
+        cleanup_tmp(name, tmp_dir_path, parquet=True)
+
+    with log_file(name, tmp_dir_path):
+        conn = get_connection(name, tmp_dir_path, threads=threads, debug=debug)
+
+        def _interrupt(_sig: int, _frame: FrameType | None) -> NoReturn:
+            conn.interrupt()
+            raise KeyboardInterrupt
+
+        old_handler = signal.signal(signal.SIGINT, _interrupt)
+        try:
+            logger.info("starting: %s", name)
+            for s in _STEP_ORDER:
+                if step and step != s:
+                    continue
+                if debug:
+                    logger.info("=== %s ===", s)
+                if s == "inputs":
+                    inputs.main(conn, name, input_path)
+                elif s == "issues":
+                    issues.main(
+                        conn, name, sliver_tolerance_m=sliver_tolerance_m, debug=debug
+                    )
+                elif s == "clean":
+                    clean_stage.main(
+                        conn,
+                        name,
+                        gap_width=parsed_gap_width,
+                        snap_tolerance=parsed_snap_tolerance,
+                        debug=debug,
+                    )
+                elif s == "outputs":
+                    outputs.main(conn, name, output_path, issues_path, debug=debug)
+            if debug:
+                only = None
+                if step and step in _STEP_TABLES:
+                    only = {t.format(n=name) for t in _STEP_TABLES[step]}
+                export_debug_tables(conn, tmp_dir_path, only=only)
+            logger.info("done: %s", name)
+        finally:
+            signal.signal(signal.SIGINT, old_handler)
+            conn.close()
+            if not step and not debug:
+                cleanup_tmp(name, tmp_dir_path)
+            if owns_tmp_dir:
+                if debug:
+                    logger.info("tmp_dir preserved for --debug: %s", tmp_dir_path)
+                else:
+                    shutil.rmtree(tmp_dir_path, ignore_errors=True)