Metadata-Version: 2.4
Name: datapush-sdk
Version: 0.1.0
Summary: datapush A 股行情 SDK：实时推送 + 历史 K 线 + 复权因子 + 本地按需缓存（CLI 与 Python 两种用法）
Author-email: datapush <support@datapush.vip>
License: MIT
Project-URL: Homepage, https://api.datapush.vip
Project-URL: Documentation, https://api.datapush.vip/dp/docs
Project-URL: Source, https://api.datapush.vip
Project-URL: Bug Tracker, https://api.datapush.vip
Keywords: datapush,a-share,stock,market-data,kline,quote,websocket,quant,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: pandas
Requires-Dist: pandas>=1.3; extra == "pandas"
Dynamic: license-file

# datapush-sdk

**datapush A 股行情 SDK**（Python）：REST 历史 + WebSocket 实时 + **本地按需缓存**。
**零第三方依赖**（只用标准库），`pip install` 后即可用 **命令行** 与 **Python 两种方式**使用，前缀都是 `datapush`。

```bash
pip install datapush-sdk
datapush config set-key sk-xxx     # 保存 API Key（也可用环境变量 DATAPUSH_API_KEY）
datapush kline 000001              # 一行拿到最近 30 个交易日日K（自动缓存）
```

```python
import datapush
c = datapush.Client()              # Key 自动读；缓存默认开启
page = c.kline("000001", days=250)  # 一行拿数据；第二次调用命中缓存
for bar in page:
    print(bar.time, bar.close)
```

---

## 1. 安装与配置

```bash
pip install datapush-sdk            # 运行时零依赖
pip install "datapush-sdk[pandas]"  # 可选：需要 to_pandas()
```

API Key 的解析优先级（高 → 低）：**显式参数 → 环境变量 `DATAPUSH_API_KEY` → `~/.datapush/config.json`**。
推荐用 CLI 保存一次即可：`datapush config set-key sk-xxx`（也可 `datapush config show` 查看，Key 会打码）。

服务地址默认 `https://api.datapush.vip`，可用 `--base-url` / `DATAPUSH_BASE_URL` / 配置文件覆盖。

## 2. 本地按需缓存（默认开启，用户无感）

- **只存不复权原始价**（`adj=none`）+ 复权因子表 ⇒ 历史永不失效、只需追加；
- **复权在本地算**：`kind="qfq"|"hfq"|"raw"`，除权后自动正确、**无需重下历史**；
- **增量续拉**：用游标 `latest_time` 只拉新增（当日 forming bar 同键覆盖写，天然幂等）；
- **范围自动补拉**：这次要 30 天、下次要 250 天，会自动把缺的那段补上；
- **断网可读**：`Client(offline=True)` 或 `--offline` 只读本地缓存；
- 缓存位置：`~/.datapush/cache/datapush.db`（SQLite 单文件）；可用 `--cache-dir` / `DATAPUSH_CACHE_DIR`
  / 配置文件 `cache_dir` 指定；`DATAPUSH_NO_CACHE=1` 或 `--no-cache` 彻底关闭。

```bash
datapush cache info                 # 路径 / 大小 / 标的数 / 根数 / 时间范围
datapush cache path                 # 只打印缓存文件路径（脚本友好）
datapush cache prune --days 90      # 只保留最近 90 天
datapush cache clear --code 000001  # 清掉某只票
datapush update 000001 --period 1m  # 手动增量（平时查询时自动做）
```

**股票列表 / 基础信息 / 交易日 / 板块** 属于实时数据，**直连不缓存**（流量很小）：
`datapush codes`（全市场代码，约 6 页 / 约 1MB）、`datapush stock 000001`。

## 3. Python 用法速查

