MOOTDX：通达信数据接口实用指南

一、核心功能解析

1.1 数据获取模块

MOOTDX提供三大核心数据模块，覆盖从实时行情到财务数据的全链条数据需求，模块间通过统一接口设计实现无缝协作。

1.1.1 实时行情模块（quotes）

核心价值：提供沪深市场实时行情数据，支持分钟线、分笔成交等高频数据获取，延迟低至毫秒级。

适用场景：实时盯盘系统、高频交易策略回测、盘中数据分析。

代码示例：

from mootdx.quotes import Quotes

# 初始化行情接口（自动选择最优服务器）
client = Quotes.factory(market='std', bestip=True, timeout=15)

# 获取单只股票实时行情
quote = client.quotes(symbol='600036')  # 招商银行
print(quote[['code', 'open', 'close', 'high', 'low', 'volume']])
# 输出示例：
#     code   open  close   high    low   volume
# 0  600036  32.50  32.85  33.00  32.45  2568900

# 获取多只股票K线数据（日线，最近30天）
klines = client.bars(symbol='600036', frequency=9, start=0, offset=30)
print(klines[['datetime', 'open', 'close', 'volume']].tail())

💡 性能优化：使用bestip=True会自动检测响应最快的服务器节点，建议首次运行时开启；生产环境可固定优质服务器IP提升稳定性。

1.1.2 本地数据读取模块（reader）

核心价值：解析通达信本地数据文件，支持日线、分钟线等历史数据快速读取，无需网络连接。

适用场景：离线数据分析、历史回测、本地策略研究。

代码示例：

from mootdx.reader import Reader

# 初始化本地数据 reader（需指定通达信安装目录）
reader = Reader.factory(market='std', tdxdir='C:/new_tdx')

# 读取日线数据
daily_data = reader.daily(symbol='600036')
print(f"读取到 {len(daily_data)} 条日线数据")

# 读取5分钟线数据
min5_data = reader.minute(symbol='600036', suffix=5)
print(f"5分钟线数据样例:\n{min5_data[['datetime', 'open', 'close']].head()}")

💡 路径技巧：通达信默认安装路径为C:/new_tdx，若自定义安装需通过tdxdir参数指定；数据文件位于vipdoc/[market]/[type]目录下。

1.1.3 财务数据模块（affair）

核心价值：获取上市公司财务报告数据，支持资产负债表、利润表等标准化财务指标解析。

适用场景：基本面分析、财务因子选股、价值投资研究。

代码示例：

from mootdx.affair import Affair

# 获取财务文件列表
files = Affair.files()
print(f"可用财务文件: {[file['filename'] for file in files[:3]]}")

# 下载并解析最新财务数据
financial_data = Affair.parse(downdir='./financial', filename='gpcw20230930.zip')
print(f"财务数据包含表: {financial_data.keys()}")

# 查看资产负债表样例
balance_sheet = financial_data['balance_sheet']
print(f"资产负债表字段: {balance_sheet.columns.tolist()[:5]}")

1.2 辅助工具模块

1.2.1 数据调整工具（adjust）

提供除权除息数据调整功能，支持前复权、后复权两种常用调整方式：

from mootdx.utils.adjust import to_adjust

# 对K线数据进行前复权处理
adjusted_klines = to_adjust(klines, symbol='600036', adjust='qfq')

1.2.2 服务器检测工具（server）

内置服务器性能检测功能，可帮助选择最优数据源：

from mootdx.server import bestip

# 检测并输出最优服务器
best_ip = bestip(console=True, limit=5)

二、快速上手指南

2.1 环境准备

📌 虚拟环境配置（推荐）：

# 创建虚拟环境
python -m venv mootdx-venv
source mootdx-venv/bin/activate  # Linux/Mac
# 或在Windows上执行: mootdx-venv\Scripts\activate

# 安装依赖
pip install -U pip setuptools wheel

📌 项目安装：

