## 根因
GetSecurityListCmd 请求体应为「12 字节命令头 + market(H) + start(H)」= 16 字节,
实现里多塞了一个 H(写死 0),实际发 18 字节。服务端只消费前 16 字节,剩下的
00 00 停在它接收缓冲里,把下一个请求的开头吃掉 —— 同一连接「第一次成功、
第二次起永远无响应」。
对照实验(同一主机、同一命令):
- 18 字节:第 1 次 OK,第 2/3 次全部 ConnectionError
- 16 字节:连发 3 次全部 OK(27 台主机复测,第二次请求 27/27 成功,此前 0/27)
分页器复用连接,等于每页都要先失败重连,冷启动被拖到 12~18s 且常直接报错。
| 场景 | 前 | 后 |
|---|---|---|
| get_universe("sh") 冷(27,534 条/28 页) | 12,267ms | 1,610ms |
| get_universe("sz") 冷(24,460 条/25 页) | 18,260ms | 571ms |
| get_universe() 全市场冷(146,848 条) | 19,085ms | 4,371ms |
| get_universe() 热 | — | 669ms |
## 北交所清单优雅降级
0x053E 对 market=2 在 27 台标准主机上全部无响应(26 台 6s 无回包、1 台立刻拒连),
同市场 0x053D 数量接口正常(389)。原实现重试 2 次×3s 后抛错,连带
get_universe() 整批失败。现直接返回空列表 + WARNING 一次。
北交所标的本身没问题:get_quotes("bj920992")/get_bars/逐笔全正常
(实测 11.79 与日线 close 一致)。
## 优化
- get_universe() 的 EX 全量只取一次(命中缓存也要反序列化 10 万条 ~200ms,
原先十几个 EX 市场各来一次)
- EX 商品列表改并发翻页(110 页,8 并发)
## 文档 / 测试
- get_universe docstring、API_REFERENCE、llms.txt、SKILL.md 写明北交所限制
- 新增 tests/test_universe.py 7 项:请求长度锁 16 字节、无尾部 padding、
北交所返回空且不碰连接池、_ex_all 只取一次
## 已知限制(非本次引入)
EX 全量含非证券条目(人员名录),(market, code) 原始数据里就不唯一,
重复出现在同一页内部;属数据源特性,未去重。
版本 0.6.8 → 0.6.9;测试 354 → 361 全通过。
Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
324 lines
20 KiB
Markdown
324 lines
20 KiB
Markdown
# pytdxdata 对外接口清单
|
||
|
||
> 以 `src/pytdxdata` 源码为准整理(v0.6.0)。分四类:Python API / 数据模型 / 辅助模块 / CLI。
|
||
>
|
||
> 方法与代码的一致性由 `scripts/check_docs.py` 在 CI 中校验。
|
||
|
||
## 一、包级导出
|
||
|
||
```python
|
||
from pytdxdata import (
|
||
TdxData, # 唯一对外入口类
|
||
Market, ExMarket, KlinePeriod, Adjust, # 枚举
|
||
SecurityBar, SecurityQuote, TransactionRecord, # 数据模型
|
||
MinuteBar, XdxrRecord, FinanceRecord,
|
||
__version__,
|
||
)
|
||
```
|
||
|
||
## 二、入口类 `TdxData`
|
||
|
||
构造参数(全部 keyword-only):
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `standard_servers` / `mac_servers` / `ex_servers` | None | 自定义服务器清单,None 用内置探测结果 |
|
||
| `port` | 7709 | 标准/MAC 端口(EX 固定 7727) |
|
||
| `timeout` | 3.0 | 连接超时(秒) |
|
||
| `cache_dir` | None | 磁盘缓存目录;None=仅内存缓存 |
|
||
| `default_adjust` | `Adjust.NONE` | 默认复权方式 |
|
||
| `max_inflight` | 64 | single-flight 并发上限 |
|
||
| `pool_min` / `pool_max` | 3 / 12 | 动态池上下限 |
|
||
| `mac_pool_cap` | 4 | 单台 MAC 服务器连接上限 |
|
||
|
||
生命周期:
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `async start()` | 启动(服务器探测 + 预建连接 + 缓存) |
|
||
| `async close()` | 关闭全部池与缓存 |
|
||
| `async with TdxData() as td:` | 上下文管理器,自动 start/close |
|
||
|
||
### 2.1 统一接口(v0.6+ 推荐){#unified}
|
||
|
||
以下方法在 v0.6 新增,标的一律用字符串(`sz000001` / `hk00700` / `usAAPL` / `cffex:IFL0`)。
|
||
|
||
#### 标的清单
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_universe(market=None)` | `list[SecurityInfo]` | 跨市场标的清单(A 股+港股+美股+期货/期权);每条带协议自带的 `decimal_point`(价格小数位)与 `pre_close`。**北交所清单协议不支持,返回空列表** |
|
||
| `sync_decimal_points(markets=("sh","sz"))` | `dict` | 从证券清单同步**权威价格小数位表**(`SecurityInfo.decimal_point`),灌进 `price_decimal_digits` 的运行时表;`start()` 已自动做(当日缓存命中则零网络),此方法用于强制刷新/排障 |
|
||
| `decimal_point_status()` | `dict` | 小数位表状态:`source`(`cache`/`universe`/空)、`stock`、`mixed_prefixes`、`syncing` |
|
||
|
||
#### 报价
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_quotes(symbols, *, fields=None, concurrency=None, pipeline=True)` | `list[SecurityQuote]` | 跨市场混合报价(A 股标准五档;给了 fields 走 MAC/EX 字段位有 name)。超 80 只自动切批,`pipeline` 开启**单连接流水线**,全市场 5,200 只 ~0.33s |
|
||
| `get_snapshot(symbols)` | `list[SymbolSnapshot]` | 个股特征快照(A 股) |
|
||
| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价(A 股) |
|
||
| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向(A 股) |
|
||
|
||
#### K线
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_bars(symbols, period=DAY, *, start=0, count=800, adjust=None, start_date=None, end_date=None, concurrency=6)` | `list[SecurityBar]` | 跨市场 K 线(自动判指数、复权走 MAC、并发分页、日期区间二分) |
|
||
| `get_indicators(symbols, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `list[IndicatorSet]` | K 线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
|
||
|
||
#### 逐笔与分时
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_ticks(symbols, *, date=None, start=0, count=None, concurrency=6)` | `list[TransactionRecord]` | 跨市场逐笔成交。返回按时间升序;`start` **从最新一笔往回数**;`vol`/`trade_count` 为约 3 秒切片的增量值(非累计)。**已剔除 `bs_flag=8` 竞价委托**(非成交,`vol` 为累计撮合量)。**指数**:`vol` 单位是百元(成交额/100)、`trade_count` 是均价×1000,均非股票语义;**可转债**:`vol` 是手(=10 张)、`trade_count` 是**真实笔数**,`Σvol` 与日线 `vol` **1:1** |
|
||
| `get_minutes(symbols, *, date=None, sampling=False, concurrency=6)` | `list[MinuteBar]` | 跨市场分时(sampling=True 取缩略采样:A股由 0x122D 派生,扩展市场 0x254D) |
|
||
|
||
#### 公司信息/文件/板块
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_f10(symbol, section=None, *, offset=0, length=65535)` | `list \| str` | F10 公司资料 |
|
||
| `get_file(name)` | `bytes` | 服务器文件原始字节(自动选通道) |
|
||
| `get_boards(kind="all", *, count=10000)` | `list[BoardInfo]` | 板块列表 |
|
||
| `get_board_members(board, *, fields=None, count=100000)` | `list[SecurityQuote]` | 板块成分股报价(归一模型) |
|
||
| `get_board_of(symbols)` | `list[BelongBoard]` | 个股所属板块 |
|
||
| `get_index_members(index, *, fields=None, count=100000)` | `list[SecurityQuote]` | **指数成分股**报价。裸 6 位按**指数语义**解析(`000001`=上证指数,不是平安银行):`000/999/880`→沪、`399`→深、`899`→北交所 |
|
||
| `get_index_trade_stats(index, date=None, *, concurrency=24, batch_size=50, members=None, skip_errors=True, on_progress=None)` | `IndexTradeStats` | **指数成分逐笔汇总**成每分钟成交量/成交笔数。协议里指数本身没有笔数(`trade_count` 是均价×1000),故由成分股逐笔累加;`.cumulative()` 取「截止该分钟累计」,`.cum_trade_count()` 直接给 `[(HH:MM, 累计笔数)]`。2230 只(上证)约 36-60 s |
|
||
| `get_index_trade_stats_multi(index, dates, *, ...)` | `list[IndexTradeStats]` | 多日批量版(成分只请求一次),用于「近 N 日同时点累计均值」基准 |
|
||
|
||
### 2.2 K线(旧接口,共 6 个) {#legacy-kline}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_kline(market, code, period, *, start=0, count=800, adjust=None, start_date=None, end_date=None)` | `list[SecurityBar]` | 主接口;count>页自动并发分页;复权走 MAC;支持日期区间(二分定位) |
|
||
| `get_kline_since(market, code, period, since, adjust=None)` | `list[SecurityBar]` | 增量便捷方法(≥since,含当天) |
|
||
| `get_kline_batch(stocks, period, *, start=0, count=800, adjust=None, concurrency=6)` | `dict[str, list[SecurityBar]]` | 多股票并发,返回 {code: bars} |
|
||
| `get_index_kline(market, code, period, *, start=0, count=800)` | `list[SecurityBar]` | 指数K线(含涨跌家数字段) |
|
||
| `get_stock_kline_with_indicators(market, code, indicators, *, period=DAY, count=30, adjust=None, params=None)` | `dict` | K线+技术指标(MACD/KDJ/RSI/BOLL/MA/EMA) |
|
||
| `get_kline_offset(offset=0, count=1)` | `tuple[int, int]` | K线偏移信息(MAC) |
|
||
|
||
### 2.3 报价(旧接口,共 4 个) {#legacy-quote}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_quotes(symbols, *, fields=None, concurrency=None, pipeline=True)` | `list[SecurityQuote]` | 五档报价;>80 只自动切批(流水线+工作窃取,5,200 只 ~0.33s);TTL 5s |
|
||
| `get_stock_quotes(stocks, bits=None)` | `list[MemberQuote]` | MAC 自定义字段报价(≤80只/次) |
|
||
| `get_stock_quotes_list(category, *, start=0, count=80, sort_type=0)` | `list[MemberQuote]` | 市场分类报价(0沪A/2深A/6全A/8科创/14创业) |
|
||
| `get_market_stat()` | `MarketStat` | 全市场统计(涨跌家数/总额/市值/涨跌停数) |
|
||
|
||
### 2.4 逐笔成交 / 分时(旧接口,共 4 个) {#legacy-tick}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_transactions(market, code, *, date=None, start=0, count=2000)` | `list[TransactionRecord]` | 逐笔成交(MAC,含 trade_count),支持历史日期 |
|
||
| `get_minute(market, code, *, date=None)` | `list[MinuteBar]` | 分时(MAC 0x122D,可历史) |
|
||
| `get_minute_batch(stocks, *, date=None, concurrency=6)` | `dict[str, list[MinuteBar]]` | 批量分时 |
|
||
| `get_chart_sampling(market, code)` | `list[float]` | 分时缩略采样(A股由 MAC **0x122D** 派生;0x254D 仅 EX 通道可用) |
|
||
|
||
### 2.5 证券列表(旧接口,共 3 个) {#legacy-list}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_security_count(market)` | `int` | 市场证券数量 |
|
||
| `get_security_list(market, *, start=0, count=None)` | `list[SecurityInfo]` | count=None=全部(先查总数防死循环) |
|
||
| `get_security_list_all(market)` | `list[SecurityInfo]` | 全市场列表(高并发一次拉完,缓存 1 天) |
|
||
|
||
### 2.6 除权 / 财务 / F10 / 文件(旧接口,共 15 个) {#file-methods}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_xdxr(symbols)` | `list[XdxrRecord]` | 除权除息历史(标准) |
|
||
| `get_finance(symbols)` | `list[FinanceRecord]` | 财务快照(标准;无数据的标的跳过) |
|
||
| `get_price_limits(symbol, name=None, pre_close=None, listed_days=9999)` | `tuple[float\|None, float\|None]` | 涨跌停价(本地计算) |
|
||
| `get_company_info_category(market, code)` | `list` | F10 目录(标准) |
|
||
| `get_company_info_content(market, code, filename, offset=0, length=65535)` | `str` | F10 内容(分块) |
|
||
| `get_block_info(filename)` | `bytes` | 板块文件**原始字节**(先查元数据再分块下载) |
|
||
| `get_report_file(filename)` | `bytes` | 报告/财务文件**原始字节**(标准 0x06B9) |
|
||
| `get_financial_file_list()` | `list[str]` | 财务文件列表**原始行**(tdxfin/gpcw.txt) |
|
||
| `get_financial_records(filename)` | `bytes` | 财报 `.dat` 原始字节(索引写 `.zip` 但服务器只有 `.dat` 时自动回退;取不到返回 `b""`) |
|
||
| `get_file_meta(filename)` | `FileMeta` | 远程文件元信息(MAC 0x1215) |
|
||
| `download_file(filename, filesize=0)` | `bytes` | 下载完整远程文件(MAC 0x1217,分块) |
|
||
| **`get_block_parsed(filename)`** | `list[TdxBlock]` | 板块文件**下载+解析**为板块成分(category 按文件名推断:0行业/2概念/3风格) |
|
||
| **`get_industry_map()`** | `dict[str, IndustryInfo]` | tdxhy.cfg **下载+解析**:`{代码: 通达信行业+申万行业}` |
|
||
| **`get_financial_file_infos()`** | `list[FinancialFileInfo]` | gpcw.txt **下载+解析**:文件名/MD5/大小 |
|
||
| **`get_financial_records_parsed(filename)`** | `list[FinancialRecord]` | 财报**解析**:每股原始 float 字段。可直接传 `get_financial_file_infos()` 的 `filename`——自动纠正服务器实际文件名(`.zip`/`.dat` 两种形态都支持);报告期取自文件名,缺失回退头部 |
|
||
|
||
> 解析层独立于网络层:解析器位于 `pytdxdata.codec`(纯标准库 `struct`/`zipfile`),可脱网单测;
|
||
> 原 `get_*` 返回 `bytes`/`list[str]` 的方法保持**向后兼容**,解析版为**新增**方法。
|
||
|
||
### 2.7 板块(旧接口,共 6 个) {#legacy-board}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_board_list(board_type=0, count=10000)` | `list[BoardInfo]` | 板块列表(0全部/1行业/2概念) |
|
||
| `get_board_members(board_symbol, count=100000, sort_type=0)` | `list[MemberQuote]` | 板块成分股报价(如 881001) |
|
||
| `get_belong_board(market, code)` | `list[BelongBoard]` | 个股所属板块 |
|
||
| `get_board_summary(board_symbol)` | `dict` | 汇总:成分数/成交额/主力净流入/涨跌家数 |
|
||
| `get_board_ranking(board_type=1, top_n=20)` | `list[dict]` | 板块涨跌幅排行 |
|
||
| `get_board_change_ranking(board_type=1, days=20, top_n=20)` | `list[dict]` | 板块 N 日涨跌幅排行(板块指数K线) |
|
||
|
||
### 2.8 MAC 扩展:竞价 / 异动 / 快照 / 资金流 / 服务器(旧接口,共 5 个) {#legacy-mac}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_auction(symbols)` | `list[AuctionItem]` | 集合竞价 |
|
||
| `get_unusual(market="all", *, start=0, count=600)` | `list[UnusualItem]` | 市场异动 |
|
||
| `get_symbol_info(market, code)` | `SymbolSnapshot` | 个股特征快照 |
|
||
| `get_capital_flow(symbols)` | `list[CapitalFlow]` | 个股资金流向 |
|
||
| `get_server_info()` | `ServerInfo` | 服务器交易时段信息 |
|
||
|
||
### 2.9 EX 扩展市场(旧接口,港股/美股/期货/期权,共 8 个) {#legacy-ex}
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|------|------|------|
|
||
| `get_goods_list(market, start=0, count=100)` | `list[dict]` | 扩展市场商品列表(0x23F5,二分定位市场) |
|
||
| `get_goods_count(market=None)` | `int` | 商品数量(None=全市场) |
|
||
| `get_goods_quotes(stocks, bits=None)` | `list[MemberQuote]` | 扩展市场报价(0x122B) |
|
||
| `get_goods_quotes_list(market, count=80)` | `list[MemberQuote]` | 商品列表+报价组合 |
|
||
| `get_goods_chart_sampling(market, code)` | `list[float]` | 扩展市场分时采样(0x254D) |
|
||
| `get_goods_tick_chart(market, code, ymd=0)` | `list[dict]` | 扩展市场分时 tick(0x122D) |
|
||
| `get_goods_transaction(market, code, *, ymd=0, start=0, count=1800)` | `list[dict]` | 扩展市场逐笔(港股 0x23FC/0x2406) |
|
||
| `get_goods_transaction_all(market, code, ymd=0)` | `list[dict]` | 港股全量逐笔(自动翻页,≤50页/9万条) |
|
||
|
||
**合计:`TdxData` 公开异步方法 63 个** = 28 个统一接口 + 33 个 deprecated 别名 + `start`/`close`
|
||
(另有 `_execute_standard` / `_execute_mac` / `_execute_ex` 等内部执行方法)。
|
||
|
||
## 三、数据模型(`pytdxdata.models`)
|
||
|
||
**枚举**
|
||
|
||
| 名称 | 取值 |
|
||
|------|------|
|
||
| `Market` | SZ=0 / SH=1 / BJ=2 |
|
||
| `KlinePeriod` | MIN_5=0 / MIN_15=1 / MIN_30=2 / MIN_60=3 / DAY=4 / WEEK=5 / MONTH=6 / MIN_1=7 / MIN_3=8 / YEAR=9 / SEASON=10 / YEAR_ALT=11(`is_minute` 属性) |
|
||
| `Adjust` | NONE=0 / QFQ=1 / HFQ=2 |
|
||
| `ExMarket` | 46 个扩展市场:HK_MAIN_BOARD=31 / US_STOCK=74 / CFFEX_FUTURES=47 / ZZ_FUTURES=28 / DL_FUTURES=29 / SH_FUTURES=30 / GZ_FUTURES=66 / SH_STOCK_OPTION=8 / SZ_STOCK_OPTION=9 等 |
|
||
|
||
**dataclass(均为 `@dataclass(slots=True)`)**
|
||
|
||
| 模型 | 关键字段 |
|
||
|------|---------|
|
||
| `SecurityBar` | market/code/open/high/low/close/vol/amount/year/month/day/hour/minute + `datetime` 属性 |
|
||
| `IndexBar` | 继承 `SecurityBar`(指数K线) |
|
||
| `SecurityQuote` | price/pre_close/OHLC/vol/amount/s_vol/b_vol/`bid[5]`/`ask[5]`/server_time/trading_status/cur_vol/rise_speed/limit_up/limit_down/decimal_point/open_amount |
|
||
| `SecurityInfo` | market/code/name/volunit/decimal_point/pre_close |
|
||
| `TransactionRecord` | market/code/time/price/vol/`trade_count`/bs_flag |
|
||
| `MinuteBar` | price/vol/avg_price/hour/minute/day_offset + `datetime`/`trading_date` 只读属性(hour 恒为合法时钟值 0~23;美股一个交易日跨两个北京自然日,按交易日聚合用 `trading_date`) |
|
||
| `XdxrRecord` | 分红送转/配股/缩股/行权 + 股本变动 + `date` 属性 |
|
||
| `FinanceRecord` | 股本/资产/负债/营收/利润等 36 个字段(万元/万股) |
|
||
| `BoardInfo` | 板块 + 领涨股信息 |
|
||
| `MemberQuote` | market/code/name/`fields: dict[str, float]` |
|
||
| `BelongBoard` | 个股所属板块 |
|
||
| `AuctionItem` | time/price/matched/unmatched |
|
||
| `UnusualItem` | 市场异动 |
|
||
| `SymbolSnapshot` | 个股特征快照 |
|
||
| `GoodsItem` | 扩展市场商品 |
|
||
| `ServerInfo` | date/last_trade_date/sessions |
|
||
| `CapitalFlow` | 主力/散户买卖 + 5档资金 |
|
||
| `TdxBlock` | name/category(0行业1地域2概念3风格)/count/`codes: list[str]`(板块成分,来自 block_*.dat) |
|
||
| `IndustryInfo` | code/tdx_industry/sw_industry(来自 tdxhy.cfg) |
|
||
| `FinancialFileInfo` | filename/hash/filesize(来自 gpcw.txt) |
|
||
| `FinancialRecord` | code/market/report_date/`fields: list[float]`(历史专业财报,注意与 `FinanceRecord` 区分) |
|
||
|
||
> 注:`__init__` 仅导出 `Market/ExMarket/KlinePeriod/Adjust` 与 6 个核心模型;`BoardInfo/MemberQuote/AuctionItem` 等需 `from pytdxdata.models import ...`。
|
||
|
||
**量纲对照(跨品种,2026-10-22 实测)**
|
||
|
||
同名字段在不同品种上单位不同。最典型的坑是用 `amount / vol` 算均价——它在可转债上会**错 10 倍**:
|
||
|
||
| 品种 | 分时 / 逐笔 `vol` | 日线 `SecurityBar.vol` | `Σ分时vol / 日线vol` | 日线 `amount / vol` |
|
||
|---|---|---|---|---|
|
||
| 股票 / ETF / LOF | 手(= 100 股) | 股 | **0.01** | 均价 ✓ |
|
||
| 可转债(110/111/113/118/123/127/128) | 手(= 10 张) | **手** | **1.0** | 均价 **×10** ⚠️ |
|
||
| 指数 | 百元(成交额/100) | 手 | — | 无意义(`amount` 是全板块口径) |
|
||
|
||
算均价:股票 `amount / vol`;可转债 `amount / vol / 10`;跨品种统一用 `Σ(price×vol) / Σvol`。
|
||
|
||
> 可转债的价格标度、分时、逐笔已全量校验(16 只当日 + 8 只历史日):分时末价 / 快照现价、`Σvol / 日线vol`、逐笔 VWAP vs `amount/(vol×10)` 比值均为 **1.000000**。
|
||
|
||
|
||
## 四、辅助模块
|
||
|
||
**`pytdxdata.indicator`**(技术指标,纯函数)
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `ma(values, period)` | 移动平均 |
|
||
| `ema(values, period)` | 指数移动平均 |
|
||
| `macd(values, fast=12, slow=26, signal=9)` | MACD |
|
||
| `rsi(values, period=14)` | RSI |
|
||
| `kdj(high, low, close, ...)` | KDJ |
|
||
| `boll(values, period=20, mult=2.0)` | 布林带 |
|
||
| `compute_indicators(high, low, close, indicators, params=None, tail=None)` | 统一入口(被 `get_stock_kline_with_indicators` 调用) |
|
||
|
||
**`pytdxdata.config`**(服务器清单与选路)
|
||
|
||
主机来源优先级链(各协议独立):`PYPYTDX_DATA_*_HOSTS` 环境变量 → **当日测速缓存** →
|
||
包内清单 `fast_pool` → 包内清单 → 代码内置常量。
|
||
|
||
| 函数 / 常量 | 说明 |
|
||
|------|------|
|
||
| `get_standard_hosts()` | 标准通道服务器列表(按上述优先级链解析) |
|
||
| `get_mac_hosts()` | MAC 通道服务器列表 |
|
||
| `get_ex_hosts()` | EX 扩展市场服务器列表 |
|
||
| `get_ex_handshakes()` | EX 握手方式映射 |
|
||
| `all_probe_candidates()` | 全量候选主机 `{standard, mac, ex}`(清单 ∪ 常量 ∪ env,**不按状态过滤**) |
|
||
| `is_valid_host(host)` | 主机名合法性校验(挡 mock 脏数据 / 非法条目) |
|
||
| `probe_cache_dir()` / `probe_cache_file()` | 用户级当日测速缓存目录 / 文件路径 |
|
||
| `load_probe_cache(today=None, path=None)` | 读当日测速缓存;缺失 / 损坏 / 非今日 / 版本不符 → `None` |
|
||
| `probe_disabled()` | 是否已用 `PYPYTDX_DATA_DISABLE_PROBE` 关闭测速 |
|
||
| `PROBE_CACHE_VERSION` | 测速缓存 payload 版本号 |
|
||
|
||
**`pytdxdata.pool.probe_cache`**(当日测速:后台执行、对用户无感)
|
||
|
||
| 符号 | 说明 |
|
||
|------|------|
|
||
| `ProbeCache` | 进程内协调器;`ensure_probe()` 为幂等入口(单飞 + 原子写) |
|
||
| `schedule_probe(hosts=None)` | 连接池用:挂后台 task 并返回该 task;无事件循环时返回 `None` |
|
||
| `get_probe_cache()` | 取进程级单例 |
|
||
|
||
**`pytdxdata.server_probe`**(离线服务器探测,`python -m pytdxdata.server_probe`)
|
||
`load_servers()` / `save_servers(cfg)` / `SERVERS_FILE` / `probe_one(server, timeout, discover)`
|
||
CLI 开关:`--discover`(三种协议全测并据实修正 `protocols`,同时剔除脏记录)/
|
||
`--group standard|mac|ex` / `--refresh`(只重测 `status=ok` 的)/ `--timeout`
|
||
|
||
## 五、CLI(`tdx` 命令,来自 `python -m pytdxdata.cli`)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `tdx quotes <sym...>` | 行情报价(五档) |
|
||
| `tdx kline <sym> [--period day] [--count 30] [--start 0] [--adjust none]` | K线 |
|
||
| `tdx index <code> [--count 30]` | 指数K线 |
|
||
| `tdx transactions <sym> [--count 30] [--date YYYYMMDD]` | 逐笔成交 |
|
||
| `tdx minute <sym> [--date YYYYMMDD]` | 分时 |
|
||
| `tdx board list\|members\|ranking\|change [--type 1] [--count 30] [--top 10] [--days 20]` | 板块 |
|
||
| `tdx info <sym>` | 个股特征快照 |
|
||
| `tdx list [--market sz] [--count 30]` | 证券列表 |
|
||
| `tdx auction <sym>` | 集合竞价 |
|
||
| `tdx unusual [--market sh] [--count 30]` | 市场异动 |
|
||
| `tdx xdxr <sym>` | 除权除息 |
|
||
| `tdx finance <sym>` | 财务快照 |
|
||
| `tdx flow <sym>` | 资金流向 |
|
||
| `tdx block [filename] [--limit 30] [--codes]` | 板块文件 下载+解析(block_*.dat → 成分股) |
|
||
| `tdx industry [codes...] [--limit 30] [--search 词]` | 行业分类 下载+解析(tdxhy.cfg) |
|
||
| `tdx financial-list [--limit 30]` | 历史专业财报文件索引(gpcw.txt) |
|
||
| `tdx financial <filename> [--code X] [--limit 5] [--fields 4]` | 历史专业财报记录 下载+解析(文件名自动纠正,见 `get_financial_records_parsed`) |
|
||
| `tdx server-info` | 服务器交易时段 |
|
||
| `tdx market-stat` | 市场统计 |
|
||
|
||
**标的写法**:`sz000001` / `sh600000` / `bj920992` / `hk00700` / `usAAPL` / `cffex:IFL0` / `000001`(6位数字=指数)
|
||
|
||
## 六、通道路由(内部自动)
|
||
|
||
| 命令 | 通道 |
|
||
|------|------|
|
||
| K线(复权 QFQ/HFQ) | MAC |
|
||
| K线(MIN_1 不复权) | MAC(串行分页) |
|
||
| K线(其他周期)/ 指数 | 标准 |
|
||
| 报价 | 标准 |
|
||
| 逐笔成交 / 分时 | MAC |
|
||
| 列表 / 数量 / 除权 / 财务 | 标准 |
|
||
| 板块 / 竞价 / 异动 / 快照 / 资金流 / 服务器 / 分类报价 | MAC |
|
||
| 港股 / 美股 / 期货 / 期权 | EX(端口 7727) |
|