amap-cli 0.1.0__py3-none-any.whl

amap_cli/__init__.py

@@ -0,0 +1,5 @@
+"""amap-cli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

amap_cli/__main__.py

@@ -0,0 +1,9 @@
+"""Module entrypoint for `python -m amap_cli`."""
+
+from __future__ import annotations
+
+from amap_cli.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

amap_cli/api.py

@@ -0,0 +1,90 @@
+"""Common Amap API client for future business commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from amap_cli import __version__
+from amap_cli.config import AmapConfig, load_config
+from amap_cli.errors import ApiRequestError, ApiResponseError, MissingConfigError
+
+
+class AmapApiClient:
+    """HTTP client that injects config and normalizes Amap failures."""
+
+    def __init__(self, config: AmapConfig | None = None) -> None:
+        self.config = config or load_config(required=True)
+        if self.config is None or not self.config.api_key:
+            raise MissingConfigError(
+                "缺少高德 API Key，请先执行 `amap-cli config set --api-key <KEY>`。"
+            )
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a GET request to the Amap REST API."""
+        query_params = dict(params or {})
+        query_params["key"] = self.config.api_key
+
+        url = self._build_url(path, query_params)
+        request = Request(
+            url,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": f"amap-cli/{__version__}",
+            },
+            method="GET",
+        )
+
+        try:
+            with urlopen(request, timeout=self.config.timeout_seconds) as response:
+                body = response.read().decode("utf-8")
+        except HTTPError as exc:
+            response_body = exc.read().decode("utf-8", errors="ignore")
+            raise ApiRequestError(
+                f"高德 API HTTP 请求失败：{exc.code}",
+                details={"status": exc.code, "body": response_body},
+            ) from exc
+        except URLError as exc:
+            raise ApiRequestError(
+                "无法连接高德 API。",
+                details={"reason": str(exc.reason)},
+            ) from exc
+        except TimeoutError as exc:
+            raise ApiRequestError("请求高德 API 超时。") from exc
+
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError as exc:
+            raise ApiRequestError(
+                "高德 API 返回了非 JSON 响应。",
+                details={"body": body[:500]},
+            ) from exc
+
+        self._raise_for_amap_error(payload)
+        return payload
+
+    def _build_url(self, path: str, params: dict[str, Any]) -> str:
+        """Build a full request URL from config and query params."""
+        normalized_path = path if path.startswith("/") else f"/{path}"
+        query = urlencode(params, doseq=True)
+        return f"{self.config.base_url.rstrip('/')}{normalized_path}?{query}"
+
+    def _raise_for_amap_error(self, payload: dict[str, Any]) -> None:
+        """Convert business-level Amap error payloads to exceptions."""
+        status = payload.get("status")
+        if status is None:
+            return
+
+        if str(status) == "1":
+            return
+
+        raise ApiResponseError(
+            payload.get("info") or "高德 API 返回失败。",
+            details={
+                "infocode": payload.get("infocode"),
+                "info": payload.get("info"),
+            },
+        )

amap_cli/cli.py

@@ -0,0 +1,129 @@
+"""CLI entrypoint and command registration."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any, Sequence
+
+from amap_cli.config import get_config_path, load_config, save_config
+from amap_cli.distance import register_distance_command
+from amap_cli.errors import AmapCliError, ValidationError
+from amap_cli.output import emit_error, emit_success
+from amap_cli.route import register_route_command
+from amap_cli.search_poi import register_search_poi_command
+
+
+class JsonArgumentParser(argparse.ArgumentParser):
+    """Argument parser that routes validation failures to JSON output."""
+
+    def error(self, message: str) -> None:
+        raise ValidationError(message)
+
+
+def build_parser() -> JsonArgumentParser:
+    """Create the root CLI parser."""
+    parser = JsonArgumentParser(
+        prog="amap-cli",
+        description="纯命令行高德地图 CLI 基础工具。",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    _register_config_command(subparsers)
+    register_distance_command(subparsers)
+    register_route_command(subparsers)
+    register_search_poi_command(subparsers)
+    return parser
+
+
+def _register_config_command(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register configuration management commands."""
+    parser = subparsers.add_parser("config", help="写入或查看高德 API 配置")
+    parser.set_defaults(handler=_handle_config_root)
+
+    config_subparsers = parser.add_subparsers(dest="config_command")
+
+    set_parser = config_subparsers.add_parser("set", help="写入高德 API 配置")
+    set_parser.add_argument("--api-key", "--key", dest="api_key", help="高德 API Key")
+    set_parser.add_argument("--base-url", help="高德 API 基础地址")
+    set_parser.add_argument(
+        "--timeout-seconds",
+        type=float,
+        help="请求超时时间（秒）",
+    )
+    set_parser.set_defaults(handler=_handle_config_set)
+
+    show_parser = config_subparsers.add_parser("show", help="查看当前配置（敏感信息脱敏）")
+    show_parser.set_defaults(handler=_handle_config_show)
+
+
+def _handle_config_root(_: argparse.Namespace) -> dict[str, Any]:
+    """Show help when `config` is called without a subcommand."""
+    raise ValidationError("缺少配置子命令，请使用 `config set` 或 `config show`。")
+
+
+def _handle_config_set(args: argparse.Namespace) -> dict[str, Any]:
+    """Persist configuration values."""
+    if (
+        args.api_key is None
+        and args.base_url is None
+        and args.timeout_seconds is None
+    ):
+        raise ValidationError(
+            "请至少提供一个配置项，例如 `--api-key`、`--base-url` 或 `--timeout-seconds`。"
+        )
+
+    config = save_config(
+        api_key=args.api_key,
+        base_url=args.base_url,
+        timeout_seconds=args.timeout_seconds,
+    )
+    return {
+        "message": "配置已保存。",
+        "config_path": str(get_config_path()),
+        "config": config.to_dict(mask_secrets=True),
+    }
+
+
+def _handle_config_show(_: argparse.Namespace) -> dict[str, Any]:
+    """Display the current configuration with masked secrets."""
+    config = load_config(required=False)
+    return {
+        "configured": config is not None and bool(config.api_key),
+        "config_path": str(get_config_path()),
+        "config": config.to_dict(mask_secrets=True) if config is not None else None,
+    }
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and emit unified JSON output for command results."""
+    parser = build_parser()
+
+    try:
+        args = parser.parse_args(argv)
+        if not hasattr(args, "handler"):
+            parser.print_help()
+            return 0
+
+        result = args.handler(args)
+        emit_success(result)
+        return 0
+    except AmapCliError as exc:
+        emit_error(exc)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        error = AmapCliError("操作已取消。", code="INTERRUPTED", exit_code=130)
+        emit_error(error)
+        return error.exit_code
+    except SystemExit:
+        raise
+    except Exception as exc:
+        error = AmapCliError(
+            "发生未预期错误。",
+            code="UNEXPECTED_ERROR",
+            details={"type": type(exc).__name__},
+            exit_code=1,
+        )
+        emit_error(error)
+        return error.exit_code

amap_cli/config.py

@@ -0,0 +1,155 @@
+"""Configuration persistence for Amap API access."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from amap_cli.errors import ConfigError, MissingConfigError, ValidationError
+
+APP_NAME = "amap-cli"
+CONFIG_FILE_NAME = "config.json"
+DEFAULT_BASE_URL = "https://restapi.amap.com"
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+@dataclass(slots=True)
+class AmapConfig:
+    """User configuration required by the CLI."""
+
+    api_key: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> "AmapConfig":
+        """Create a config object from persisted JSON data."""
+        api_key = raw.get("api_key")
+        base_url = raw.get("base_url", DEFAULT_BASE_URL)
+        timeout_seconds = raw.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS)
+
+        if api_key is not None and not isinstance(api_key, str):
+            raise ConfigError("配置文件中的 api_key 格式无效。")
+        if not isinstance(base_url, str) or not base_url.strip():
+            raise ConfigError("配置文件中的 base_url 格式无效。")
+        if not isinstance(timeout_seconds, (int, float)) or timeout_seconds <= 0:
+            raise ConfigError("配置文件中的 timeout_seconds 格式无效。")
+
+        normalized_api_key = None
+        if api_key is not None:
+            normalized_api_key = api_key.strip() or None
+
+        return cls(
+            api_key=normalized_api_key,
+            base_url=base_url.strip(),
+            timeout_seconds=float(timeout_seconds),
+        )
+
+    def to_dict(self, *, mask_secrets: bool = False) -> dict[str, Any]:
+        """Serialize the config for persistence or display."""
+        payload = asdict(self)
+        if mask_secrets:
+            payload["api_key"] = mask_secret(self.api_key)
+        return payload
+
+
+def get_config_dir() -> Path:
+    """Return the OS-specific configuration directory."""
+    system_name = platform.system().lower()
+
+    if system_name == "darwin":
+        return Path.home() / "Library" / "Application Support" / APP_NAME
+
+    if system_name == "windows":
+        app_data = os.environ.get("APPDATA")
+        if app_data:
+            return Path(app_data) / APP_NAME
+        return Path.home() / "AppData" / "Roaming" / APP_NAME
+
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        return Path(xdg_config_home) / APP_NAME
+    return Path.home() / ".config" / APP_NAME
+
+
+def get_config_path() -> Path:
+    """Return the full configuration file path."""
+    return get_config_dir() / CONFIG_FILE_NAME
+
+
+def load_config(*, required: bool = False) -> AmapConfig | None:
+    """Load config from disk, optionally requiring it to exist."""
+    path = get_config_path()
+    if not path.exists():
+        if required:
+            raise MissingConfigError(
+                "未找到高德 API 配置，请先执行 `amap-cli config set --api-key <KEY>`。"
+            )
+        return None
+
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError("配置文件不是合法的 JSON。", details={"path": str(path)}) from exc
+    except OSError as exc:
+        raise ConfigError("读取配置文件失败。", details={"path": str(path)}) from exc
+
+    if not isinstance(raw, dict):
+        raise ConfigError("配置文件内容格式无效。", details={"path": str(path)})
+
+    return AmapConfig.from_dict(raw)
+
+
+def save_config(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout_seconds: float | None = None,
+) -> AmapConfig:
+    """Persist config updates to the OS-specific config path."""
+    config = load_config(required=False) or AmapConfig()
+
+    if api_key is not None:
+        api_key = api_key.strip()
+        if not api_key:
+            raise ValidationError("`--api-key` 不能为空。")
+        config.api_key = api_key
+
+    if base_url is not None:
+        base_url = base_url.strip()
+        if not base_url:
+            raise ValidationError("`--base-url` 不能为空。")
+        config.base_url = base_url
+
+    if timeout_seconds is not None:
+        if timeout_seconds <= 0:
+            raise ValidationError("`--timeout-seconds` 必须大于 0。")
+        config.timeout_seconds = float(timeout_seconds)
+
+    path = get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(config.to_dict(), ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    if os.name != "nt":
+        try:
+            path.chmod(0o600)
+        except OSError:
+            pass
+
+    return config
+
+
+def mask_secret(value: str | None) -> str | None:
+    """Mask a secret for display in CLI output."""
+    if value is None:
+        return None
+    if len(value) <= 4:
+        return "*" * len(value)
+    return "*" * (len(value) - 4) + value[-4:]

amap_cli/distance.py

@@ -0,0 +1,194 @@
+"""Straight-line distance command registration and handlers."""
+
+from __future__ import annotations
+
+import argparse
+import math
+from dataclasses import dataclass
+from typing import Callable
+
+from amap_cli.api import AmapApiClient
+from amap_cli.geocode import geocode_text
+from amap_cli.params import (
+    Coordinate,
+    LocationInput,
+    normalize_text_argument,
+    parse_location_input,
+)
+
+EARTH_RADIUS_METERS = 6_371_008.8
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedDistanceRequest:
+    """Validated distance command arguments before geocoding."""
+
+    origin: LocationInput
+    origin_name: str | None
+    destination: LocationInput
+    destination_name: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedDistancePoint:
+    """Distance point after resolving names to coordinates when needed."""
+
+    raw: str
+    name: str
+    coordinate: Coordinate
+    formatted_address: str | None = None
+
+    def to_state(self) -> dict[str, object]:
+        """Convert the point to the CLI state shape."""
+        state: dict[str, object] = {
+            "name": self.name,
+            "position": [
+                round(self.coordinate.longitude, 6),
+                round(self.coordinate.latitude, 6),
+            ],
+        }
+        if self.formatted_address is not None:
+            state["formattedAddress"] = self.formatted_address
+        return state
+
+
+def register_distance_command(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> argparse.ArgumentParser:
+    """Register the `distance` command on a subparser collection."""
+    parser = subparsers.add_parser(
+        "distance",
+        help="计算两个地点之间的直线距离",
+        description="计算两个地点之间的直线距离；坐标直接本地计算，地名会先做地理编码。",
+    )
+    parser.add_argument(
+        "--from",
+        dest="origin",
+        required=True,
+        help="起点，支持地名或 `经度,纬度`",
+    )
+    parser.add_argument(
+        "--from-name",
+        dest="origin_name",
+        help="起点显示名称，通常配合坐标使用",
+    )
+    parser.add_argument(
+        "--to",
+        dest="destination",
+        required=True,
+        help="终点，支持地名或 `经度,纬度`",
+    )
+    parser.add_argument(
+        "--to-name",
+        dest="destination_name",
+        help="终点显示名称，通常配合坐标使用",
+    )
+    parser.set_defaults(handler=handle_distance_command)
+    return parser
+
+
+def handle_distance_command(
+    args: argparse.Namespace,
+    *,
+    client: AmapApiClient | None = None,
+) -> dict[str, object]:
+    """Handle the `distance` command and return normalized JSON data."""
+    request = _prepare_distance_request(args)
+    client_holder: list[AmapApiClient | None] = [client]
+
+    def get_client() -> AmapApiClient:
+        if client_holder[0] is None:
+            client_holder[0] = AmapApiClient()
+        return client_holder[0]
+
+    origin = _resolve_distance_point(
+        request.origin,
+        display_name=request.origin_name,
+        client_factory=get_client,
+    )
+
+    destination = _resolve_distance_point(
+        request.destination,
+        display_name=request.destination_name,
+        client_factory=get_client,
+    )
+
+    distance_meters = _calculate_straight_line_distance(
+        origin.coordinate,
+        destination.coordinate,
+    )
+
+    return {
+        "state": {
+            "from": origin.to_state(),
+            "to": destination.to_state(),
+            "mode": "straight_line",
+            "unit": "meter",
+            "source": "local_haversine",
+        },
+        "summary": {
+            "distance": distance_meters,
+            "distanceKilometers": round(distance_meters / 1000, 3),
+        },
+    }
+
+
+def _prepare_distance_request(args: argparse.Namespace) -> PreparedDistanceRequest:
+    """Validate and normalize distance command arguments."""
+    return PreparedDistanceRequest(
+        origin=parse_location_input(args.origin, "from"),
+        origin_name=_normalize_optional_text(args.origin_name, "from-name"),
+        destination=parse_location_input(args.destination, "to"),
+        destination_name=_normalize_optional_text(args.destination_name, "to-name"),
+    )
+
+
+def _normalize_optional_text(value: str | None, field_name: str) -> str | None:
+    """Trim an optional text argument when present."""
+    if value is None:
+        return None
+    return normalize_text_argument(value, field_name)
+
+
+def _resolve_distance_point(
+    location: LocationInput,
+    *,
+    display_name: str | None,
+    client_factory: Callable[[], AmapApiClient],
+) -> ResolvedDistancePoint:
+    """Resolve a distance point to a display name and coordinate."""
+    if location.coordinate is not None:
+        return ResolvedDistancePoint(
+            raw=location.raw,
+            name=display_name or location.raw,
+            coordinate=location.coordinate,
+        )
+
+    client = client_factory()
+    geocoded = geocode_text(location.name or location.raw, client=client)
+    return ResolvedDistancePoint(
+        raw=location.raw,
+        name=display_name or location.name or location.raw,
+        coordinate=geocoded.coordinate,
+        formatted_address=geocoded.formatted_address,
+    )
+
+
+def _calculate_straight_line_distance(origin: Coordinate, destination: Coordinate) -> int:
+    """Calculate the great-circle distance in meters with the Haversine formula."""
+    origin_lat = math.radians(origin.latitude)
+    origin_lng = math.radians(origin.longitude)
+    destination_lat = math.radians(destination.latitude)
+    destination_lng = math.radians(destination.longitude)
+
+    delta_lat = destination_lat - origin_lat
+    delta_lng = destination_lng - origin_lng
+
+    haversine = (
+        math.sin(delta_lat / 2) ** 2
+        + math.cos(origin_lat)
+        * math.cos(destination_lat)
+        * math.sin(delta_lng / 2) ** 2
+    )
+    central_angle = 2 * math.atan2(math.sqrt(haversine), math.sqrt(1 - haversine))
+    return round(EARTH_RADIUS_METERS * central_angle)

amap_cli/errors.py

@@ -0,0 +1,87 @@
+"""Custom error types used by the CLI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AmapCliError(Exception):
+    """Base exception with a stable machine-readable payload."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "CLI_ERROR",
+        details: Any | None = None,
+        exit_code: int = 1,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details
+        self.exit_code = exit_code
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the error to the unified JSON output shape."""
+        return {
+            "code": self.code,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+class ValidationError(AmapCliError):
+    """Raised when command arguments fail validation."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(
+            message,
+            code="INVALID_ARGUMENT",
+            details=details,
+            exit_code=2,
+        )
+
+
+class ConfigError(AmapCliError):
+    """Raised when configuration is missing or invalid."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "CONFIG_ERROR",
+        details: Any | None = None,
+    ) -> None:
+        super().__init__(message, code=code, details=details, exit_code=1)
+
+
+class MissingConfigError(ConfigError):
+    """Raised when a required config item has not been configured yet."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(message, code="MISSING_CONFIG", details=details)
+
+
+class ApiRequestError(AmapCliError):
+    """Raised when the HTTP request to Amap cannot be completed."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(
+            message,
+            code="API_REQUEST_ERROR",
+            details=details,
+            exit_code=1,
+        )
+
+
+class ApiResponseError(AmapCliError):
+    """Raised when the Amap API returns a business-level failure."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(
+            message,
+            code="API_RESPONSE_ERROR",
+            details=details,
+            exit_code=1,
+        )