Metadata-Version: 2.4
Name: agushuju
Version: 0.2.0
Summary: 爱股数据（agushuju.com）Python SDK — tushare 亲和的 A 股数据接口
Author: agushuju
License: MIT
Keywords: agushuju,tushare,stock,futures,finance,quant
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20
Provides-Extra: dataframe
Requires-Dist: pandas>=1.0; extra == "dataframe"

# agushuju — 爱股数据 Python SDK

tushare 亲和的 A 股数据接口客户端：方法名与 [爱股数据](https://www.agushuju.com) 端点一一对应，
`stock_` 前缀端点可省略前缀调用（`stock_daily` → `pro.daily()`），从 tushare 迁移只改一行 import。

## 安装

```bash
# 源码安装（本仓库）
cd sdk/python && pip install .

# 仅依赖 DataFrame 支持（可选，未装则返回 list[dict]）
pip install .[dataframe]
```

在线运行（`/coderunner`）的环境已在服务端预装本 SDK，可直接 `import agushuju`。

## 快速开始

```python
import agushuju as agu

pro = agu.pro_api('你的APIKey')   # https://www.agushuju.com/userapikey

# 股票日线（端点 stock_daily，tushare 亲和省略 stock_ 前缀）
# tushare 习惯参数开箱即用（SDK 自动翻译 ts_code / start_date / YYYYMMDD）：
df = pro.daily(ts_code='000001.SZ', start_date='20260101', end_date='20260901')
# 平台原生参数完全等价：
df = pro.daily(stock_code='000001.SZ', trade_date_start='2026-01-01', trade_date_end='2026-09-01')

# 指数 / 基金 / 期货（非 stock_ 前缀端点用全名）
df = pro.index_daily(ts_code='000001.SH')          # ts_code 自动按端点路由
df = pro.fund_daily(fund_code='510300.SH')
df = pro.futures_daily(futures_code='RB2601.SHF')

# 交易日历、财务指标
cal = pro.trade_cal(exchange='SSE', cal_date_start='2026-01-01', cal_date_end='2026-12-31')
fina = pro.fina_indicator(stock_code='000001.SZ', end_date_start='2026-06-30', end_date_end='2026-06-30')

# 分页
df = pro.daily(stock_code='000001.SZ', limit=100, offset=200)

# 通用原始调用（任意端点 path 直达，新端点无需 SDK 发版）
rows = pro.query('stock_moneyflow', stock_code='000001.SZ')
```

## 方法名规则

| 端点 path | SDK 方法 |
|---|---|
| `stock_daily` | `pro.daily()`（`stock_` 前缀省略） |
| `stock_trade_cal` | `pro.trade_cal()` |
| `index_daily` / `fund_daily` / `futures_daily` | `pro.index_daily()` 等全名 |
| 任意新端点 | `pro.query('<path>', **params)` |

未识别的方法名会按原样请求，服务端返回错误时抛 `ApiError` 并带上下文。

### tushare 参数兼容（v0.2.0 起）

方法名与参数均亲和：tushare 风格参数在请求前自动翻译为平台参数，**原生参数也完全支持**（两者可混用，显式原生参数优先）：

| tushare 写法 | SDK 自动翻译为 |
|---|---|
| `ts_code='000001.SZ'` | `stock_code`（按端点路由：指数/基金/期货端点分别为 index_code / fund_code / futures_code） |
| `start_date='20260101'` / `end_date='20260901'` | 端点主日期列的「列名_start / 列名_end」（如 `trade_date_start`；财务指标端点映射到报告期 `end_date_start`），日期值 `YYYYMMDD` 自动转 `YYYY-MM-DD` |
| `period='20260630'` | 不翻译（无对应语义），请用 `end_date_start='2026-06-30', end_date_end='2026-06-30'` |

各端点可用参数见[接口文档](https://www.agushuju.com/doc)；schema 之外的参数会被服务端静默忽略（不会报错），翻译映射基于端点 schema 快照（`_PRIMARY_DATE`），新端点默认回退 `trade_date`。

## 客户端配置

```python
pro = agu.pro_api(
    'token',
    base_url='http://127.0.0.1:8181',  # 默认 https://www.agushuju.com，或环境变量 AGUSHUJU_API_BASE
    timeout=60,   # 单次请求超时（秒）
    retry=3,      # 网络错误 / 5xx 重试次数（401/402/429 不重试）
)
```

返回值为 `pandas.DataFrame`（未安装 pandas 时为 `list[dict]`）；`df.attrs['count']` 为满足条件的总记录数（分页统计）。

## 错误处理

- 业务失败（余额不足 402、未认证 401、限流 429、参数错 1）→ `ApiError`，`e.code` 为服务端错误码
- 网络失败 / 5xx → 自动重试后仍失败抛 `ApiError`

```python
from agushuju import ApiError

try:
    df = pro.daily(ts_code='000001.SZ')
except ApiError as e:
    print(e.code, e)
```

## 相关链接

- 接口文档：https://www.agushuju.com/doc
- 定价与限流：https://www.agushuju.com/pricing
- 数据源状态：https://www.agushuju.com/status
- API Key 管理：https://www.agushuju.com/userapikey
