stock-gateway 0.1.3

A-share data aggregation SDK with explicit gateway APIs.

Stock Gateway

A 股数据采集、聚合、研究和复盘辅助 Python SDK。项目对外提供显式网关方法，例如 get_quote()、get_kline()、get_depth()，调用方无需直接关心底层数据源 provider。

本 SDK 用于数据获取和研究辅助，不提供投资建议，也不是自动交易系统。

安装

pip install stock-gateway

指定版本：

pip install stock-gateway==0.1.3

运行环境：

• Python >=3.11
• 默认依赖：pandas、requests、thsdk、mootdx、lxml
• 使用 thsdk provider 时建议配置 THS_USERNAME、THS_PASSWORD；可选配置 THS_MAC

快速开始

from stock_gateway import StockGateway

gateway = StockGateway()

quote = gateway.get_quote("300498")
print(quote.ok, quote.provider, quote.error)
print(quote.data)

kline = gateway.get_kline("300498", interval="day", count=120)
print(kline.ok, kline.provider, kline.error)
print(kline.data)

使用完真实 provider 后，可以关闭 provider 持有的连接：

for provider in gateway.providers.values():
    close = getattr(provider, "close", None) or getattr(provider, "disconnect", None)
    if callable(close):
        close()

返回值

所有接口返回 GatewayResult：

字段	含义
ok	请求是否成功
data	标准化后的数据，常见为 pandas.DataFrame、dict、list 或 bytes
provider	实际命中的数据源
schema	标准化字段 schema
warnings	警告信息，例如兼容降级说明
fallback_chain	provider 尝试和降级链路
error	失败时的错误信息
raw	provider 原始结果，便于调试
symbol / normalized_symbol	输入代码和标准化代码信息
latency_ms	最终命中 provider 的耗时

示例：

result = gateway.get_quote(["600519", "300498"])

if result.ok:
    print(result.data)
else:
    print(result.error)

for attempt in result.fallback_chain:
    print(attempt.provider, attempt.status, attempt.error_type, attempt.error)

股票代码

常用接口可直接传 6 位 A 股代码：

gateway.get_quote("600519")
gateway.get_kline("300498", interval="1m", count=260)

SDK 会在内部转换为各 provider 需要的代码格式，例如腾讯、新浪、东方财富、同花顺和通达信格式。

Provider 与降级

默认 provider="auto"，SDK 会按接口策略选择 provider，并在语义兼容时自动降级。降级过程会写入 fallback_chain，不会静默换源。

result = gateway.get_kline("300498", interval="day")
print(result.provider)
print([(item.provider, item.status) for item in result.fallback_chain])

也可以指定 provider 并关闭降级：

result = gateway.get_quote("300498", provider="tencent", fallback=False)

常见 provider 名称包括：

• thsdk
• mootdx
• tencent
• sina
• baidu
• eastmoney
• cninfo
• ths_hot
• jiuyangongshe
• timor

已实现接口

行情与交易数据

方法	用途
get_quote(codes, provider="auto", fallback=True)	实时行情，支持单代码或代码列表
get_kline(code, interval="day", count=None, start=None, end=None, adjust=None, provider="auto", fallback=True)	K 线数据，支持日线和常见分钟周期
get_depth(code, provider="auto", fallback=True)	盘口深度
get_intraday(code, date=None, provider="auto", fallback=True)	日内分时
get_transaction(code, date=None, provider="auto", fallback=True)	逐笔成交
get_chart_image(code, period="daily", provider="auto", fallback=True)	走势图图片 bytes

新闻、公告与资讯

方法	用途
get_stock_news(code, limit=20, provider="auto", fallback=True)	个股新闻
get_global_news(limit=50, provider="auto", fallback=True)	全市场资讯
get_announcements(code, limit=30, provider="auto", fallback=True)	公司公告

资金、筹码与交易异动

