Metadata-Version: 2.4
Name: tdxaidata
Version: 1.0.0
Summary: 通达信 TdxAiData 行情/专业数据 Python 接口（跨平台 Windows/macOS/Linux）
Author: tdx-meiziyao
License-Expression: MIT
Project-URL: Homepage, https://www.tdx.com.cn
Keywords: tdx,通达信,quant,quantitative,行情,A股,股票
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
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: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pandas
Requires-Dist: pandas>=1.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# tdxaidata

通达信 TdxAiData 行情 / 专业数据 Python 数据接口（**跨平台：Windows / macOS / Linux**）。

基于 TdxAiData 原生动态库，用 `ctypes` 直接调用，对齐 `tqcenter` 命名，提供行情、证券基础信息、板块、交易日、专业数据、除权除息、股本、涨跌停、分笔、分时与实时订阅能力。**不依赖** `tqcenter.py`、`TPyth.dll`、策略运行环境或通达信客户端交互。

## 特性

- 跨平台：Windows（`TdxAiData.dll`）/ macOS（`libTdxAiData.dylib`）/ Linux（`libTdxAiData.so`），随包自动匹配
- 与 tqcenter 一致的接口命名：`get_market_data`、`get_market_snapshot`、`get_financial_data`、`subscribe` 等
- K 线与除权除息在装有 pandas 时返回 `DataFrame`
- 可选 `TDX_AI_DATA_LIB` 环境变量指定动态库路径

## 安装

```bash
pip install tdxaidata
```

可选：pandas 支持

```bash
pip install tdxaidata[pandas]
```

## 快速开始

```python
from tdxaidata import tqs

# 实时行情快照
snap = tqs.get_market_snapshot("600000.SH", ["Name", "Price", "Close"])
print(snap)

# K 线（需 pandas）
market = tqs.get_market_data(
    field_list=["Close", "Volume"],
    stock_list=["600000.SH", "000001.SZ"],
    period="1d",
    count=100,
    dividend_type="front",
)
print(market["Close"].tail())

# 订阅实时行情（保持进程运行）
import time

def on_quote(data):
    print("[行情]", data)

tqs.subscribe(stock_list=["000001.SZ", "600000.SH"], callback=on_quote)
time.sleep(30)
tqs.unsubscribe()
```

## 配置（必读）

随包提供 `TdxAiData.ini`（位于包内 `tdxaidata/lib/`），默认指向通达信官方 AI 数据服务（行情 `aihs.tdx.com.cn:7709`、数据 `aids.tdx.com.cn:7727`）。**Token 未预填**，安装后必须按实际环境修改：

- `[TcHqHost]` / `[TcDsHost]`：行情 / 数据服务地址（默认已指向官方域名，一般无需改动）
- `[Token]`：填写 `token=`（**必填**，登录通达信个人版商城 → 会员中心 → 积分和Key管理 → 创建数据服务 Key；缺失或错误会导致连接 / 认证失败）

> 动态库初始化时读取其所在目录（`tdxaidata/lib/`）的 `TdxAiData.ini`。也可以不改模板，通过环境变量 `TDX_AI_DATA_LIB` 指向外部动态库目录。

## 动态库查找顺序

1. 构造 `_NativeTdxAiData(dll_path)` 显式传入的路径
2. 环境变量 `TDX_AI_DATA_LIB`
3. 包内 `tdxaidata/lib/` 下的平台对应动态库（`TdxAiData.dll` / `libTdxAiData.dylib` / `libTdxAiData.so`）
4. 模块同目录（源码部署兼容）

## 接口概览

- 行情与基础信息：`get_market_data` / `get_divid_factors` / `get_stock_info` / `get_market_snapshot` / `get_more_info`
- 证券列表、板块与交易日：`get_stock_list` / `get_sector_list` / `get_stock_list_in_sector` / `get_trading_dates` / `get_zzgz_stocklist`
- 专业数据：`get_financial_data` / `get_financial_data_by_date` / `get_gpjy_value(_by_date)` / `get_bkjy_value(_by_date)` / `get_scjy_value(_by_date)` / `get_gp_one_data`
- 关系 / 可转债 / ETF / 涨跌停 / 股本：`get_relation` / `get_kzz_info` / `get_trackzs_etf_info` / `get_zdt_data` / `get_gb_info(_by_date)` / `get_exday_data`
- 分笔 / 分时：`get_tick_data` / `get_minute_data`
- 订阅：`subscribe` / `unsubscribe` / `get_subscribe_hq_stock_list`
- 文件下载：`download_file`（HTTP，不依赖动态库）

> 完整参数说明与字段参考见包内 `tdxaidata/docs/tqServer使用文档.md`（随 wheel/sdist 分发；源码仓库另附 `SKILL.md`）。

## 错误处理

新版多数错误（库未加载、返回空 / 无效 JSON、`ErrorId != 0`、参数非法等）会**打印 `[错误]` 提示并返回空值**（`None` / `{}` / `[]`），调用后请检查返回值。

## 许可

MIT License