# 方式1: 直接安装最新版
pip install -U git+https://gitcode.com/GitHub_Trending/mo/mootdx.git

# 方式2: 源码安装（开发模式）
git clone https://gitcode.com/GitHub_Trending/mo/mootdx.git
cd mootdx
pip install -e .[dev]  # 包含开发依赖

2.2 基础功能演示

2.2.1 数据流转示例

以下示例展示从获取原始数据到指标计算的完整流程：

from mootdx.quotes import Quotes
from mootdx.utils.adjust import to_adjust
import pandas as pd

# 1. 获取原始K线数据
client = Quotes.factory(bestip=True)
klines = client.bars(symbol='600036', frequency=9, offset=120)  # 120天日线

# 2. 数据清洗与复权
klines = klines.dropna()
adjusted_klines = to_adjust(klines, symbol='600036', adjust='qfq')

# 3. 技术指标计算（简单移动平均线）
adjusted_klines['ma5'] = adjusted_klines['close'].rolling(window=5).mean()
adjusted_klines['ma20'] = adjusted_klines['close'].rolling(window=20).mean()

# 4. 信号生成（金叉/死叉）
adjusted_klines['signal'] = 0
adjusted_klines.loc[adjusted_klines['ma5'] > adjusted_klines['ma20'], 'signal'] = 1
adjusted_klines.loc[adjusted_klines['ma5'] < adjusted_klines['ma20'], 'signal'] = -1

# 查看最近10个交易日信号
print(adjusted_klines[['datetime', 'close', 'ma5', 'ma20', 'signal']].tail(10))

2.2.2 命令行工具使用

MOOTDX提供便捷的命令行工具，支持快速数据导出：

📌 导出股票列表：

mootdx cli stocks -o ./stocks.csv

📌 批量导出K线数据：

mootdx cli quotes -s 600036,000001 -f 9 -o ./klines/

三、高级配置策略

3.1 参数优先级说明

MOOTDX配置参数遵循以下优先级规则（从高到低）：

优先级	配置方式	适用场景
1	实例化时参数	临时覆盖默认配置
2	环境变量	系统级临时配置
3	配置文件	持久化全局配置
4	内置默认值	未配置时的 fallback

配置示例：

# 1. 实例化时参数（最高优先级）
client = Quotes.factory(timeout=30, bestip=False)

# 2. 通过环境变量配置
import os
os.environ['MOOTDX_TIMEOUT'] = '20'

# 3. 通过配置文件配置
from mootdx.config import set
set('BESTIP', {'HQ': ('119.147.212.81', 7727)})  # 固定行情服务器

3.2 常见错误处理

网络连接错误：

try:
    client = Quotes.factory(bestip=True, timeout=10)
    quote = client.quotes('600036')
except Exception as e:
    logger.error(f"行情获取失败: {str(e)}")
    # 备用方案：使用本地缓存数据
    quote = load_cached_data('600036')

数据格式异常：

klines = client.bars('600036')
if klines is None or klines.empty:
    logger.warning("获取K线数据为空，使用备选接口")
    klines = backup_client.bars('600036')

3.3 性能优化配置

1. 缓存策略：

from mootdx.utils.pandas_cache import pd_cache

# 添加缓存装饰器（缓存有效期1小时）
@pd_cache(expired=3600)
def get_daily_data(symbol):
    return client.bars(symbol=symbol, frequency=9)

2. 批量请求优化：

# 批量获取多只股票行情（减少网络往返）
symbols = ['600036', '601318', '000858', '000001']
quotes = client.quotes(symbol=symbols)  # 一次请求获取多只股票

3. 服务器连接池：

# 长连接模式（适用于高频请求场景）
client = Quotes.factory(heartbeat=True, auto_retry=True)

MOOTDX数据处理流程示意图：从数据源获取到指标计算的完整链路

通过以上配置策略，可使MOOTDX在不同场景下均保持最佳性能表现。建议根据实际需求组合使用各类优化手段，平衡数据新鲜度与系统资源消耗。