Metadata-Version: 2.1
Name: kestrel-data-sdk
Version: 0.3.3
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+。

## 安装

```bash
pip install kestrel-data-sdk
```

## 按产品下载

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

## 下载账户的全部授权数据

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

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

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