zer0data SDK 升级指南

本文档说明如何将 zer0data SDK 升级到新版本。

📦 版本检查

查看当前版本

import zer0data
print(f"当前版本: {zer0data.__version__}")

查看已安装的提交

pip show zer0data

输出示例：

Name: zer0data
Version: 0.1.0
Location: /path/to/site-packages

🚀 升级方法

zer0data SDK 通过 Git 仓库安装，升级即为重新安装指定版本。

方式 1：升级到最新主分支

pip（SSH）pip（HTTPS）uv

pip install --force-reinstall \
  "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

pip install --force-reinstall \
  "git+https://github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

uv add --reinstall \
  "git+ssh://git@github.com/zer0coldai/zer0data.git#subdirectory=sdk"

方式 2：升级到指定提交（推荐生产环境）

# 将 <commit-sha> 替换为目标提交的完整或短 SHA
pip install --force-reinstall \
  "git+ssh://git@github.com/zer0coldai/zer0data.git@<commit-sha>#subdirectory=sdk"

锁定提交的好处

锁定到具体提交可确保环境可复现，避免主分支更新引起意外行为变化。

方式 3：在干净虚拟环境中安装

# 创建新虚拟环境
python -m venv .venv_new
source .venv_new/bin/activate   # Linux/Mac
# 或
.venv_new\Scripts\activate       # Windows

# 安装最新版本
pip install "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"

✅ 升级验证

基本验证

import zer0data

# 确认版本
print(f"zer0data 版本: {zer0data.__version__}")

# 确认核心类可正常导入
from zer0data import Client, KlineService, SymbolService
print("核心类导入成功")

# 初始化 Client
client = Client()
print("Client 初始化成功")

功能验证

import zer0data as zd

client = zd.Client()

# 验证合约元数据查询
symbols = client.get_symbols(market="um", quote_asset="USDT")
assert not symbols.empty, "get_symbols 返回空数据"
print(f"合约数: {len(symbols)}")

# 验证 K 线查询（小范围取样）
df = client.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-01-02",
    frequency="1h",
    limit=10,
)
print(f"K 线行数: {len(df)}")
print("验证通过 ✓")

⚠️ 升级注意事项

1. 同步升级 dbmodule：SDK 与 dbmodule 版本需配套，升级 SDK 时建议一同升级：

   pip install --force-reinstall \
     "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=dbmodule"
   pip install --force-reinstall \
     "git+ssh://git@github.com/zer0coldai/zer0data.git@main#subdirectory=sdk"
   

2. 查阅更新日志：升级前请阅读 更新日志，确认是否有破坏性变更（Breaking Changes）

3. 生产环境建议：在测试环境验证通过后再升级生产环境，推荐使用锁定提交的方式

✅ 升级检查清单

• 已备份当前使用的提交 SHA（pip show zer0data）
• 已查阅目标版本的 更新日志
• 已在测试环境执行功能验证
• 已同步升级 dbmodule 到配套版本
• 已记录本次升级使用的仓库地址和提交 SHA

---

查看版本历史： 更新日志 →