kestrel-data-sdk

Kestrel Data 按需数据下载 SDK。适用于已获授权的 API 账户，无 Web UI、无常驻服务、 无自动下发，支持 Linux、macOS 和 Windows 的 Python 3.10+。

from kestrel_data_sdk import Kestrel

kd = Kestrel("api-user", "password")
print(kd.products())
kd.download("ods.wind.ashareeodprices", "/data/kestrel", start="202601", end="202608")

授权范围内没有下载次数配额。特定 API 账户还可由管理员开启“全部数据权限”。默认在输出 目录的 .kestrel/sdk-cache.sqlite3 记录已完成的发布版本。每次同步只把本地版本号集合提交给 服务端，由服务端立即返回不可变的 24 小时同步计划；只有需要更新的分区才逐个获取文件清单， 避免在首次下载前等待整批历史文件扫描。 需要主动重新下载时使用：

kd.download("ods.wind.ashareeodprices", "/data/kestrel", start="202608", end="202608", force=True)

下载默认在终端显示文件进度、已下载/总大小、速度和 ETA。非交互脚本可使用 progress=False 关闭。网络中断时会保留 .kestrel.part 临时文件并自动断点续传，默认最多尝试 5 次。

缓存查询和校验：

print(kd.cache_info("/data/kestrel"))

# 显式检查存在性、大小和修改时间；失效索引会被清除，下次下载自动补齐
print(kd.check_cache("/data/kestrel"))

# 精确检查会读取全部已缓存文件并重算 SHA-256
print(kd.check_cache("/data/kestrel", deep=True))

check_cache(..., repair=True) 只修复缓存索引，不会删除本地文件。特殊脚本可以使用 Kestrel(..., cache=False) 禁用持久缓存。

账户必须由管理员设为 API 工具。普通 API 账户受产品授权、数据范围和授权有效期约束； 开启“全部数据权限”的账户不受这些约束。