Metadata-Version: 2.5
Name: meridian-kit-sdk
Version: 0.1.0
Summary: Meridian Kit SDK for the Meridian Data API
Project-URL: Homepage, https://www.ultrastiching.com
Author: Meridian
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: requests<3,>=2.31
Requires-Dist: urllib3<2,>=1.26.20; python_version < '3.10'
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == 'test'
Description-Content-Type: text/markdown

# Meridian Kit SDK for Python

Meridian Kit SDK 用于通过 Python 调用 Meridian Data API。SDK 使用 AK/SK 自动
完成请求签名，并提供业务函数和通用 HTTP 请求两种调用方式。

## 使用要求

- Python 3.9 或更高版本（推荐使用仍处于安全维护期的 Python 3.11 或更高版本）；
- 可访问 Meridian Data API 的网络环境；
- Meridian 提供的 API 地址、Access Key（AK）和 Secret Key（SK）。

SDK 依赖 `requests>=2.31,<3`。正常安装时，`pip` 会自动处理依赖；如果安装环境
不能访问 Python 包索引，需要由环境管理员预先准备依赖包。

Python 3.9 使用兼容旧版 macOS LibreSSL 的 `urllib3>=1.26.20,<2`；Python 3.10
及以上使用 Requests 正常解析出的 urllib3 2.x。urllib3 1.26 分支已停止常规维护，
因此新部署仍推荐使用 Python 3.11 或更高版本。

## 安装

### 首次安装

从 PyPI 安装：

```bash
python -m pip install meridian-kit-sdk
```

Windows PowerShell：

```powershell
py -3 -m pip install meridian-kit-sdk
```

安装后可检查 SDK 版本：

```bash
python -c "import meridian_kit_sdk; print(meridian_kit_sdk.__version__)"
```

该命令会输出当前安装的 SDK 版本号。

## 配置并运行 Demo

如果使用仓库中的 `demo.py`，将以下三个占位值替换为 Meridian 提供的实际配置：

```python
base_url = "https://api.ultrastiching.com"
access_key = "replace-with-your-access-key"
secret_key = "replace-with-your-secret-key"
```

`base_url` 必须是 Meridian 提供的纯 HTTP(S) API 地址。当前生产 API 地址为
`https://api.ultrastiching.com`，不能误用 `https://www.ultrastiching.com`，也不能附带
`/api/wd`、Query 参数或 `#fragment`。

配置完成后执行：

```bash
python demo.py
```

Demo 调用 `get_s_majorbiz()`，成功时会输出服务端返回的 JSON 数据。示例中的股票
代码和日期可根据实际查询需求修改。

## 调用业务函数

SDK 业务函数通过 `MeridianClient` 调用。AK/SK 签名、时间戳和 Nonce 均由 SDK
自动生成：

```python
from meridian_kit_sdk import MeridianClient

base_url = "https://api.ultrastiching.com"
access_key = "replace-with-your-access-key"
secret_key = "replace-with-your-secret-key"

with MeridianClient(
    base_url=base_url,
    access_key=access_key,
    secret_key=secret_key,
) as client:
    result = client.get_s_majorbiz(
        code=["600745", "603986"],
        trade_date=["20240705", "20240704"],
    )
    print(result)
```

业务函数返回服务端响应解码后的 JSON 对象。SDK 不自动转换为
`pandas.DataFrame`。

完整业务函数、调用签名、HTTP 路径、参数和返回值说明见仓库中的
`API_LIST.md`。该文件可直接使用编辑器全文搜索函数名或业务说明。安装后也可以在
Python 中查看单个函数说明，例如：

```python
help(MeridianClient.get_s_majorbiz)
```

## 通过 API 路径调用

当需要直接调用 API 路径时，可以使用 `request()`：

```python
with MeridianClient(
    base_url=base_url,
    access_key=access_key,
    secret_key=secret_key,
) as client:
    response = client.request(
        "POST",
        "/api/wd/get_s_majorbiz",
        json={
            "code": {"symbols": ["600745", "603986"]},
            "trade_date": {"dates": ["20240705", "20240704"]},
        },
    )
    result = response.json()
```

`request()` 返回 `requests.Response`。请求路径必须以单个 `/` 开头，不能传入完整
URL。请求体最大为 1 MiB。

## 错误处理

```python
from meridian_kit_sdk import (
    MeridianApiError,
    MeridianResponseError,
    MeridianTransportError,
)

try:
    result = client.get_s_majorbiz(
        code=["600745"],
        trade_date=["20240705"],
    )
except MeridianApiError as error:
    # 服务端返回非 2xx。
    print(error.status_code, error.error_code, error.message, error.request_id)
except MeridianTransportError as error:
    # DNS、连接、TLS 或响应读取失败。
    print(error)
except MeridianResponseError as error:
    # 服务端返回 2xx，但响应不是合法 JSON。
    print(error.request_id)
```

SDK 默认不自动重试。网络中断时不能仅根据客户端错误判断服务端是否已经完成调用；
是否重试应结合具体业务和计费规则决定。

## 常见问题

### 提示 `No module named 'meridian_kit_sdk'`

确认安装 SDK 和运行程序使用的是同一个 Python 解释器，并重新执行安装命令。

### 返回 401 或签名校验失败

检查 AK、SK 是否完整，客户端系统时间是否准确，以及 `base_url` 是否为 Meridian
提供的地址。不要手工添加或覆盖 `X-Meridian-*` 鉴权请求头。

### 返回 405，且 `code` 和 `request_id` 都为空

这通常表示请求没有进入 Meridian Data API 网关，而是发到了网站入口。确认
`base_url` 使用 `https://api.ultrastiching.com`，不要使用
`https://www.ultrastiching.com`。SDK 会自动拼接 `/api/wd/...`，不要把该路径加到
`base_url` 中。

### 网络连接失败

检查域名解析、代理、防火墙、TLS 证书和目标 API 地址。若所在环境必须使用代理，
请先按所在组织的网络规范配置 Python/Requests 代理。

### 出现 `NotOpenSSLWarning`

该警告通常表示旧版 macOS Python 使用 LibreSSL，同时环境中残留了 urllib3 2.x。
请重新安装当前 SDK，让 `pip` 按 Python 3.9 的依赖约束安装兼容版本：

```bash
python -m pip install --upgrade --force-reinstall meridian-kit-sdk
```

### 接口返回不可用

确认当前凭证是否有权调用目标接口，以及接口是否已对当前账号发布。如需定位，向
Meridian 支持人员提供异常中的 `request_id`，不要提供 Secret Key。

## 升级与卸载

### 升级到新版本

使用 `--upgrade` 安装最新版本：

```bash
python -m pip install --upgrade meridian-kit-sdk
```

### 重新安装同一版本

如果需要重新安装当前版本，使用 `--force-reinstall` 保证替换本地已经安装的内容：

```bash
python -m pip install --force-reinstall meridian-kit-sdk
```

正常发布时，每次修改交付包内容都应提升版本号，并使用 `--upgrade` 安装新版本；
不应长期通过同一版本号反复交付不同内容。

### 卸载

卸载 SDK：

```bash
python -m pip uninstall meridian-kit-sdk
```

## 凭证安全

- 不要将真实 SK 提交到 Git、粘贴到工单或发送到群聊；
- 不要在日志、异常消息或截图中输出完整 AK/SK；
- 不要把 SK 放入 URL、Query 参数或自定义请求头；
- 如果凭证疑似泄露，应立即联系 Meridian 管理员撤销并重新生成。
