amap-cli 0.1.0__py3-none-any.whl

amap_cli/search_poi.py

@@ -0,0 +1,281 @@
+"""POI search command registration and handlers."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any
+
+from amap_cli.api import AmapApiClient
+from amap_cli.errors import ValidationError
+from amap_cli.params import Coordinate, normalize_text_argument, parse_coordinate
+
+DEFAULT_RADIUS = 3000
+DEFAULT_PAGE_SIZE = 10
+DEFAULT_PAGE_INDEX = 1
+MAX_PAGE_SIZE = 25
+MAX_RADIUS = 50000
+TEXT_SEARCH_PATH = "/v3/place/text"
+AROUND_SEARCH_PATH = "/v3/place/around"
+
+
+@dataclass(frozen=True, slots=True)
+class SearchPoiRequest:
+    """Normalized search-poi command input."""
+
+    keyword: str
+    city: str | None
+    center: Coordinate | None
+    radius: int
+    page_size: int
+    page_index: int
+
+    @property
+    def is_nearby_search(self) -> bool:
+        """Return whether the request should use nearby search."""
+        return self.center is not None
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> "SearchPoiRequest":
+        """Build a validated request from parsed CLI arguments."""
+        keyword = normalize_text_argument(args.keyword, "keyword")
+        city = (
+            normalize_text_argument(args.city, "city")
+            if args.city is not None
+            else None
+        )
+        center = (
+            parse_coordinate(args.center, "center")
+            if args.center is not None
+            else None
+        )
+
+        radius = _validate_positive_int(
+            args.radius,
+            "radius",
+            min_value=1,
+            max_value=MAX_RADIUS,
+        )
+        page_size = _validate_positive_int(
+            args.pageSize,
+            "pageSize",
+            min_value=1,
+            max_value=MAX_PAGE_SIZE,
+        )
+        page_index = _validate_positive_int(
+            args.pageIndex,
+            "pageIndex",
+            min_value=1,
+        )
+
+        if center is None and getattr(args, "radius", None) != DEFAULT_RADIUS:
+            raise ValidationError("仅在提供 `--center` 时允许传入 `--radius`。")
+
+        return cls(
+            keyword=keyword,
+            city=city,
+            center=center,
+            radius=radius,
+            page_size=page_size,
+            page_index=page_index,
+        )
+
+    def to_api_request(self) -> tuple[str, dict[str, Any]]:
+        """Convert the normalized request to Amap REST API arguments."""
+        params: dict[str, Any] = {
+            "keywords": self.keyword,
+            "offset": self.page_size,
+            "page": self.page_index,
+            "extensions": "all",
+        }
+
+        if self.is_nearby_search:
+            params["location"] = self.center.to_amap_value() if self.center else None
+            params["radius"] = self.radius
+            return AROUND_SEARCH_PATH, params
+
+        if self.city is not None:
+            params["city"] = self.city
+        return TEXT_SEARCH_PATH, params
+
+    def build_state(self, total: int) -> dict[str, Any]:
+        """Build CLI-facing state metadata."""
+        state: dict[str, Any] = {
+            "keyword": self.keyword,
+            "pageSize": self.page_size,
+            "pageIndex": self.page_index,
+            "extensions": "all",
+            "resultCount": total,
+        }
+
+        if self.is_nearby_search:
+            state["center"] = (
+                [self.center.longitude, self.center.latitude]
+                if self.center is not None
+                else None
+            )
+            state["radius"] = self.radius
+        elif self.city is not None:
+            state["city"] = self.city
+
+        return state
+
+
+def register_search_poi_command(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> argparse.ArgumentParser:
+    """Register the `search-poi` command on a subparser collection."""
+    parser = subparsers.add_parser(
+        "search-poi",
+        help="搜索 POI",
+        description="按关键词或周边范围搜索 POI。",
+    )
+    add_search_poi_arguments(parser)
+    parser.set_defaults(handler=handle_search_poi)
+    return parser
+
+
+def add_search_poi_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add search-poi arguments to a parser."""
+    parser.add_argument("--keyword", required=True, help="搜索关键词")
+    parser.add_argument("--city", help="搜索城市")
+    parser.add_argument("--center", help="周边搜索中心，格式为 `经度,纬度`")
+    parser.add_argument(
+        "--radius",
+        type=int,
+        default=DEFAULT_RADIUS,
+        help=f"周边搜索半径（米），默认 {DEFAULT_RADIUS}",
+    )
+    parser.add_argument(
+        "--pageSize",
+        type=int,
+        default=DEFAULT_PAGE_SIZE,
+        help=f"每页数量，范围 1-{MAX_PAGE_SIZE}，默认 {DEFAULT_PAGE_SIZE}",
+    )
+    parser.add_argument(
+        "--pageIndex",
+        type=int,
+        default=DEFAULT_PAGE_INDEX,
+        help=f"页码，从 1 开始，默认 {DEFAULT_PAGE_INDEX}",
+    )
+
+
+def handle_search_poi(
+    args: argparse.Namespace,
+    *,
+    client: AmapApiClient | None = None,
+) -> dict[str, Any]:
+    """Handle the `search-poi` command and normalize the response."""
+    request = SearchPoiRequest.from_args(args)
+    api_client = client or AmapApiClient()
+    path, params = request.to_api_request()
+    payload = api_client.get(path, params=params)
+
+    total = _parse_total(payload.get("count"))
+    return {
+        "state": request.build_state(total),
+        "pois": _normalize_pois(payload.get("pois")),
+        "total": total,
+        "pageIndex": request.page_index,
+        "pageSize": request.page_size,
+    }
+
+
+def _validate_positive_int(
+    value: Any,
+    field_name: str,
+    *,
+    min_value: int,
+    max_value: int | None = None,
+) -> int:
+    """Validate a positive integer CLI argument."""
+    if not isinstance(value, int):
+        raise ValidationError(f"`{field_name}` 必须是整数。")
+    if value < min_value:
+        raise ValidationError(f"`{field_name}` 必须大于等于 {min_value}。")
+    if max_value is not None and value > max_value:
+        raise ValidationError(f"`{field_name}` 必须小于等于 {max_value}。")
+    return value
+
+
+def _parse_total(value: Any) -> int:
+    """Convert the Amap `count` field to an integer."""
+    if value in (None, ""):
+        return 0
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _normalize_pois(value: Any) -> list[dict[str, Any]]:
+    """Normalize the raw Amap POI list to the CLI output shape."""
+    if not isinstance(value, list):
+        return []
+
+    return [_normalize_poi(item) for item in value if isinstance(item, dict)]
+
+
+def _normalize_poi(raw: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a single POI payload."""
+    return {
+        "id": _normalize_optional_text(raw.get("id")),
+        "name": _normalize_optional_text(raw.get("name")),
+        "type": _normalize_optional_text(raw.get("type")),
+        "location": _parse_location(raw.get("location")),
+        "address": _normalize_optional_text(raw.get("address")),
+        "distance": _parse_distance(raw.get("distance")),
+        "tel": _normalize_optional_text(raw.get("tel")),
+        "pname": _normalize_optional_text(raw.get("pname")),
+        "cityname": _normalize_optional_text(raw.get("cityname")),
+        "adname": _normalize_optional_text(raw.get("adname")),
+        "photo": _extract_photo(raw.get("photos")),
+    }
+
+
+def _parse_location(value: Any) -> list[float] | None:
+    """Parse API location strings into `[lng, lat]` lists."""
+    if not isinstance(value, str) or not value.strip():
+        return None
+
+    parts = [part.strip() for part in value.split(",", 1)]
+    if len(parts) != 2:
+        return None
+
+    try:
+        return [float(parts[0]), float(parts[1])]
+    except ValueError:
+        return None
+
+
+def _parse_distance(value: Any) -> int | None:
+    """Convert the API distance field to an integer when available."""
+    if value in (None, ""):
+        return None
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def _extract_photo(value: Any) -> str | None:
+    """Extract the first photo URL from the Amap photo list."""
+    if not isinstance(value, list):
+        return None
+
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        url = _normalize_optional_text(item.get("url"))
+        if url is not None:
+            return url
+
+    return None
+
+
+def _normalize_optional_text(value: Any) -> str | None:
+    """Trim optional text fields and normalize empty strings to None."""
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    return normalized or None

amap_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: amap-cli
+Version: 0.1.0
+Summary: Pure command-line CLI for Amap APIs.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# amap-cli
+
+`amap-cli` 是一个基于高德开放平台 Web API 的纯命令行工具，面向终端环境和 AI Agent 使用。
+
+## 功能特性
+
+- 纯命令行调用高德地图 API
+- 支持命令行写入和读取高德 API Key
+- 支持两点直线距离计算
+- 支持路径规划
+- 支持 POI 搜索
+- 所有命令统一返回机器可读 JSON
+- 提供配套的 Agent skill，便于在智能体环境中直接调用
+
+## 安装与使用
+
+### 方式一：直接使用 `uvx` 运行
+
+项目发布到 PyPI 后，可以直接执行：
+
+```bash
+uvx amap-cli --help
+```
+
+配置高德 API Key：
+
+```bash
+uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
+```
+
+路径规划示例：
+
+```bash
+uvx amap-cli route \
+  --from 北京南站 \
+  --to 天安门 \
+  --type driving
+```
+
+直线距离示例：
+
+```bash
+uvx amap-cli distance \
+  --from 116.397,39.909 \
+  --to 116.407,39.904
+```
+
+POI 搜索示例：
+
+```bash
+uvx amap-cli search-poi \
+  --keyword 星巴克 \
+  --city 北京 \
+  --pageSize 5
+```
+
+### 方式二：安装后使用
+
+如果希望安装到本机工具目录，执行：
+
+```bash
+uv tool install amap-cli
+```
+
+安装完成后可直接调用：
+
+```bash
+amap-cli --help
+```
+
+配置和业务命令示例：
+
+```bash
+amap-cli config set --api-key <YOUR_AMAP_KEY>
+amap-cli distance --from 116.397,39.909 --to 116.407,39.904
+amap-cli route --from 北京南站 --to 天安门 --type driving
+amap-cli search-poi --keyword 星巴克 --city 北京
+```
+
+## Skill 使用说明
+
+本项目提供了配套的 `amap-cli` skill，适合在支持 skill 的 Agent 环境中使用。
+
+- skill 的目标是让 Agent 直接通过 `uvx amap-cli` 调用本工具
+- 使用方式与上面的“直接使用 `uvx` 运行”一致
+- 使用前先配置高德 API Key，之后即可发起路径规划和 POI 搜索
+- `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
+- 建议 Agent 直接解析命令返回的 JSON 结果
+
+## 命令说明
+
+### 配置
+
+写入 API Key：
+
+```bash
+amap-cli config set --api-key <YOUR_AMAP_KEY>
+```
+
+查看当前配置：
+
+```bash
+amap-cli config show
+```
+
+配置会按照当前操作系统规范保存在用户配置目录中。macOS 下默认路径为：
+
+```text
+~/Library/Application Support/amap-cli/config.json
+```
+
+### 路径规划
+
+基础格式：
+
+```bash
+amap-cli route \
+  --from <结构化地址|地标名称|经度,纬度> \
+  --to <结构化地址|地标名称|经度,纬度> \
+  --type <driving|walking|riding|transit>
+```
+
+可选参数：
+
+- `--from-name`
+- `--to-name`
+- `--waypoints`
+- `--policy`
+- `--strategy`
+- `--city`
+
+说明：
+
+- `--waypoints` 和 `--policy` 仅 `driving` 支持
+- `--strategy` 和 `--city` 仅 `transit` 支持
+- 地理编码仅支持详细的结构化地址，以及地标性名胜景区、建筑物名称
+- 当起点、终点或途经点使用上述名称并解析成功时，返回结果中的对应节点会附带 `formattedAddress`
+- 对于其他较模糊的名称，建议先通过 `search-poi` 获取目标地点坐标，再调用 `route`
+- 不支持 `--json` 输入
+
+### 直线距离
+
+基础格式：
+
+```bash
+amap-cli distance \
+  --from <结构化地址|地标名称|经度,纬度> \
+  --to <结构化地址|地标名称|经度,纬度>
+```
+
+可选参数：
+
+- `--from-name`
+- `--to-name`
+
+说明：
+
+- 当 `--from` 和 `--to` 都是坐标时，直接在本地计算直线距离
+- 当任一输入为结构化地址或地标性名胜景区、建筑物名称时，会先调用高德地理编码接口解析坐标，再做本地计算
+- 当输入为上述名称时，返回结果中的 `state.from.formattedAddress` / `state.to.formattedAddress` 会带上高德解析出的完整地址
+- 对于其他较模糊的名称，建议先通过 `search-poi` 获取目标地点坐标，再调用 `distance`
+- 结果中的 `summary.distance` 单位为米
+- 不支持 `--json` 输入
+
+### POI 搜索
+
+基础格式：
+
+```bash
+amap-cli search-poi --keyword <关键词>
+```
+
+可选参数：
+
+- `--city`
+- `--center`
+- `--radius`
+- `--pageSize`
+- `--pageIndex`
+
+说明：
+
+- 传入 `--center` 时执行周边搜索
+- 未传入 `--center` 时执行关键词搜索
+- 不支持 `--json` 输入
+
+## 输出格式
+
+成功时：
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null
+}
+```
+
+失败时：
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "INVALID_ARGUMENT",
+    "message": "错误说明",
+    "details": {}
+  }
+}
+```
+
+## 本地开发
+
+安装项目依赖：
+
+```bash
+uv sync
+```
+
+本地运行：
+
+```bash
+uv run amap-cli --help
+```
+
+## PyPI 发布
+
+### 1. 确认版本号
+
+每次发布前，先更新 `pyproject.toml` 中的 `version`。  
+PyPI 不允许重复上传同一个版本号的分发包。
+
+### 2. 构建分发包
+
+```bash
+uv build
+```
+
+构建成功后会在 `dist/` 目录下生成：
+
+- `*.tar.gz`
+- `*.whl`
+
+### 3. 准备 PyPI Token
+
+登录 PyPI 后创建 API Token，推荐通过环境变量传入：
+
+```bash
+export UV_PUBLISH_TOKEN="pypi-你的token"
+```
+
+### 4. 先发布到 TestPyPI 验证（推荐）
+
+```bash
+uv publish \
+  --publish-url https://test.pypi.org/legacy/ \
+  --check-url https://test.pypi.org/simple/
+```
+
+如果只是验证包能否被安装，可以执行：
+
+```bash
+uvx --index-url https://test.pypi.org/simple/ amap-cli --help
+```
+
+### 5. 发布到正式 PyPI
+
+确认 TestPyPI 验证通过后，执行：
+
+```bash
+uv publish
+```
+
+### 6. 发布后验证
+
+发布完成后，推荐优先使用 `uvx` 做一次快速验证：
+
+```bash
+uvx amap-cli --help
+```
+
+发布后，推荐优先使用 `uvx amap-cli` 进行一次性调用，或使用 `uv tool install amap-cli` 安装到本地。

amap_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+amap_cli/__init__.py,sha256=fIvpzGG20FCyIKhTdrMw2SaUL6l-rBxWPkka7uCLkoQ,74
+amap_cli/__main__.py,sha256=I_7ztHJAX_h8YivkMSLeC8suZmAsBPiJVVq8JvhIwG4,175
+amap_cli/api.py,sha256=tBxSuJIYcK_vTBuFu0JBNPmkfGiWVGfl2aagI-fDj2s,3284
+amap_cli/cli.py,sha256=hiOu7OanlzoVU4gq03vFPSIOftQQWsmslXXf2mdVZxc,4374
+amap_cli/config.py,sha256=7yd9LgVQphxd-BSnpjN6DbBY0vs-Jvx2GqjMyQT6XR4,5040
+amap_cli/distance.py,sha256=d3cRX6_TjK6wEiosAufSb1n5fnM2nXdL76sU5_ltg6k,6035
+amap_cli/errors.py,sha256=3D4pozE-T073FqcnyHg4XhdExEf9K_P8PpKsVu84RVM,2356
+amap_cli/geocode.py,sha256=zjBLaWY2bbNSHG36N48DLfSqcQy3vWLOGeBLszrzm0A,1842
+amap_cli/output.py,sha256=fDGp9FUnBuHNZc94GfNjNnlKPYFjHXMqxATfhVh-Ea0,1132
+amap_cli/params.py,sha256=TF0-AHHSgCn2ORxb55aZtfwOXpPebAr6MBO_wTCZodw,2398
+amap_cli/route.py,sha256=su4a3U0ZPSrfkhujdRXMxvmEdbP71OeOlWNM4vddvv0,20667
+amap_cli/search_poi.py,sha256=CgRsII7mC2pl2wbIy34Ta9Is_XlOOJXcmuZYB88Cs0k,8686
+amap_cli-0.1.0.dist-info/METADATA,sha256=p-El-zCN-bYrfeDYg1GUkm5hpmdkrsHtiBefZj8QVUk,5803
+amap_cli-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+amap_cli-0.1.0.dist-info/entry_points.txt,sha256=CUABuFvXeD0w7roHluAZamzJws04DcezkMnXpxJAFkA,47
+amap_cli-0.1.0.dist-info/RECORD,,

amap_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

amap_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+amap-cli = amap_cli.cli:main