topo-tools 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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/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)

topo_tools/api/extend.py

@@ -0,0 +1,128 @@
+"""Public API: extend polygon boundaries outward with Voronoi diagrams."""
+
+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.duckdb_utils import (
+    cleanup_tmp,
+    export_debug_tables,
+    get_connection,
+    log_file,
+)
+from topo_tools.core.extend import _01_inputs as inputs
+from topo_tools.core.extend import _02_lines as lines
+from topo_tools.core.extend import _05_merge as merge
+from topo_tools.core.extend import _06_outputs as outputs
+from topo_tools.core.extend import attempt
+
+logger = getLogger(__name__)
+
+_STEP_ORDER = ["inputs", "lines", "attempt", "merge", "outputs"]
+
+_STEP_TABLES = {
+    "inputs": ["{n}_01"],
+    "lines": ["{n}_02"],
+    "attempt": [
+        "{n}_03a",
+        "{n}_03_tmp1",
+        "{n}_03_tmp2",
+        "{n}_03_tmp3",
+        "{n}_03_tmp4",
+        "{n}_03b",
+        "{n}_04",
+        "{n}_04_tmp1",
+        "{n}_04_tmp2",
+    ],
+    "merge": ["{n}_05", "{n}_05_tmp1", "{n}_05_tmp2", "{n}_05_tmp3"],
+    "outputs": [],
+}
+
+
+def extend(  # noqa: C901, PLR0912, PLR0913, PLR0915
+    input_path: str | Path,
+    output_path: str | Path | None = None,
+    *,
+    memory_gb: float = 4.0,
+    threads: int | None = None,
+    tmp_dir: str | Path | None = None,
+    overwrite: bool = False,
+    debug: bool = False,
+    step: str | None = None,
+) -> None:
+    """Extend polygon boundaries outward with Voronoi diagrams to fill coverage gaps.
+
+    Processes exactly one file per call. If output_path is omitted, it defaults
+    to input_path with an "_extended" suffix in the same directory.
+    """
+    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)
+
+    input_path = Path(input_path)
+    output_path = (
+        Path(output_path)
+        if output_path is not None
+        else input_path.with_stem(input_path.stem + "_extended")
+    )
+    if output_path.exists() and not overwrite:
+        msg = f"output already exists: {output_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(".", "_")
+    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 == "lines":
+                    lines.main(conn, name)
+                elif s == "attempt":
+                    attempt.main(conn, name, memory_gb=memory_gb, debug=debug)
+                elif s == "merge":
+                    merge.main(conn, name, debug=debug)
+                elif s == "outputs":
+                    outputs.main(conn, name, output_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/api/match.py

@@ -0,0 +1,140 @@
+"""Public API: match child polygons to parent boundaries, then extend to fill gaps."""
+
+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.duckdb_utils import (
+    cleanup_tmp,
+    export_debug_tables,
+    get_connection,
+    log_file,
+)
+from topo_tools.core.match import _01_inputs as inputs
+from topo_tools.core.match import _02_assign as assign
+from topo_tools.core.match import _03_groups as groups
+from topo_tools.core.match import _04_merge as merge
+from topo_tools.core.match import _05_outputs as outputs
+
+logger = getLogger(__name__)
+
+_STEP_ORDER = ["inputs", "assign", "groups", "merge", "outputs"]
+
+_STEP_TABLES = {
+    "inputs": ["{n}_child_01", "{n}_parent_01"],
+    "assign": ["{n}_02_pairs", "{n}_02_assign", "{n}_02_unassigned"],
+    # "groups" is deliberately absent: group ids aren't known ahead of time
+    # (dynamic "{n}_g{parent_fid}" names), so it falls through to the
+    # "export everything currently in the connection" default below, same as
+    # a full (no --step) run.
+    "merge": ["{n}_04"],
+    "outputs": [],
+}
+
+
+def match(  # noqa: C901, PLR0912, PLR0913, PLR0915
+    input_path: str | Path,
+    clip_path: str | Path,
+    output_path: str | Path | None = None,
+    *,
+    memory_gb: float = 4.0,
+    threads: int | None = None,
+    tmp_dir: str | Path | None = None,
+    overwrite: bool = False,
+    debug: bool = False,
+    step: str | None = None,
+) -> None:
+    """Match child polygons to their best-overlapping parent, then extend to fill gaps.
+
+    Processes exactly one child file + one parent/clip file per call. Children
+    are assigned to whichever parent polygon they share the largest area with,
+    grouped by that assignment, extended within each group independently (in
+    an isolated subprocess per group), clipped to that group's own parent,
+    reassembled, and coverage-cleaned once as a whole. If output_path is
+    omitted, it defaults to input_path with a "_matched" suffix in the same
+    directory.
+    """
+    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)
+
+    input_path = Path(input_path)
+    clip_path = Path(clip_path)
+    output_path = (
+        Path(output_path)
+        if output_path is not None
+        else input_path.with_stem(input_path.stem + "_matched")
+    )
+    if output_path.exists() and not overwrite:
+        msg = f"output already exists: {output_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)
+
+    # "_match" keeps every table/file this call creates distinct from an
+    # extend() run against the same input_path/tmp_dir -- e.g. extend's bare
+    # "{name}_04" (Voronoi cells) would otherwise collide with match's own
+    # bare "{name}_04" (final coverage-cleaned output) if both tools shared a
+    # tmp_dir and were run with --debug for side-by-side inspection.
+    name = input_path.name.replace(".", "_") + "_match"
+    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, clip_path)
+                elif s == "assign":
+                    assign.main(conn, name)
+                elif s == "groups":
+                    groups.main(
+                        conn,
+                        name,
+                        tmp_dir_path,
+                        memory_gb=memory_gb,
+                        threads=threads,
+                        debug=debug,
+                    )
+                elif s == "merge":
+                    merge.main(conn, name, debug=debug)
+                elif s == "outputs":
+                    outputs.main(conn, name, output_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/cli/__init__.py

@@ -0,0 +1 @@
+"""Click CLI commands — the only layer allowed to import click."""