```python
import datapush
c = datapush.Client()                       # 也可 Client(api_key=..., cache=False, offline=True)

# 历史
c.codes()                                   # 全市场代码（实时）
c.stocks(all=True)                          # 全市场列表（实时）；c.stocks(page=1, page_size=20) 单页
c.stock("000001")                           # 基础信息 12 字段（实时）
c.kline("000001", days=250)                 # 日K（前复权）
c.kline("000001", days=250, kind="hfq")     # 后复权（本地因子表算）
c.kline("000001", start="2026-01-01", end="2026-09-26", kind="raw")
c.minute("000001", days=1)                  # 1 分钟 K 线（当日）
c.fiveminute("000001", days=5)              # 5 分钟 K 线
c.kline("000001", since="2026-09-26 14:59") # 增量（闭区间，含该根）
c.xdxr("000001")                            # 复权因子表（TTL 1 天，除权后自动刷新）
c.factors("000001", size=30, fields="close,ma5")   # 量化因子（高级用户）
c.factor_catalog()                          # 因子目录

# 实时（WebSocket）
q = c.quote("000001")                       # 一次快照（WS 首帧；REST 没有该接口）
for e in c.watch(["000001", "600108"], types=["quote", "k1"], seconds=30):
    if e.type == "quote":
        print(e.quote.price)

# 导出与缓存
c.kline("000001", days=250).to_csv("000001.csv")
c.kline("000001", days=250).to_dicts()      # list[dict]
c.to_pandas(c.kline("000001", days=250))    # 需要 pandas
c.cache_info(); c.update("000001", period="day"); c.close()
```

## 4. CLI 速查

```bash
datapush kline 000001 [--days 250 | --size 100 --offset 0 | --start 2026-01-01 --end 2026-09-26 | --since "..."]
                     [--period day|1m|5m] [--kind qfq|hfq|raw] [--limit 60] [--csv out.csv] [--json] [--no-refresh]
datapush minute 000001 --days 1
datapush fiveminute 000001 --days 5
datapush xdxr 000001 [--refresh]
datapush stocks [--page 1 --page-size 20] [--all]
datapush codes [--market sh|sz|bj] [--prefixed]        # 默认一行一个，可直接管道
datapush stock 000001
datapush factors 000001 --size 30 [--fields close,ma5] [--daily-kline 0]
datapush quote 000001 [--types quote|depth]
datapush watch 000001 600108 [--types quote,k1] [--seconds 30]
datapush update 000001 --period 1m
datapush cache info|path|clear|prune
datapush config set-key sk-xxx | config show | config path | config set cache_dir D:/datapush-cache
datapush doctor                                        # 一键排障
datapush get /api/v1/stocks/000001/xdxr --param k=v     # 通用逃生舱（调试新接口）
```

通用选项可写在命令前或命令后：`--json`（原始 JSON，便于管道）、`--csv FILE`、`--api-key`、`--base-url`、
`--timeout`、`--cache-dir`、`--no-cache`、`--offline`。
退出码：`0` 成功 / `1` 业务或网络错误 / `2` 参数错误。

## 5. 本地复权（与官方文档公式一致）

`adj=none` 取原始价 + `xdxr()` 取因子表 ⇒ **一次乘法**：

```
段 = segments 里第一个 from ≤ bar.date（都不满足 ⇒ from 为空的兜底段）
前复权价 = raw价 × seg.qfq      后复权价 = raw价 × seg.hfq
换手率   = cjl / ltgb × seg.share_ratio × 100        自检：seg.hfq × P == seg.qfq（P = 兜底段 qfq）
```

SDK 已内置：`datapush.adjust_bars(bars, table, kind=...)`、`datapush.pick_segment(table, date)`、
`datapush.verify_segments(table)`。细节见官方文档「复权因子表（本地复权计算）」。

## 6. 常见问题

- **`import datapush` 不是我装的这个包？** PyPI 上另有一个无关的 `datapush`（MySQL 数据生成器）。
  两者同装会互相覆盖顶层模块，此时用别名：`import datapush_sdk as datapush`。
- **需要 Key 但没有？** 先 `datapush config set-key sk-xxx`（注册后在控制台复制）；`datapush doctor` 可自查。
- **返回 402 / 429？** 402 = 积分不足；429 = 分钟接口限流（10 QPS/用户，SDK 已按 `Retry-After` 自动退避重试）。
- **能离线用吗？** 能：缓存过的标的用 `offline=True`/`--offline` 可读；实时接口必须联网。
- **WS 单连接能订阅多少？** 最多 50 个 code（SDK 会自动分批订阅）；普通用户最多 10 个连接。

## 7. 兼容性与许可

- Python **3.9+**（Windows / macOS / Linux），运行时**零第三方依赖**；`py.typed` 已附带，支持类型检查。
- License: **MIT**。接口与字段含义以官方文档为准（`https://api.datapush.vip/dp/docs`）。
