amap-cli 0.1.0__py3-none-any.whl

amap_cli/geocode.py

@@ -0,0 +1,61 @@
+"""Shared geocoding helpers for CLI commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from amap_cli.api import AmapApiClient
+from amap_cli.errors import ApiResponseError
+from amap_cli.params import Coordinate, parse_coordinate
+
+
+@dataclass(frozen=True, slots=True)
+class GeocodeResult:
+    """Normalized geocoding result for CLI commands."""
+
+    coordinate: Coordinate
+    formatted_address: str | None
+
+
+def geocode_text(
+    value: str,
+    *,
+    client: AmapApiClient,
+    city: str | None = None,
+) -> GeocodeResult:
+    """Convert a place name to a coordinate with the geocoding API."""
+    params: dict[str, Any] = {"address": value}
+    if city is not None:
+        params["city"] = city
+
+    payload = client.get("/v3/geocode/geo", params=params)
+    geocodes = payload.get("geocodes")
+    if not isinstance(geocodes, list) or not geocodes:
+        raise ApiResponseError(
+            f"未找到地点：{value}",
+            details={"address": value, "city": city},
+        )
+
+    first = geocodes[0]
+    if not isinstance(first, dict):
+        raise ApiResponseError(
+            "地理编码响应格式无效。",
+            details={"address": value, "city": city},
+        )
+
+    location_value = first.get("location")
+    if not isinstance(location_value, str) or not location_value.strip():
+        raise ApiResponseError(
+            "地理编码结果缺少坐标信息。",
+            details={"address": value, "city": city},
+        )
+
+    formatted_address = first.get("formatted_address")
+    if not isinstance(formatted_address, str) or not formatted_address.strip():
+        formatted_address = None
+
+    return GeocodeResult(
+        coordinate=parse_coordinate(location_value, "geocode.location"),
+        formatted_address=formatted_address,
+    )

amap_cli/output.py

@@ -0,0 +1,45 @@
+"""Helpers for unified JSON output."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from amap_cli.errors import AmapCliError
+
+
+def build_success_payload(data: Any) -> dict[str, Any]:
+    """Build the standard success payload."""
+    return {
+        "success": True,
+        "data": data,
+        "error": None,
+    }
+
+
+def build_error_payload(error: AmapCliError) -> dict[str, Any]:
+    """Build the standard error payload."""
+    return {
+        "success": False,
+        "data": None,
+        "error": error.to_dict(),
+    }
+
+
+def write_json(payload: dict[str, Any], *, stream: TextIO | None = None) -> None:
+    """Write a JSON payload as a single CLI response."""
+    if stream is None:
+        stream = sys.stdout
+    json.dump(payload, stream, ensure_ascii=False, indent=2)
+    stream.write("\n")
+
+
+def emit_success(data: Any) -> None:
+    """Print a success payload to standard output."""
+    write_json(build_success_payload(data))
+
+
+def emit_error(error: AmapCliError) -> None:
+    """Print an error payload to standard output."""
+    write_json(build_error_payload(error))

amap_cli/params.py

@@ -0,0 +1,77 @@
+"""Shared argument parsing helpers for future business commands."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from amap_cli.errors import ValidationError
+
+COORDINATE_PATTERN = re.compile(
+    r"^\s*([-+]?\d+(?:\.\d+)?)\s*,\s*([-+]?\d+(?:\.\d+)?)\s*$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Coordinate:
+    """A validated longitude/latitude pair."""
+
+    longitude: float
+    latitude: float
+
+    def to_amap_value(self) -> str:
+        """Convert to the `lng,lat` format expected by Amap APIs."""
+        return f"{self.longitude:.6f},{self.latitude:.6f}"
+
+
+@dataclass(frozen=True, slots=True)
+class LocationInput:
+    """A location argument that may be coordinates or a place name."""
+
+    raw: str
+    kind: str
+    coordinate: Coordinate | None = None
+    name: str | None = None
+
+
+def normalize_text_argument(value: str, field_name: str) -> str:
+    """Trim and validate a text argument."""
+    normalized = value.strip()
+    if not normalized:
+        raise ValidationError(f"`{field_name}` 不能为空。")
+    return normalized
+
+
+def parse_coordinate(value: str, field_name: str = "location") -> Coordinate:
+    """Parse a `lng,lat` string into a validated coordinate object."""
+    normalized = normalize_text_argument(value, field_name)
+    matched = COORDINATE_PATTERN.match(normalized)
+    if matched is None:
+        raise ValidationError(
+            f"`{field_name}` 必须是 `经度,纬度` 格式，例如 `116.397,39.909`。"
+        )
+
+    longitude = float(matched.group(1))
+    latitude = float(matched.group(2))
+
+    if not -180 <= longitude <= 180:
+        raise ValidationError(f"`{field_name}` 中的经度超出范围 [-180, 180]。")
+    if not -90 <= latitude <= 90:
+        raise ValidationError(f"`{field_name}` 中的纬度超出范围 [-90, 90]。")
+
+    return Coordinate(longitude=longitude, latitude=latitude)
+
+
+def parse_location_input(value: str, field_name: str) -> LocationInput:
+    """Parse a future route/search location argument."""
+    normalized = normalize_text_argument(value, field_name)
+
+    if COORDINATE_PATTERN.match(normalized):
+        coordinate = parse_coordinate(normalized, field_name)
+        return LocationInput(
+            raw=normalized,
+            kind="coordinate",
+            coordinate=coordinate,
+        )
+
+    return LocationInput(raw=normalized, kind="text", name=normalized)