Metadata-Version: 2.1
Name: kestrel-data-sdk
Version: 0.3.2
Summary: Kestrel Data on-demand download SDK
Author: Kestrel Data
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# kestrel-data-sdk

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

```python
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 小时同步计划；只有需要更新的分区才逐个获取文件清单，
避免在首次下载前等待整批历史文件扫描。
需要主动重新下载时使用：

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

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

缓存查询和校验：

```python
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 账户受产品授权、数据范围和授权有效期约束；
开启“全部数据权限”的账户不受这些约束。
