Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.2.4
Summary: AlphaKit — 简洁的金融数据 API 工具包
Author: AlphaKit Team
License: MIT
Project-URL: Homepage, https://github.com/yourusername/alphakit
Keywords: finance,data,api,quant,alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.3.0

# AlphaKit SDK

简洁的 A 股市场数据 API 工具包。

## 安装

```bash
pip install alphakit-sdk
```

## 快速开始

```python
import alphakit as ak

ak.set_token('your_token_here')
api = ak.AlphaKit()

# 默认获取最近一年日线
df = api.daily(ts_code='000001.SZ')
print(df)
```

> Token 与服务接入信息请联系服务提供方获取。

## 客户端初始化

```python
import alphakit as ak

# 全局 token
ak.set_token('your_token_here')
api = ak.AlphaKit()

# 实例化时传入
api = ak.AlphaKit(token='your_token_here')

# 自定义服务地址
api = ak.AlphaKit(token='your_token_here', base_url='https://your-domain.com')
```

## API 接口

### 股票

```python
# 股票列表
api.stock_basic()
api.stock_basic(ts_code='000001.SZ')

# 日线行情（只传 ts_code 默认取最近一年）
api.daily(ts_code='000001.SZ')
api.daily(ts_code='000001.SZ', start_date='20260601', end_date='20260618')
api.daily(trade_date='20260618')  # 全市场

# 每日基础指标（PE/PB/PS/总市值/换手率）
api.daily_basic(ts_code='000001.SZ', start_date='20260601', end_date='20260618')

# 复权因子
api.adj_factor(ts_code='000001.SZ', start_date='20260601', end_date='20260618')

# 股票技术因子（35 个常用指标：均线/KDJ/RSI/MACD/BOLL/CCI/BIAS 等）
api.stk_factor(ts_code='000001.SZ', start_date='20260601', end_date='20260618')
api.stk_factor(trade_date='20260618')  # 全市场
```

### 资金流向

```python
api.moneyflow(ts_code='000001.SZ', trade_date='20260618')
api.moneyflow_dc(ts_code='000001.SZ', trade_date='20260618')
```

### 两融

```python
api.margin(trade_date='20260618')
api.margin_detail(ts_code='000001.SZ', start_date='20260601', end_date='20260618')
```

### 市场行为

```python
# 停复牌
api.suspend_d(ts_code='000001.SZ', start_date='20260601', end_date='20260618')
api.suspend_d(suspend_type='S', trade_date='20260601')   # 停牌
api.suspend_d(suspend_type='R', trade_date='20260601')   # 复牌

# 涨跌停 / 龙虎榜 / 开盘啦
api.limit_list_d(trade_date='20260618')
api.top_list(trade_date='20260618')
api.kpl_list(trade_date='20260618')
```

### 指数 / 行业

```python
api.index_daily(ts_code='000300.SH', start_date='20260601', end_date='20260618')
api.index_dailybasic(ts_code='000001.SH', trade_date='20260618')
api.sw_daily(trade_date='20260618')
```

### ETF / 期权

```python
api.etf_basic()
api.etf_daily(ts_code='510300.SH', start_date='20260601', end_date='20260618')
api.etf_nav(ts_code='510300.SH', start_date='20260601', end_date='20260618')
api.etf_share(ts_code='510300.SH', trade_date='20260618')

api.opt_basic(exchange='SSE')
api.opt_daily(ts_code='10004355.SH', trade_date='20260618')
```

### 通用查询

```python
# 任意 tushare 兼容接口（按需）
api.query('trade_cal', exchange='SSE', start_date='20260101', end_date='20261231')
api.query('income', ts_code='000001.SZ', period='20251231')
api.query('balancesheet', ts_code='000001.SZ', period='20251231')
api.query('cashflow', ts_code='000001.SZ', period='20251231')
api.query('fina_indicator', ts_code='000001.SZ', period='20251231')
api.query('weekly', ts_code='000001.SZ', start_date='20260101', end_date='20260618')
api.query('monthly', ts_code='000001.SZ', start_date='20260101', end_date='20260618')
api.query('repurchase', ts_code='000001.SZ', start_date='20260101', end_date='20260618')
api.query('stk_surv', ts_code='000001.SZ', start_date='20260101', end_date='20260618')
```

## 错误处理

```python
from alphakit.exceptions import AlphaKitError

try:
    df = api.daily(ts_code='000001.SZ')
except AlphaKitError as e:
    print(f"[{e.code}] {e.message}")
```

| 错误码 | 含义 | 处理 |
|---|---|---|
| 1001 | Token 无效/过期 | 检查 token |
| 1002 | 等级无权访问 | 升级等级 |
| 1003 | IP 限制 | 检查 IP 绑定 |
| 1004 | 触发限频 | 降低请求频率 |
| 1005 | 当日配额用尽 | 等次日或提升配额 |
| 1006 | 参数错误 | 检查参数 |
| 1500 | 服务器错误 | 稍后重试 |
| 9999 | 网络失败 | 检查网络 |

## 最佳实践

### Token 安全

```python
import os
import alphakit as ak

ak.set_token(os.environ['ALPHAKIT_TOKEN'])
```

### 智能默认

```python
# 推荐：只传 ts_code 自动取最近一年
df = api.daily(ts_code='000001.SZ')
```

### 批量优先

```python
# 推荐：一次拿整段
df = api.daily(ts_code='000001.SZ', start_date='20260101', end_date='20260618')

# 不推荐：逐日查询
for d in date_list:
    api.daily(ts_code='000001.SZ', trade_date=d)
```

### 异常重试

```python
import time
from alphakit.exceptions import AlphaKitError

def safe_query(func, *args, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except AlphaKitError as e:
            # 限频/服务器错误才重试
            if e.code in (1004, 1500, 9999) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise
```

## 数据范围

- 日线行情、估值指标、资金流向、技术因子、复权因子、龙虎榜、涨跌停、两融：自 2020-01-02 起
- 指数日线、ETF 日线/净值/份额、期权日线、申万行业日线：每个交易日更新
- 财务数据（利润表/资产负债表/现金流量表/财务指标）：按报告期更新
- 数据每个交易日 18:00 自动更新

## 版本历史

- **v0.2.3** — 新增 `stk_factor` / `adj_factor` / `margin` / `margin_detail` / `index_daily` / `index_dailybasic` / `sw_daily` 便捷方法
- **v0.2.2** — `suspend_d` 新增 `suspend_type` 参数；修正字段映射
- **v0.2.1** — `daily()` 智能默认（只传 ts_code 取最近一年）
- **v0.2.0** — 支持 ETF / 期权数据
- **v0.1.0** — 初始版本

## 许可证

MIT
