Python SDK¶
使用 Python SDK 连接 Catalog Service，读取和管理目录、数据库、表、卷、文件等资源。本页先完成一次只读的目录列表调用。
安装¶
Python SDK 要求 Python 3.9 或更高版本。当前公开版本可从指定标签安装：
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"
确认包可导入：
python -c "from moi import RawClient; print('MOI Python SDK is ready')"
将已验证的版本写入依赖文件或锁文件。不要让生产环境长期跟随未固定的分支。
配置客户端¶
向部署方获取 Catalog Service 地址和 SDK Key，并设置为环境变量：
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：
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')})")
运行程序：
python quickstart.py
调用成功后会打印当前身份可见的目录。空列表不一定表示错误，也可能表示该身份尚未拥有可见目录。
选择客户端¶
RawClient 提供 Catalog Service 的资源调用，并将成功响应中的 data 返回给应用。需要表权限角色、文件导入或 SQL 等组合操作时，可使用同一个底层客户端创建 SDKClient：
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 应用中调用 Catalog Service。
使用 Product SDK 管理 MOI 产品资源。