使用 pytdx，`TdxHq_API` 接口下载数据的 AI 编程指引提示词

🧠 目标描述

你需要根据用户需求，编写或修改 Python 代码，使用 pytdx 库中的 TdxHq_API 接口，从通达信服务器获取指定金融品种（如股票、指数）的历史行情数据。重点关注K线数据（包括但不限于日线、60分钟线等），并支持配置化管理连接参数和灵活的时间范围控制。

---

🛠️ 技术要求与编程指引

1. 依赖库导入与初始化

确保导入以下常用库：

import toml
import os
from pytdx.hq import TdxHq_API
import pandas as pd

加载配置文件（推荐格式为 config.toml）：

config_path = os.path.join(os.path.dirname(__file__), 'config.toml')
with open(config_path, 'r') as f:config = toml.load(f)

初始化行情接口并建立连接：

api = TdxHq_API()
api.connect(config['tdx']['api_host'], config['tdx']['api_port'])

记得断开连接：

api.disconnect()

---

2. 函数命名规范与结构建议

函数名应清晰表达获取的数据类型、周期和标的，例如：

• get_hs300_60min_data()
• get_stock_day_data(code)
• get_index_kline(index_code, period='60m', ndays=200)

函数基本结构如下：

def get_index_kline(index_code, period='60m', ndays=200):api = TdxHq_API()api.connect(config['tdx']['api_host'], config['tdx']['api_port'])df = pd.DataFrame()if api:# TODO: 根据period确定categorycategory = 3  # 60分钟线total_bars = ndays * 4  # 每天4根60分钟线batches = (total_bars + 799) // 800for i in range(batches):start = i * 800count = min(800, total_bars - start)data = api.get_security_bars(category, 1, index_code, start, count)batch_df = api.to_df(data)df = pd.concat([df, batch_df])api.disconnect()return df

---

3. 数据请求逻辑与参数说明

使用 api.get_security_bars() 获取 K 线数据：

data = api.get_security_bars(category, market, code, start, count)

• category: 数据周期类型：
  • 0 日线
  • 1 1分钟线
  • 2 5分钟线
  • 3 60分钟线
  • 4 周线
  • 5 月线
• market: 市场代码：
  • 0 深市
  • 1 沪市
• code: 证券代码（字符串形式）
• start, count: 分页参数，每次最多取 800 条记录

---

4. 返回值处理建议

将结果转换为 pandas.DataFrame 并进行清洗：

df = api.to_df(data)# 可选：转换时间戳为 datetime 类型
df['datetime'] = pd.to_datetime(df['datetime'])
df.set_index('datetime', inplace=True)

---

5. 异常处理与健壮性建议

添加异常捕获机制以提升稳定性：

try:api = TdxHq_API()with api.connect(config['tdx']['api_host'], config['tdx']['api_port']):# 数据获取逻辑
except Exception as e:print(f"数据获取失败: {e}")
finally:try:api.disconnect()except:pass

---

✅ 示例调用方式

df = get_index_kline('510300', period='60m', ndays=200)
print(df.head())

---

🧩 扩展功能建议

• 支持多种周期：日线（0）、30分钟（2）、60分钟（3）等
• 支持多只股票/指数并发下载（可结合 concurrent.futures）
• 自动去重、排序、保存为 CSV 或 HDF5 文件
• 提供时间区间筛选功能（如某年某月某日至某日）

---

💬 AI指令建议模板
“请根据上述指引，帮我写一个函数，使用 TdxHq_API 获取创业板指过去 100 天的日线数据。”

---

如果你有特定需求（如获取某只个股的30分钟线、获取多个指数等），请进一步补充细节，我会为你定制更精确的代码模板。