# Python SDK

使用 Python SDK 连接 Catalog Service，读取和管理目录、数据库、表、卷、文件等资源。本页先完成一次只读的目录列表调用。

## 安装

Python SDK 要求 Python 3.9 或更高版本。当前公开版本可从指定标签安装：

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "moi-python-sdk @ git+https://github.com/matrixorigin/moi-python-sdk.git@v0.1.1.dev0"
```

确认包可导入：

```bash
python -c "from moi import RawClient; print('MOI Python SDK is ready')"
```

将已验证的版本写入依赖文件或锁文件。不要让生产环境长期跟随未固定的分支。

## 配置客户端

向部署方获取 Catalog Service 地址和 SDK Key，并设置为环境变量：

```bash
export MOI_BASE_URL="https://<catalog-service-host>"
export MOI_API_KEY="<sdk-api-key>"
```

`MOI_BASE_URL` 必须包含协议和主机名。`RawClient` 会规范化地址，并在请求中发送 `moi-key`。不要将 Genesis 访问令牌、浏览器 Cookie 或数据库密码当作 Catalog Service 的 SDK Key。

## 列出可见目录

创建 `quickstart.py`：

```python
import os

from moi import APIError, HTTPError, RawClient


def required_env(name: str) -> str:
    value = os.getenv(name, "").strip()
    if not value:
        raise RuntimeError(f"Set {name} before running this program")
    return value


client = RawClient(
    base_url=required_env("MOI_BASE_URL"),
    api_key=required_env("MOI_API_KEY"),
)

try:
    response = client.list_catalogs()
except APIError as exc:
    raise SystemExit(
        f"MOI API error: code={exc.code}, request_id={exc.request_id}"
    ) from exc
except HTTPError as exc:
    raise SystemExit(f"HTTP error: status={exc.status_code}") from exc

catalogs = response.get("list", []) if isinstance(response, dict) else []
for catalog in catalogs:
    print(f"{catalog.get('name')} (id={catalog.get('id')})")
```

运行程序：

```bash
python quickstart.py
```

调用成功后会打印当前身份可见的目录。空列表不一定表示错误，也可能表示该身份尚未拥有可见目录。

## 选择客户端

`RawClient` 提供 Catalog Service 的资源调用，并将成功响应中的 `data` 返回给应用。需要表权限角色、文件导入或 SQL 等组合操作时，可使用同一个底层客户端创建 `SDKClient`：

```python
from moi import RawClient, SDKClient

raw = RawClient(base_url="https://<catalog-service-host>", api_key="<sdk-api-key>")
client = SDKClient(raw)
```

使用前确认目标能力属于 Python SDK；不要将 Product SDK 的客户端或示例混入此处。

## 处理错误

服务返回业务错误时，SDK 抛出 `APIError`，其中的 `code` 和 `request_id` 可用于定位请求。服务返回非成功 HTTP 状态时，SDK 抛出 `HTTPError`。记录请求关联信息时不要记录 SDK Key、密码或完整敏感响应。

需要控制请求等待时间时，在创建客户端时使用该 SDK 提供的超时选项；超时只表示客户端未在等待时间内取得响应，不表示服务端操作一定没有继续执行。写操作超时后，先查询目标资源或任务状态，再决定是否重试。

## 下一步

- 使用 [Go SDK](go-sdk.md) 在 Go 应用中调用 Catalog Service。
- 使用 [Product SDK](product-sdk/index.md) 管理 MOI 产品资源。