Adding Auto-Completion to Python Spatial CLI Tools

# spatial_cli.py
from __future__ import annotations

import functools
from pathlib import Path
from typing import List

import typer

app = typer.Typer(
    name="spatial-cli",
    help="Geospatial batch processing toolkit with shell completion.",
    add_completion=True,   # (1) exposes --install-completion and --show-completion
)

# ---------------------------------------------------------------------------
# Completer functions — must be pure, fast, and import-free of heavy GIS libs
# ---------------------------------------------------------------------------

SUPPORTED_FORMATS: List[str] = [
    "GeoTIFF", "Shapefile", "GeoPackage", "NetCDF", "GeoJSON", "FlatGeobuf"
]

# EPSG codes that cover the most common GIS CRS choices;
# extend or replace with a lightweight SQLite lookup for broader coverage.
EPSG_REGISTRY: List[str] = [
    "EPSG:4326",   # WGS 84 geographic
    "EPSG:3857",   # Web Mercator
    "EPSG:32633",  # UTM zone 33N
    "EPSG:32632",  # UTM zone 32N
    "EPSG:26918",  # UTM zone 18N (NAD83)
    "EPSG:27700",  # British National Grid
]

SPATIAL_EXTS = frozenset({".tif", ".tiff", ".shp", ".gpkg", ".geojson", ".nc", ".fgb"})


def complete_formats(ctx: typer.Context, param: typer.CallbackParam, incomplete: str) -> List[str]:  # (2)
    """Return spatial format names that start with the partial input."""
    return [f for f in SUPPORTED_FORMATS if f.lower().startswith(incomplete.lower())]


def complete_crs(ctx: typer.Context, param: typer.CallbackParam, incomplete: str) -> List[str]:
    """Return EPSG codes matching the partial string."""
    return [c for c in EPSG_REGISTRY if incomplete.upper() in c.upper()]


@functools.lru_cache(maxsize=64)   # (3) cache per unique parent-dir string
def _list_spatial_files(parent: str) -> List[str]:
    try:
        return [
            str(p) for p in Path(parent).iterdir()
            if p.suffix.lower() in SPATIAL_EXTS
        ]
    except (PermissionError, NotADirectoryError):
        return []


def complete_paths(ctx: typer.Context, param: typer.CallbackParam, incomplete: str) -> List[str]:
    """Suggest .tif/.shp/.gpkg/.geojson files relative to the partial path."""
    p = Path(incomplete)
    parent = str(p.parent) if p.parent != Path(".") else "."
    candidates = _list_spatial_files(parent)
    return [c for c in candidates if Path(c).name.startswith(p.name)]


# ---------------------------------------------------------------------------
# CLI command
# ---------------------------------------------------------------------------

@app.command()
def process(
    input_path: Path = typer.Argument(
        ...,
        help="Path to the input raster (.tif) or vector (.gpkg, .shp) dataset.",
        shell_complete=complete_paths,   # (4)
    ),
    output_format: str = typer.Option(
        "GeoTIFF",
        "--format", "-f",
        help="Output spatial format.",
        shell_complete=complete_formats,
    ),
    target_crs: str = typer.Option(
        "EPSG:4326",
        "--crs", "-c",
        help="Target coordinate reference system as an EPSG code.",
        shell_complete=complete_crs,
    ),
) -> None:
    """Reproject and convert a spatial dataset to the requested format and CRS."""
    typer.echo(f"Input : {input_path}")
    typer.echo(f"Format: {output_format}")
    typer.echo(f"CRS   : {target_crs}")
    # Replace this block with rasterio.open / pyogrio.read_dataframe logic.


if __name__ == "__main__":
    app()

python spatial_cli.py --install-completion
# Restart the shell or run:
source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

# Export once and commit the file:
python spatial_cli.py --show-completion bash > completions/spatial_cli.bash
python spatial_cli.py --show-completion zsh  > completions/spatial_cli.zsh

# System-wide activation (Linux):
sudo cp completions/spatial_cli.bash /etc/profile.d/spatial_cli_completion.sh

pip install "typer[all]"
# Verify shellingham is present:
python -c "import shellingham; print(shellingham.detect_shell())"
# Expected output: ('bash', '/bin/bash') or ('zsh', '/usr/bin/zsh')

python spatial_cli.py --install-completion bash
python spatial_cli.py --install-completion zsh

# 1. Spatial file path completion — should list .tif/.gpkg/.shp files in ./data/
python spatial_cli.py process data/<TAB>

# 2. Format completion
python spatial_cli.py process data/input.tif --format Geo<TAB>
# Expected: GeoTIFF  GeoPackage  GeoJSON

# 3. CRS completion
python spatial_cli.py process data/input.tif --crs EPSG:32<TAB>
# Expected: EPSG:3257  EPSG:32633  EPSG:32632

# 4. Smoke-test the completion subprocess directly (Bash):
COMP_WORDS="spatial_cli process data/in" COMP_CWORD=2 \
  _TYPER_COMPLETE_ARGS="process data/in" \
  _SPATIAL_CLI_COMPLETE=bash_complete \
  python spatial_cli.py