Metadata-Version: 2.4
Name: tdxquant
Version: 0.2.0
Summary: 通达信量化(TdxQuant) HTTP SDK —— 统一返回 DataFrame，字段金融规范化(snake_case)
Requires-Python: >=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: orjson>=3.11.9
Requires-Dist: pandas>=2.0
Description-Content-Type: text/markdown

# tdxquant

[![PyPI version](https://img.shields.io/pypi/v/tdxquant.svg)](https://pypi.org/project/tdxquant/) [![Python](https://img.shields.io/pypi/pyversions/tdxquant.svg)](https://pypi.org/project/tdxquant/)

通达信量化（TdxQuant）**HTTP SDK** —— 直接调用通达信客户端官方 HTTP 接口（`POST http://127.0.0.1:17709/`），统一返回 `pandas.DataFrame`，字段重命名为金融行业规范的 **snake_case**。

> **命名**：PyPI 包名 `tdxquant`（`pip install tdxquant`），import 名 `tdxquant`（`from tdxquant import TdxAPI`）。

## 工作方式

通达信量化客户端原生提供 HTTP 调用方式（无需 tqcenter / DLL / 自建网关）：

```
你的代码(SDK) ──HTTP/JSON──► 通达信客户端(127.0.0.1:17709)
```

1. 启动支持 TQ 的通达信客户端（它会监听 `127.0.0.1:17709`）
2. SDK 直接 POST 调用，字段重命名 + DataFrame 封装在 SDK 内完成

> 请求格式：`{"id":1, "method":"<tqcenter方法名>", "params":{...}}`，`method` 为 tqcenter 函数名，`params` 为底层参数名。

## 安装

```bash
pip install tdxquant      # 从 PyPI（import 名为 tdxquant）
# 或 uv add tdxquant
```

> **本地开发**（克隆源码后）：`uv sync` 或 `pip install -e .`。
> 需要 Python ≥ 3.13、通达信金融终端（量化模拟版 / 专业研究版等支持 TQ 策略的版本）。

## 快速开始

```python
from tdxquant import TdxAPI

api = TdxAPI()   # 默认 http://127.0.0.1:17709，需通达信客户端在线

# K线（OHLCV 长表）
df = api.get_kline("000001.SZ", freq="daily", adjust="qfq", start_date="20260101")
# 实时快照
snap = api.get_snapshot("000001.SZ")
# 股票 / 板块 / ETF
api.get_stock_list()                   # 所有分类合并(带 market/category 列)
api.get_sector_list()
api.get_track_etf("000300.SH")
# 财务
api.get_financial("600519.SH", fields=["Fn193","Fn194"], start_date="20240101")
# 交易日历
api.get_trading_calendar("20260101", "20260613")
```

从别的机器调用：`TdxAPI(base_url="http://通达信机器IP:17709")`。

## 接口总览

| 类别 | 方法 | 说明 |
|---|---|---|
| 行情 | `get_kline` | K线（OHLCV 长表） |
| | `get_snapshot` | 实时快照（五档） |
| | `get_instrument_info` / `get_more_info` | 基本信息 |
| | `get_dividend_factors` | 分红送配 |
| 财务 | `get_financial` / `get_financial_by_date` | 专业财务（FNxxx） |
| | `get_stock_trade_data(_by_date)` | 股票交易（GPx） |
| | `get_sector_trade_data(_by_date)` | 板块交易（BKx） |
| | `get_market_trade_data(_by_date)` | 市场交易（SCx） |
| | `get_stock_single_data` | 单点数据（GOx） |
| | `get_share_capital(_by_date)` | 股本数据 |
| 板块 | `get_stock_list` | 分类成分股（market 不传返回全部，带 market/category 列） |
| | `get_sector_list` / `get_user_sectors` | 板块列表 |
| | `get_sector_stocks` | 板块成分股 |
| 证券 | `get_convertible_bond` | 可转债 |
| | `get_ipo_info` | 新股/新债申购 |
| | `get_track_etf` | 跟踪指数的 ETF |
| 日历 | `get_trading_dates` / `get_trading_calendar` | 交易日 |

> 交易类（`order_stock`）按需求不做。完整参数与字段说明见 [`docs/api_reference.md`](docs/api_reference.md)。

## 字段命名规范

- 全部 **snake_case 小写**，采用金融行业惯例（OHLCV / bid-ask / nav / pct_chg）。
- 原字段 → 新字段完整血缘见 [`docs/field_lineage.md`](docs/field_lineage.md)。
- 通达信专业编码字段（`FNxxx`/`GPx` 等）保留转小写，需对照通达信字段手册。

代码格式：`000001.SZ` / `600519.SH`（6 位 + 市场后缀）；频率 `daily/5min/...`；
复权 `none/qfq/hfq`；日期严格 `YYYYMMDD`（区间用 `start_date`/`end_date`，按日期点用 `date`）。

## 测试

```bash
uv run pytest                     # 单元测试（字段血缘契约 + 拼装逻辑）
uv run pytest --runintegration    # 集成测试（需通达信客户端在线）
```

## 项目结构

```
tdxquant/
├── client.py          # HTTP 客户端（POST 17709）+ DataFrame 拼装
├── schema.py          # 字段血缘映射表（唯一真实来源）
├── enums.py           # Freq / Adjust 枚举 + validate_date 日期校验
├── exceptions.py      # 异常
└── api/               # 各业务接口（mixin）
    ├── market.py  financial.py  sector.py  instrument.py  calendar.py
```

## 常见问题

- **`server return none` / 连接失败**：确认通达信客户端已启动并登录行情；SDK 默认连 `127.0.0.1:17709`。
- **`502 Bad Gateway`**：本机代理（Clash/V2Ray）劫持 localhost 请求。SDK 已默认 `trust_env=False` 直连，若仍异常请关闭代理。
- **财务/专业数据为空**：需先在通达信客户端下载对应盘后/专业财务数据。
- **`get_financial` 报 end_time 缺失**：底层要求结束日期，`end_date` 留空时 SDK 自动取当天。