方法	用途
get_fund_flow(code, period="minute", provider="auto", fallback=True)	资金流
get_fund_flow_120d(code, provider="auto", fallback=True)	近 120 日资金流
get_margin(code, provider="auto", fallback=True)	融资融券
get_block_trade(code, provider="auto", fallback=True)	大宗交易
get_holder_num(code, provider="auto", fallback=True)	股东户数
get_dividend(code, provider="auto", fallback=True)	分红送配
get_lockup_expiry(code, forward_days=90, provider="auto", fallback=True)	限售解禁
get_dragon_tiger(code, trade_date=None, look_back=30, provider="auto", fallback=True)	个股龙虎榜
get_daily_dragon_tiger(trade_date=None, provider="auto", fallback=True)	每日龙虎榜

指数、板块与题材

方法	用途
get_index_quote(index_code, provider="auto", fallback=True)	指数行情
get_index_kline(index_code, interval="day", provider="auto", fallback=True)	指数 K 线
get_index_list(provider="auto", fallback=True)	指数列表
get_sector_list(sector_type="industry", provider="auto", fallback=True)	板块列表
get_sector_quote(sector_code, provider="auto", fallback=True)	板块行情
get_sector_constituents(sector_code, provider="auto", fallback=True)	板块成分股
get_industry_rank(top_n=20, provider="auto", fallback=True)	行业涨跌排行
get_concept_blocks(code, provider="auto", fallback=True)	个股题材归属
get_hot_reason(date=None, provider="auto", fallback=True)	热点题材归因

交易日历

方法	用途
is_trading_day(date, provider="auto", fallback=True)	判断日期是否为交易日

财务、估值与研报

方法	用途
get_finance_snapshot(code, provider="auto", fallback=True)	财务快照
get_stock_info(code, provider="auto", fallback=True)	个股基础信息
get_reports(code, max_pages=2, provider="auto", fallback=True)	研报列表
download_report(record, target_dir=None, filename=None, provider="auto", fallback=True)	下载研报 PDF
get_eps_forecast(code, provider="auto", fallback=True)	EPS 预测
get_financial_statement(code, report_type="income", limit=8, provider="auto", fallback=True)	财务三表
get_valuation(code, provider="auto", fallback=True)	估值指标

问财与组合分析

方法	用途
query_wencai(query, provider="auto")	问财自然语言查询
query_wencai_base(query, provider="auto")	问财基础查询
screen_stocks(query, provider="auto")	自然语言选股
compare_stocks(codes, interval="day", count=30, provider="auto", fallback=True)	多股行情、走势和相关性对比
normalize_trend(codes, interval="day", count=30, provider="auto", fallback=True)	多股归一化走势
correlation_matrix(codes, interval="day", count=30, provider="auto", fallback=True)	多股收盘价相关性矩阵

环境变量

如果使用默认 StockGateway()，部分接口会优先或降级调用 thsdk。thsdk 连接同花顺行情服务时建议配置账号密码：

export THS_USERNAME="你的同花顺账号"
export THS_PASSWORD="你的同花顺密码"

如果需要固定设备标识，也可以配置：

export THS_MAC="你的 MAC 地址或 thsdk 要求的设备标识"

注意：

• 环境变量名大小写敏感，thsdk 默认读取 THS_USERNAME、THS_PASSWORD、THS_MAC。
• 如果部署平台使用 ths_username、ths_password 作为 secret 名称，请在启动进程前映射为大写环境变量。
• 本 SDK 不接入同花顺问财 OpenAPI，不读取 API_KEY，也不构造 X-Claw-* 请求头。
• 不要把真实账号、密码、Cookie、Token、Webhook 或本地行情缓存提交到代码仓库。
• 如果上层项目需要代理、缓存目录或日志配置，请在上层项目自行管理。

使用注意

• 行情、新闻、公告、财务和研报数据具有时效性，请在使用前重新拉取，并记录数据时间和 provider。
• 东方财富、同花顺热点等数据源可能触发风控，SDK 内部对相关 provider 做了串行限流；上层项目不要并发猛打接口。
• thsdk、mootdx 和网页数据源可能受本机环境、网络、交易时段和源站可用性影响；失败时优先查看 fallback_chain 和 error。
• 自动降级只发生在语义等价或兼容的数据源之间；不等价数据不会被静默替代。
• 问财相关接口通过 thsdk 承载，返回字段可能随查询语句和源站变化，建议保留 raw 便于排查。