tilefetch 0.1.0__py3-none-any.whl

tilefetch/cli.py

@@ -0,0 +1,419 @@
+"""Command-line interface: ``tilefetch providers|estimate|get|mosaic|info``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Sequence
+
+from ._version import __version__
+from .api import estimate, fetch, mosaic
+from .pmtiles import PMTilesReader
+from .providers import list_providers
+from .sources import PolicyError, TileSource, wmts_source
+from .storage import MBTilesStore, store_kind
+
+__all__ = ["main", "build_parser"]
+
+
+def _kv(items: Sequence[str] | None, sep: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items or []:
+        if sep not in item:
+            raise ValueError(f"expected KEY{sep}VALUE, got {item!r}")
+        k, v = item.split(sep, 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def parse_subdomains(raw: str) -> tuple[str, ...]:
+    """``"abc"`` -> ``("a", "b", "c")``; ``"t0,t1"`` -> ``("t0", "t1")``."""
+    if "," in raw:
+        return tuple(s.strip() for s in raw.split(",") if s.strip())
+    return tuple(raw.strip())
+
+
+def _add_source(p: argparse.ArgumentParser, allow_input: bool = False) -> None:
+    g = p.add_argument_group("source (choose one)")
+    g.add_argument("--provider", "-p", help="built-in provider name (see `tilefetch providers`)")
+    g.add_argument(
+        "--url", "-u", help="URL template, e.g. https://tiles.example.org/{z}/{x}/{y}.png"
+    )
+    g.add_argument("--wmts", help="WMTS GetCapabilities URL or file (with --layer)")
+    if allow_input:
+        g.add_argument(
+            "--input", "-i", help="existing .mbtiles, .pmtiles or z/x/y folder (offline)"
+        )
+    g.add_argument("--layer", help="WMTS layer identifier")
+    g.add_argument(
+        "--tile-matrix-set", help="WMTS tile matrix set (default: first Web Mercator one)"
+    )
+    g.add_argument("--style", help="WMTS style")
+    g.add_argument("--format", dest="wmts_format", help="WMTS format, e.g. image/png")
+    g.add_argument(
+        "--encoding", choices=["auto", "rest", "kvp"], default="auto", help="WMTS request encoding"
+    )
+    g.add_argument(
+        "--param",
+        action="append",
+        metavar="KEY=VALUE",
+        help="template parameter / WMTS dimension (repeatable)",
+    )
+    g.add_argument(
+        "--tms", action="store_true", help="custom URL uses TMS rows ({y} counted from the south)"
+    )
+    g.add_argument("--subdomains", help="values for {s}, e.g. abc or a,b,c")
+    g.add_argument("--min-zoom", type=int, default=0, help="custom URL: lowest zoom served")
+    g.add_argument("--max-zoom", type=int, default=22, help="custom URL: highest zoom served")
+    g.add_argument("--attribution", default="", help="attribution text for a custom source")
+    g.add_argument("--terms-url", help="terms-of-use URL for a custom source")
+
+
+def _add_area(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("area")
+    g.add_argument(
+        "--bbox", "-b", help="west,south,east,north (degrees unless --bbox-crs EPSG:3857)"
+    )
+    g.add_argument(
+        "--bbox-crs", default="EPSG:4326", help="CRS of --bbox: EPSG:4326 (default) or EPSG:3857"
+    )
+    g.add_argument("--geojson", "-g", help="GeoJSON file with (Multi)Polygon geometry")
+    g.add_argument("--zoom", "-z", required=True, help="zoom level(s): 14, 12-15 or 10,12,14")
+
+
+def _add_download(p: argparse.ArgumentParser) -> None:
+    g = p.add_argument_group("download")
+    g.add_argument("--threads", "-t", type=int, default=2, help="concurrent requests (default 2)")
+    g.add_argument("--rate", type=float, help="max requests per second (default: provider limit)")
+    g.add_argument(
+        "--max-tiles", type=int, help="tile cap for this job (custom sources only can raise it)"
+    )
+    g.add_argument("--retries", type=int, default=4, help="retries per tile (default 4)")
+    g.add_argument("--timeout", type=float, default=30.0, help="request timeout in seconds")
+    g.add_argument("--cache", help="on-disk HTTP cache folder (enables ETag revalidation)")
+    g.add_argument(
+        "--revalidate", action="store_true", help="revalidate cached tiles (If-None-Match)"
+    )
+    g.add_argument("--user-agent", help="identify your application (browser strings are refused)")
+    g.add_argument(
+        "--header", "-H", action="append", metavar="'Name: value'", help="extra HTTP header"
+    )
+    g.add_argument("--quiet", "-q", action="store_true", help="no attribution/progress on stderr")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tilefetch",
+        description=(
+            "Download XYZ/TMS/WMTS tiles for an area into MBTiles, PMTiles, a z/x/y folder "
+            "or one georeferenced image. Respect each provider's terms of use."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"tilefetch {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    pp = sub.add_parser("providers", help="list built-in providers with their terms")
+    pp.add_argument("--json", action="store_true", help="print JSON")
+
+    pe = sub.add_parser("estimate", help="count tiles and estimate size before downloading")
+    _add_source(pe)
+    _add_area(pe)
+    pe.add_argument("--sample", type=int, default=0, help="download N tiles to measure tile size")
+    pe.add_argument("--max-tiles", type=int)
+    pe.add_argument("--rate", type=float)
+    pe.add_argument("--user-agent")
+    pe.add_argument("--header", "-H", action="append")
+    pe.add_argument("--json", action="store_true", help="print JSON")
+
+    pg = sub.add_parser("get", help="download tiles into .mbtiles, .pmtiles, a folder or an image")
+    _add_source(pg)
+    _add_area(pg)
+    _add_download(pg)
+    pg.add_argument(
+        "--output", "-o", required=True, help="output path (.mbtiles, .pmtiles, folder, .tif, .png)"
+    )
+    pg.add_argument(
+        "--overwrite", action="store_true", help="start from scratch instead of resuming"
+    )
+    pg.add_argument(
+        "--no-resume", action="store_true", help="re-download tiles already in the output"
+    )
+    pg.add_argument("--name", help="tileset name stored in the metadata")
+
+    pm = sub.add_parser("mosaic", help="stitch one zoom level into a georeferenced image")
+    _add_source(pm, allow_input=True)
+    _add_area(pm)
+    _add_download(pm)
+    pm.add_argument("--output", "-o", required=True, help="output image (.tif, .png, .jpg, .webp)")
+    pm.add_argument(
+        "--crs", default="EPSG:3857", help="output CRS: EPSG:3857 (default) or EPSG:4326"
+    )
+    pm.add_argument(
+        "--crop",
+        choices=["exact", "snap", "none"],
+        default="exact",
+        help="crop mode (default exact)",
+    )
+    pm.add_argument("--resampling", choices=["nearest", "bilinear", "bicubic"], default="bilinear")
+    pm.add_argument("--width", type=int, help="output width in pixels (EPSG:4326 only)")
+    pm.add_argument(
+        "--engine", choices=["pillow", "rasterio"], default="pillow", help="GeoTIFF writer"
+    )
+
+    pi = sub.add_parser("info", help="show header/metadata of a .mbtiles or .pmtiles file")
+    pi.add_argument("path")
+    pi.add_argument("--json", action="store_true")
+    return parser
+
+
+def _source(args: argparse.Namespace) -> Any:
+    params = _kv(args.param, "=")
+    headers = _kv(getattr(args, "header", None), ":")
+    chosen = [n for n in ("provider", "url", "wmts", "input") if getattr(args, n, None)]
+    if len(chosen) != 1:
+        raise SystemExit(
+            "error: give exactly one of --provider, --url, --wmts"
+            + (", --input" if hasattr(args, "input") else "")
+        )
+    if args.provider:
+        return args.provider, params, headers
+    if getattr(args, "input", None):
+        return args.input, params, headers
+    if args.url:
+        subs: tuple[str, ...] = ()
+        if args.subdomains:
+            subs = parse_subdomains(args.subdomains)
+        src = TileSource.from_url(
+            args.url,
+            params=params,
+            headers=headers,
+            scheme="tms" if args.tms else "xyz",
+            attribution=args.attribution,
+            terms_url=args.terms_url,
+            min_zoom=args.min_zoom,
+            max_zoom=args.max_zoom,
+            **({"subdomains": subs} if subs else {}),
+        )
+        return src, {}, {}
+    if not args.layer:
+        raise SystemExit("error: --wmts needs --layer")
+    src = wmts_source(
+        args.wmts,
+        args.layer,
+        tile_matrix_set=args.tile_matrix_set,
+        style=args.style,
+        format=args.wmts_format,
+        dimensions=params,
+        encoding=args.encoding,
+        attribution=args.attribution,
+        terms_url=args.terms_url,
+        headers=headers,
+    )
+    return src, {}, {}
+
+
+def _area(args: argparse.Namespace) -> dict[str, Any]:
+    if bool(args.bbox) == bool(args.geojson):
+        raise SystemExit("error: give exactly one of --bbox or --geojson")
+    return {"bbox": args.bbox, "geometry": args.geojson, "bbox_crs": args.bbox_crs}
+
+
+class _Progress:
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+        self.last = -1
+
+    def __call__(self, done: int, total: int) -> None:
+        if not self.enabled or total == 0:
+            return
+        pct = int(100 * done / total)
+        if pct != self.last or done == total:
+            self.last = pct
+            end = "\n" if done == total else ""
+            print(
+                f"\r[tilefetch] {done}/{total} tiles ({pct}%)", end=end, file=sys.stderr, flush=True
+            )
+
+
+def _fmt_bytes(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
+        n /= 1024.0
+    return f"{n:.1f} GB"  # pragma: no cover
+
+
+def _cmd_providers(args: argparse.Namespace) -> int:
+    provs = list_providers()
+    if args.json:
+        print(json.dumps([p.summary() for p in provs], indent=2))
+        return 0
+    for p in provs:
+        print(
+            f"{p.name}  (zoom {p.min_zoom}-{p.max_zoom}, max {p.max_tiles} tiles/job, {p.max_rate} req/s)"
+        )
+        print(f"    {p.description}")
+        print(f"    attribution: {p.attribution}")
+        print(f"    terms:       {p.terms_url}")
+    print(
+        "\nOther sources: pass --url with a template for a server you operate or whose terms "
+        "allow bulk/offline use. tile.openstreetmap.org and similar community servers forbid it."
+    )
+    return 0
+
+
+def _cmd_estimate(args: argparse.Namespace) -> int:
+    src, params, headers = _source(args)
+    est = estimate(
+        src,
+        zoom=args.zoom,
+        params=params or None,
+        sample=args.sample,
+        max_tiles=args.max_tiles,
+        rate=args.rate,
+        user_agent=args.user_agent,
+        headers=headers or None,
+        **_area(args),
+    )
+    if args.json:
+        print(json.dumps(est.as_dict(), indent=2))
+        return 0 if est.within_limit else 1
+    print(f"source: {est.source}")
+    for z, n in est.tiles_per_zoom.items():
+        size = est.mosaic_size.get(z)
+        px = f", mosaic {size[0]}x{size[1]} px" if size else ""
+        print(f"  zoom {z:2d}: {n} tiles, {est.resolution_m[z]:.2f} m/px{px}")
+    how = f"measured from {est.sampled} tiles" if est.sampled else "typical size"
+    print(f"total: {est.total_tiles} tiles, ~{_fmt_bytes(est.estimated_bytes)} ({how})")
+    if est.estimated_seconds is not None:
+        print(f"time at {est.rate} req/s: >= {est.estimated_seconds:.0f} s")
+    if est.max_tiles is not None:
+        state = "within" if est.within_limit else "EXCEEDS"
+        print(f"limit: {est.max_tiles} tiles per job ({state})")
+    return 0 if est.within_limit else 1
+
+
+def _download_kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    return {
+        "threads": args.threads,
+        "rate": args.rate,
+        "max_tiles": args.max_tiles,
+        "retries": args.retries,
+        "timeout": args.timeout,
+        "cache_dir": args.cache,
+        "revalidate": args.revalidate,
+        "user_agent": args.user_agent,
+        "quiet": args.quiet,
+        "progress": _Progress(not args.quiet and sys.stderr.isatty()),
+    }
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    src, params, headers = _source(args)
+    res = fetch(
+        src,
+        zoom=args.zoom,
+        out=args.output,
+        params=params or None,
+        headers=headers or None,
+        overwrite=args.overwrite,
+        resume=not args.no_resume,
+        name=args.name,
+        **_area(args),
+        **_download_kwargs(args),
+    )
+    s = res.stats
+    print(
+        f"{res.path}: {s.total} tiles - {s.downloaded} downloaded, {s.cached} from cache, "
+        f"{s.skipped} already present, {s.missing} missing, {s.failed} failed "
+        f"({_fmt_bytes(s.bytes)})"
+    )
+    for tile, err in s.errors[:5]:
+        print(f"  failed {tile.z}/{tile.x}/{tile.y}: {err}", file=sys.stderr)
+    return 0 if res.ok else 1
+
+
+_CROP: dict[str, bool | str] = {"exact": True, "snap": "snap", "none": False}
+
+
+def _cmd_mosaic(args: argparse.Namespace) -> int:
+    src, params, headers = _source(args)
+    kwargs = _download_kwargs(args)
+    zoom = int(args.zoom)
+    res = mosaic(
+        src,
+        zoom=zoom,
+        out=args.output,
+        crs=args.crs,
+        crop=_CROP[args.crop],
+        resampling=args.resampling,
+        width=args.width,
+        engine=args.engine,
+        params=params or None,
+        headers=headers or None,
+        **_area(args),
+        **kwargs,
+    )
+    b = res.bounds
+    print(
+        f"{res.path}: {res.image.width}x{res.image.height} px, {res.crs}, "
+        f"bounds {b.minx:.6f},{b.miny:.6f},{b.maxx:.6f},{b.maxy:.6f}, missing tiles {res.missing}"
+    )
+    if res.attribution and not args.quiet and getattr(args, "input", None):
+        # Network sources already announced it on stderr; offline packages carry it in metadata.
+        print(f"Attribution: {res.attribution}")
+    failed = res.stats.failed if res.stats else 0
+    return 0 if failed == 0 else 1
+
+
+def _cmd_info(args: argparse.Namespace) -> int:
+    kind = store_kind(args.path)
+    info: dict[str, Any] = {"path": args.path, "kind": kind}
+    if kind == "pmtiles":
+        with PMTilesReader(args.path) as r:
+            info["header"] = dict(vars(r.header))
+            info["metadata"] = r.metadata
+    elif kind == "mbtiles":
+        with MBTilesStore(args.path, "r") as m:
+            info["metadata"] = m.metadata
+            info["tiles"] = len(m)
+    else:
+        print("error: info supports .mbtiles and .pmtiles files", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(info, indent=2, default=str))
+    else:
+        for k, v in info.items():
+            if isinstance(v, dict):
+                print(f"{k}:")
+                for kk, vv in v.items():
+                    print(f"  {kk}: {vv}")
+            else:
+                print(f"{k}: {v}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "providers": _cmd_providers,
+        "estimate": _cmd_estimate,
+        "get": _cmd_get,
+        "mosaic": _cmd_mosaic,
+        "info": _cmd_info,
+    }
+    try:
+        return handlers[args.command](args)
+    except (PolicyError, ValueError, KeyError, FileNotFoundError) as exc:
+        msg = exc.args[0] if isinstance(exc, KeyError) and exc.args else exc
+        print(f"error: {msg}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:  # pragma: no cover - interactive
+        print("\ninterrupted; run the same command again to resume", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())