findupe 0.4.0__py3-none-any.whl

findupe/__init__.py

@@ -0,0 +1,25 @@
+"""findupe — safe duplicate finder & reviewer for macOS."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _read_version() -> str:
+    try:
+        return version("findupe")
+    except PackageNotFoundError:
+        # No installed dist-info (e.g. running straight from a checkout without
+        # `uv sync`/`pip install -e .` first) — fall back to pyproject.toml so
+        # there's still a single source of truth for the version.
+        import tomllib
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parent.parent.parent / "pyproject.toml"
+        try:
+            return tomllib.loads(pyproject.read_text())["project"]["version"]
+        except (OSError, KeyError):
+            return "0.0.0+unknown"
+
+
+__version__ = _read_version()

findupe/cache.py

@@ -0,0 +1,135 @@
+"""Persistent SQLite index so re-scans only hash new or changed files.
+
+A cache row is valid only if (path, size, mtime_ns, volume) all match — any
+change forces recompute. WAL mode + batched transactions keep the index
+consistent if a scan is interrupted; resuming is just re-running the scan.
+Written from the main thread only (workers return results; caller stores).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .models import FileRecord, norm_path
+from .paths import resolve_data_home
+
+_SCHEMA_VERSION = 2  # v2: volume_uuid keying + capture_subsec
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS files (
+    path        TEXT PRIMARY KEY,
+    size        INTEGER NOT NULL,
+    mtime_ns    INTEGER NOT NULL,
+    volume_uuid TEXT NOT NULL,
+    exact_hash  TEXT,
+    phash       INTEGER,
+    dhash       INTEGER,
+    width       INTEGER,
+    height      INTEGER,
+    capture_key TEXT,
+    capture_subsec TEXT,
+    last_seen   TEXT NOT NULL
+);
+"""
+
+
+def _to_signed(v: int | None) -> int | None:
+    """SQLite INTEGER is signed 64-bit; perceptual hashes are unsigned 64-bit."""
+    if v is None:
+        return None
+    return v - (1 << 64) if v >= (1 << 63) else v
+
+
+def _to_unsigned(v: int | None) -> int | None:
+    if v is None:
+        return None
+    return v + (1 << 64) if v < 0 else v
+
+
+@dataclass
+class CachedInfo:
+    exact_hash: str | None
+    phash: int | None
+    dhash: int | None
+    width: int | None
+    height: int | None
+    capture_key: str | None
+    capture_subsec: str | None
+
+
+class Cache:
+    def __init__(self, db_path: Path | None = None) -> None:
+        db_path = db_path if db_path is not None else resolve_data_home() / "index.db"
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.db_path = db_path
+        self.conn = sqlite3.connect(db_path)
+        self.conn.execute("PRAGMA journal_mode=WAL")
+        version = self.conn.execute("PRAGMA user_version").fetchone()[0]
+        if version != _SCHEMA_VERSION:
+            # cheap-to-rebuild cache: recreate rather than migrate
+            self.conn.execute("DROP TABLE IF EXISTS files")
+            self.conn.execute(f"PRAGMA user_version={_SCHEMA_VERSION}")
+        self.conn.execute(_SCHEMA)
+        self.conn.commit()
+        self.hits = 0
+        self.misses = 0
+
+    def lookup(self, rec: FileRecord) -> CachedInfo | None:
+        row = self.conn.execute(
+            "SELECT exact_hash, phash, dhash, width, height, capture_key, capture_subsec "
+            "FROM files WHERE path=? AND size=? AND mtime_ns=? AND volume_uuid=?",
+            (norm_path(rec.path), rec.size, rec.mtime_ns, rec.volume_uuid),
+        ).fetchone()
+        if row is None:
+            self.misses += 1
+            return None
+        self.hits += 1
+        exact_hash, phash, dhash, width, height, capture_key, capture_subsec = row
+        return CachedInfo(
+            exact_hash, _to_unsigned(phash), _to_unsigned(dhash),
+            width, height, capture_key, capture_subsec,
+        )
+
+    def store(self, records: list[FileRecord]) -> None:
+        now = datetime.now(timezone.utc).isoformat()
+        self.conn.executemany(
+            # COALESCE merges pipeline stages (exact pass, then perceptual pass) for the
+            # SAME file version. If size/mtime changed, the old values are stale and must
+            # be replaced outright — hence the CASE guard on every merged column.
+            "INSERT INTO files (path, size, mtime_ns, volume_uuid, exact_hash, phash, dhash,"
+            " width, height, capture_key, capture_subsec, last_seen) VALUES (?,?,?,?,?,?,?,?,?,?,?,?) "
+            "ON CONFLICT(path) DO UPDATE SET "
+            + ", ".join(
+                f"{col} = CASE WHEN files.size = excluded.size AND files.mtime_ns = excluded.mtime_ns"
+                f" THEN COALESCE(excluded.{col}, files.{col}) ELSE excluded.{col} END"
+                for col in ("exact_hash", "phash", "dhash", "width", "height",
+                            "capture_key", "capture_subsec")
+            )
+            + ", size=excluded.size, mtime_ns=excluded.mtime_ns,"
+            " volume_uuid=excluded.volume_uuid, last_seen=excluded.last_seen",
+            [
+                (
+                    norm_path(r.path), r.size, r.mtime_ns, r.volume_uuid, r.exact_hash,
+                    _to_signed(r.phash), _to_signed(r.dhash),
+                    r.width, r.height, r.capture_key, r.capture_subsec, now,
+                )
+                for r in records
+            ],
+        )
+        self.conn.commit()
+
+    def clear(self) -> None:
+        self.conn.execute("DELETE FROM files")
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def __enter__(self) -> Cache:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

findupe/cli.py

@@ -0,0 +1,333 @@
+"""findupe CLI: scan / apply / undo / cache clear.
+
+scan never deletes; apply only acts on a reviewed selection JSON and asks for a
+typed confirmation; undo restores from the Trash. See README for the workflow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import grouping
+from .cache import Cache
+from .discover import discover
+from .grouping import build_families
+from .hashing import ensure_hashes, group_exact
+from .imaging import compute_perceptual
+from .dashboard import render_dashboard_html
+from .ledger import list_scans, load_scan, record_scan
+from .models import FileRecord, ScanResult
+from .report import _is_image_family, generate_reports
+from .stats import (
+    aggregate_undo_totals,
+    applied_scan_ids,
+    duplicates_timeline,
+    reclaimed_timeline,
+    render_stats_text,
+)
+from .trash import FakeTrasher, FinderTrasher, apply_selection, list_manifests, undo
+
+
+def _fmt_bytes(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1024 or unit == "TB":
+            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
+        n /= 1024
+    return f"{n} B"
+
+
+def _collect_hash_errors(
+    records: list[FileRecord], companions: list[FileRecord]
+) -> list[tuple[Path, str]]:
+    """Dedup by path: discover._attach_companions appends one shared sidecar
+    (e.g. an XMP) to EVERY primary in its stem-group, so a companion with the
+    same path can appear more than once in `companions` — one real problem
+    file must not be counted or reported more than once."""
+    seen: dict[Path, str] = {}
+    for rec in records + companions:
+        if rec.hash_error and rec.path not in seen:
+            seen[rec.path] = rec.hash_error
+    return list(seen.items())
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    roots = [Path(p).expanduser().resolve() for p in args.paths]
+    bad_roots = [r for r in roots if not r.is_dir()]
+    if bad_roots:
+        for r in bad_roots:
+            print(f"error: {r}: not a directory or not mounted", file=sys.stderr)
+        return 2
+    print(f"discovering files under {len(roots)} root(s)…")
+    disc = discover(roots, exclude_globs=args.exclude, materialize=args.materialize)
+    print(f"  {len(disc.records)} files · {len(disc.skipped_stubs)} cloud stubs skipped · "
+          f"{len(disc.skipped_managed)} managed libraries refused · {len(disc.hardlink_notes)} hardlinks · "
+          f"{len(disc.zero_byte)} zero-byte · {len(disc.errors)} read errors")
+    if disc.skipped_managed:
+        print("  refused (managed libraries):")
+        for p in disc.skipped_managed:
+            print(f"    {p}")
+    if disc.errors:
+        print(f"  {len(disc.errors)} read errors — see report notes for details")
+
+    with Cache(args.db) as cache:
+        print("exact pass (BLAKE2b funnel)…")
+        exact = group_exact(disc.records, cache=cache)
+        print(f"  {len(exact)} exact-duplicate groups")
+
+        print("perceptual pass (images)…")
+        compute_perceptual(disc.records, cache=cache, workers=args.workers)
+
+        families, possible = build_families(
+            disc.records, exact, threshold_possible=args.threshold
+        )
+        members = [r for f in families for p in f.partitions for r in p.files]
+        companions = [c for r in members for c in r.companions]
+        ensure_hashes(members + companions, cache=cache)
+
+    hash_errors = _collect_hash_errors(disc.records, companions)
+    pointer = " — see report notes for details" if hash_errors else ""
+    print(f"  {len(hash_errors)} decode/hash errors{pointer}")
+
+    scan_id = datetime.now().strftime("%Y%m%d-%H%M%S")
+    scan = ScanResult(
+        scan_id=scan_id, roots=roots, families=families,
+        skipped_stubs=disc.skipped_stubs, skipped_managed=disc.skipped_managed,
+        errors=disc.errors, hardlink_notes=disc.hardlink_notes, zero_byte=disc.zero_byte,
+        hash_errors=hash_errors,
+    )
+    img_path, other_path = generate_reports(scan, possible, Path(args.output))
+
+    img_families = [f for f in families if _is_image_family(f)]
+    other_families = [f for f in families if not _is_image_family(f)]
+
+    def _cat_summary(label: str, fams: list, path: Path) -> None:
+        surplus = sum(f.surplus_count for f in fams)
+        reclaimable = sum(f.surplus_bytes for f in fams)
+        print(f"  {label}: {len(fams)} families · {surplus} surplus · "
+              f"{_fmt_bytes(reclaimable)} reclaimable — {path.resolve()}")
+
+    print(f"\n{len(families)} duplicate families · {len(possible)} possible matches (review-only)")
+    _cat_summary("images", img_families, img_path)
+    _cat_summary("other ", other_families, other_path)
+    print("next:   open each report, review, Export selection, then run apply once per\n"
+          "        exported file, e.g.:\n"
+          f"        findupe apply findupe-selection-{scan_id}-images.json\n"
+          f"        findupe apply findupe-selection-{scan_id}-other.json")
+
+    try:
+        record_scan(scan, possible, img_families, other_families,
+                    (img_path, other_path), scans_dir=args.scans_dir)
+    except Exception as e:  # archival is a convenience on an already-succeeded scan
+        print(f"warning: could not archive this scan to history: {e}", file=sys.stderr)
+    return 0
+
+
+def _make_trasher(args: argparse.Namespace):
+    return FakeTrasher(Path(args.trash_dir)) if args.trash_dir else FinderTrasher()
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    try:
+        selection = json.loads(Path(args.selection).read_text())
+    except OSError as e:
+        print(f"cannot read selection file: {e}", file=sys.stderr)
+        return 2
+    except json.JSONDecodeError as e:
+        print(f"selection file is not valid JSON: {e}", file=sys.stderr)
+        return 2
+    trasher = _make_trasher(args)
+
+    plan, manifest_path = apply_selection(
+        selection, trasher, dry_run=True, undo_dir=args.undo_dir
+    )
+    if plan.fatal:
+        print(f"REFUSED: {plan.fatal}", file=sys.stderr)
+        return 2
+    for fam, reason in plan.rejected_families.items():
+        print(f"  rejected {fam}: {reason}", file=sys.stderr)
+    for path, reason in plan.skipped:
+        print(f"  skipped  {path}: {reason}", file=sys.stderr)
+    if not plan.to_trash:
+        print("nothing to do (all entries were skipped or rejected)")
+        return 1
+
+    comps = f" + {len(plan.companions)} companion file(s)" if plan.companions else ""
+    print(f"will move {len(plan.to_trash)} file(s){comps} "
+          f"({_fmt_bytes(plan.bytes_to_trash)}) to the Trash")
+    if args.dry_run:
+        for e in plan.to_trash:
+            print(f"  would trash: {e['path']}")
+        for c in plan.companions:
+            print(f"  would trash: {c['path']} (companion)")
+        return 0
+
+    answer = input("type 'trash' to confirm (anything else aborts): ")
+    if answer.strip().lower() != "trash":
+        print("aborted — nothing was moved")
+        return 1
+
+    plan, manifest_path = apply_selection(
+        selection, trasher, dry_run=False, undo_dir=args.undo_dir
+    )
+    print(f"trashed {len(plan.to_trash)} file(s); "
+          f"{len(plan.skipped)} skipped (see above)")
+    if manifest_path:
+        print(f"undo manifest: {manifest_path}")
+        print(f"to restore:    findupe undo {manifest_path.name}")
+    return 0
+
+
+def cmd_undo(args: argparse.Namespace) -> int:
+    manifests = list_manifests(args.undo_dir)
+    if not args.manifest:
+        if not manifests:
+            print("no undo manifests")
+            return 0
+        for m in manifests:
+            print(m.name)
+        return 0
+    match = next(
+        (m for m in manifests if m.name == args.manifest or m.stem == args.manifest
+         or m.name.startswith(args.manifest)),
+        None,
+    )
+    if match is None:
+        candidate = Path(args.manifest)
+        match = candidate if candidate.is_file() else None
+    if match is None:
+        print(f"no manifest matching {args.manifest!r}", file=sys.stderr)
+        return 2
+    results = undo(match, trasher=_make_trasher(args), undo_dir=args.undo_dir)
+    for path, outcome in results:
+        print(f"  {outcome}: {path}")
+    restored = sum(1 for _, o in results if o == "restored")
+    print(f"restored {restored}/{len(results)}")
+    return 0
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    records = list_scans(args.scans_dir)
+    totals = aggregate_undo_totals(args.undo_dir, args.scans_dir)
+    applied = applied_scan_ids(args.undo_dir)
+    print(render_stats_text(records, totals, applied))
+    if args.html is not None:
+        html_doc = render_dashboard_html(
+            records, totals, applied,
+            reclaimed_timeline(args.undo_dir), duplicates_timeline(records),
+        )
+        args.html.write_text(html_doc, encoding="utf-8")
+        print(f"dashboard: {args.html.resolve()}")
+    return 0
+
+
+def _find_scan(scan_id: str, scans_dir: Path):
+    """Prefix-tolerant lookup, mirroring cmd_undo's manifest matching."""
+    exact = load_scan(scan_id, scans_dir)
+    if exact is not None:
+        return exact
+    return next((r for r in list_scans(scans_dir) if r.scan_id.startswith(scan_id)), None)
+
+
+def cmd_history(args: argparse.Namespace) -> int:
+    if not args.scan_id:
+        records = list_scans(args.scans_dir)
+        if not records:
+            print("no archived scans")
+            return 0
+        applied = applied_scan_ids(args.undo_dir)
+        for r in records:
+            tag = "applied" if r.scan_id in applied else "not applied"
+            print(f"{r.scan_id}  {r.duplicate_families} families  "
+                  f"{_fmt_bytes(r.surplus_bytes)} reclaimable — [{tag}]")
+        return 0
+    rec = _find_scan(args.scan_id, args.scans_dir)
+    if rec is None:
+        print(f"no archived scan matching {args.scan_id!r}", file=sys.stderr)
+        return 2
+    applied = rec.scan_id in applied_scan_ids(args.undo_dir)
+    print(f"{rec.scan_id}  ({'applied' if applied else 'not applied'})")
+    print(f"  {rec.duplicate_families} duplicate families · {rec.possible_matches} possible matches")
+    for category, path in rec.report_paths.items():
+        print(f"  {category}: {path.resolve() if path else '(report copy missing)'}")
+    return 0
+
+
+def cmd_cache_clear(args: argparse.Namespace) -> int:
+    with Cache(args.db) as cache:
+        cache.clear()
+        db_path = cache.db_path
+    print(f"cache cleared: {db_path}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if sys.platform != "darwin":
+        print("findupe requires macOS — it relies on Finder/AppleScript for Trash "
+              "integration and APFS-specific behavior.", file=sys.stderr)
+        return 2
+    parser = argparse.ArgumentParser(
+        prog="findupe",
+        description="Safe duplicate finder: scan -> review HTML report -> apply -> (undo)",
+    )
+    # default=None, not a pre-resolved path: each is resolved lazily inside the
+    # function that actually needs it, only when still None, so passing an
+    # explicit flag here genuinely bypasses the one-time
+    # ~/.dupefinder -> ~/.findupe migration check — it never fires just
+    # because argparse filled in a default.
+    parser.add_argument("--db", type=Path, default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--undo-dir", type=Path, default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--scans-dir", type=Path, default=None, help=argparse.SUPPRESS)
+    parser.add_argument("--trash-dir", help="use a plain directory instead of the macOS Trash")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="find duplicates and write the review report")
+    p_scan.add_argument("paths", nargs="+")
+    p_scan.add_argument("--exclude", action="append", default=[], metavar="GLOB")
+    p_scan.add_argument("--materialize", action="store_true",
+                        help="download iCloud stubs instead of skipping them")
+    p_scan.add_argument("--threshold", type=int, default=grouping.THRESHOLD_POSSIBLE,
+                        help="max pHash distance for the review-only 'possible' tier")
+    p_scan.add_argument("-o", "--output", default="report.html",
+                        help="base report path; writes <name>-images.html and <name>-other.html")
+    p_scan.add_argument("--workers", type=int, default=4, help=argparse.SUPPRESS)
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_apply = sub.add_parser("apply", help="move a reviewed selection to the Trash")
+    p_apply.add_argument("selection")
+    p_apply.add_argument("--dry-run", action="store_true")
+    p_apply.set_defaults(func=cmd_apply)
+
+    p_undo = sub.add_parser("undo", help="restore a previous apply (no arg: list manifests)")
+    p_undo.add_argument("manifest", nargs="?")
+    p_undo.set_defaults(func=cmd_undo)
+
+    p_cache = sub.add_parser("cache", help="cache maintenance")
+    cache_sub = p_cache.add_subparsers(dest="cache_command", required=True)
+    p_clear = cache_sub.add_parser("clear")
+    p_clear.set_defaults(func=cmd_cache_clear)
+
+    p_stats = sub.add_parser("stats", help="all-time totals across every scan and apply")
+    p_stats.add_argument("--html", nargs="?", const=Path("findupe-dashboard.html"),
+                         default=None, type=Path, metavar="PATH",
+                         help="also write an HTML dashboard (optional output path)")
+    p_stats.set_defaults(func=cmd_stats)
+
+    p_history = sub.add_parser("history", help="list archived scans, or show one by id")
+    p_history.add_argument("scan_id", nargs="?")
+    p_history.set_defaults(func=cmd_history)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("\ninterrupted — nothing partial was deleted; cache keeps completed work",
+              file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

findupe/clones.py

@@ -0,0 +1,116 @@
+"""APFS clone detection via physical-extent comparison (F_LOG2PHYS_EXT).
+
+Spiked and verified on real hardware (2026-07-15): a `cp -c` clone reports
+the exact same physical device offset as its original; an independent copy
+does not; two independently-written files with identical content don't
+overlap either (ruling out any content-based-dedup false positive). A
+partially-edited clone still shares extents for its unedited remainder —
+detecting that correctly needs interval overlap, not exact-offset equality,
+which is what `shares_physical_extents` does.
+
+Only ever called within an already-confirmed exact-hash duplicate cluster
+(the only files clones can ever be) — never scan-wide, since the fcntl call
+has real per-file cost.
+
+Fails safe in BOTH directions, and the two directions are not symmetric:
+- Any error (non-APFS volume, permission issue, file vanished) -> treat as
+  "not a clone". A detection failure must never HIDE reclaimable space that
+  genuinely exists.
+- A *successful* call that reports device offset 0 for a file's first
+  extent -> also treated as "not a clone" and the whole probe for that file
+  is discarded. This is the more dangerous direction: a filesystem that
+  returns a "successful" but meaningless placeholder offset (rather than a
+  real error) for an unsupported case could make two genuinely-independent
+  files look identical, causing this code to falsely claim trashing one
+  frees no space — undercounting, the opposite of the error case, and worse
+  than not having this feature at all. Empirically verified on this real
+  machine (2026-07-15): FAT32 and exFAT volumes both raise a clean
+  OSError(ENOTSUP) rather than returning a placeholder — this guard is
+  deliberate defense-in-depth for filesystems/drivers not tested here, not
+  a response to an observed failure.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+from pathlib import Path
+
+_F_LOG2PHYS_EXT = 65
+_STRUCT_FMT = "<Iqq"  # struct log2phys, #pragma pack(4): uint, off_t, off_t
+
+
+def _extent_map(path: Path) -> list[tuple[int, int]] | None:
+    """[(device_offset, length), ...] covering the whole file. None on any
+    error, or if the kernel reports a suspicious 0 device offset."""
+    import fcntl  # Unix-only; imported lazily so this module stays importable
+    # on Windows — cli.py's sys.platform guard runs before any code path that
+    # would actually reach this function, but module-level imports elsewhere
+    # in the chain (cli -> grouping -> clones) happen before that guard does.
+    try:
+        fd = os.open(path, os.O_RDONLY)
+    except OSError:
+        return None
+    try:
+        try:
+            size = os.fstat(fd).st_size
+        except OSError:
+            return None
+        if size == 0:
+            return None
+        extents: list[tuple[int, int]] = []
+        file_offset = 0
+        while file_offset < size:
+            query = struct.pack(_STRUCT_FMT, 0, size - file_offset, file_offset)
+            try:
+                result = fcntl.fcntl(fd, _F_LOG2PHYS_EXT, query)
+            except OSError:
+                return None  # unsupported (non-APFS, network volume, etc.)
+            _flags, contig, dev_off = struct.unpack(_STRUCT_FMT, result)
+            if dev_off <= 0:
+                # a real device offset is never 0 (reserved/boot area) — treat
+                # as a placeholder/unsupported response, not real data
+                return None
+            if contig <= 0:
+                break  # avoid an infinite loop if the kernel reports no progress
+            extents.append((dev_off, contig))
+            file_offset += contig
+        return extents
+    finally:
+        os.close(fd)
+
+
+def _overlaps(a: list[tuple[int, int]], b: list[tuple[int, int]]) -> bool:
+    return any(
+        da < db + lb and db < da + la
+        for da, la in a
+        for db, lb in b
+    )
+
+
+class KeeperExtents:
+    """One file's extent map, computed once and checked against many others —
+    for a cluster with N surplus files, the keeper would otherwise get
+    re-probed N times for no reason."""
+
+    def __init__(self, path: Path) -> None:
+        self._extents = _extent_map(path)
+
+    def shares_with(self, other: Path) -> bool:
+        """True if `other` shares ANY physical storage with this extent map —
+        an APFS clone relationship, even if `other` has since been partially
+        edited (the unedited remainder still overlaps). False (never raises)
+        if either side's extent map can't be trusted (unreadable, unsupported
+        volume, or a suspicious response) or if they genuinely share nothing."""
+        if not self._extents:
+            return False
+        other_extents = _extent_map(other)
+        if not other_extents:
+            return False
+        return _overlaps(self._extents, other_extents)
+
+
+def shares_physical_extents(a: Path, b: Path) -> bool:
+    """Convenience wrapper for a single one-off comparison. See KeeperExtents
+    for reusing one side's extent map across multiple comparisons."""
+    return KeeperExtents(a).shares_with(b)