kestrel-data-sdk

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

安装

pip install kestrel-data-sdk

按产品下载

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")

下载账户的全部授权数据

不传 start 和 end，即按后台为每个产品配置的授权日期范围下载：

from getpass import getpass

from kestrel_data_sdk import Kestrel

output = "/data/kestrel"
kd = Kestrel(input("用户名: ").strip(), getpass("密码: "))

failures = []
products = kd.products()
for index, product in enumerate(products, 1):
    product_id = product["productId"]
    print(f"\n[{index}/{len(products)}] {product.get('name') or product_id} ({product_id})")
    try:
        kd.download(product_id, output)
    except Exception as error:
        failures.append((product_id, str(error)))
        print(f"[失败] {product_id}: {error}")

print(f"\n全部任务结束，失败产品: {len(failures)}")
for product_id, error in failures:
    print(f"- {product_id}: {error}")

脚本可反复执行；已完成文件会使用本地缓存，未完成文件会断点续传。

授权范围内没有下载次数配额。特定 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 账户受产品授权、数据范围和授权有效期约束； 开启“全部数据权限”的账户不受这些约束。