简介tushare是国内流行的开源Python财经数据接口库本资源为tushare 0.2.0版本的最新源代码面向金融数据开发、量化分析及Python进阶学习者。源码完整呈现了股票、期货、基金等多类市场数据的实时与历史接口实现覆盖HTTP请求封装、数据解析、异常处理等核心逻辑有助于读者掌握数据获取的工程化写法。资源共44个文件包含25个Python源文件、7个RST文档以及配置文件、说明文档等压缩包仅269KB结构紧凑、便于精读。目前已有1493人学习下载。深入研读可进一步理解数据库存储设计、数据清洗预处理、多线程与异步IO并发优化以及错误处理与日志记录机制对提升大规模金融数据处理和Python编程能力很有价值。1. Tushare 最新源码先弄懂它到底干了一件什么事每当身边有朋友拿 A 股历史行情做回测我第一反应都是让他下载 Tushare 最新源代码看看而不是直接 pip install 完就闷头写策略。这个包在外界认知里常被当成“免费行情接口”实际上它的工程量远大于表面核心不是爬虫而是一整套围绕鉴权、积分、限流、字段映射、日期规范和数据清洗的 SDK 封装。每次调用pro.daily()背后都有一条从本地参数校验、动态注册接口、HTTP 请求、JSON 解析到 DataFrame 组装完成的完整链路。想自建行情服务或做数据层二次开发的开发者跟着下面的章节把源码走一遍不仅能跑通接口还能看清哪些改造点值得下手。2. 核心模块拆解一个行情请求从进入到返回的完整链路2.1 源码目录与三块核心把最新源码包解压后工程目录大致长这样tushare/ ├── __init__.py # 对外入口set_token / pro_api / pro_bar ├── pro/ │ ├── __init__.py # 接口注册表定义每个接口的参数与字段 │ ├── client.py # DataApi 客户端HTTP 请求与响应解析 │ └── ts_api.py # 接口名称与参数规格声明 ├── stock/ # 早期抓取逻辑属于历史兼容层 ├── util/ # 日期、配置等工具函数 ├── tests/ # 单元测试 └── setup.py # 项目安装脚本这个目录结构对初学者有几个迷惑点。整个仓库看起来不小但真正在二次开发里需要动刀的地方只有pro/目录下的两个文件。stock/是早期 2.x 时代的抓取层里面散落着不少直接对接网页数据的逻辑我当时翻这个目录花了一整晚最后的结论是可以直接绕过。你现在看到的绝大多数行情接口都走 pro 这一层stock/保留下来更多是为了让老脚本平滑迁移新项目里不要依赖它。整个源码可以抽象成三块入口层负责 Token 的全局管理和客户端对象的创建。客户端层DataApi类负责参数拼接、HTTP 请求、响应解析。注册表层声明每个接口的名称、参数列表和返回字段客户端初始化时按这张表动态生成同名方法。主干逻辑是典型的“数据字典驱动”想加一个新接口不用写新的调用函数只要在注册表里追加一条声明客户端启动后就会自动多出一个同名方法。这也是这个项目里最值得学习的设计思路之一。API_LIST { trade_cal: { api_name: trade_cal, params: [exchange, start_date, end_date], }, daily: { api_name: daily, params: [ts_code, trade_date, start_date, end_date], }, }这段简化的注册表说明了两件事。第一方法名如daily与远端的接口标识api_name可以解耦二次开发时你可以通过这张表把粗粒度接口拆成细粒度的内部服务而不必改动远端协议。第二参数列表是白名单式的客户端在请求前会拿这张表和调用方传入的 kwargs 做匹配。我读源码时特意把完整注册表打印出来数过一遍发现大多数行情接口返回字段都超过十个但业务里高频用到的通常只有四五个。这解释了为什么二次开发时不要直接透传接口给下游而要先做字段裁剪。2.2 从 ts.pro_api() 到一次 HTTP 请求入口模块的代码极其克制。set_token只是写入一个模块级变量pro_api则负责校验 Token 并创建客户端实例。源码简写之后大概是这样的_token def set_token(token): global _token _token token def pro_api(token, timeout30): global _token if token: _token token if not _token: raise Exception(未设置 token请先调用 set_token 或传入 token 参数) return DataApi(_token, timeouttimeout)这里有几个容易被忽略的点set_token并没有把 Token 持久化到磁盘。每次重启 Python 进程都要重新调用一次所以项目里一般把 Token 放到环境变量或配置文件中启动时统一读取。pro_api的timeout参数默认 30 秒。在部分网络环境下这个值经常不够用建议显式传入 60。token和timeout都支持在创建实例时传入这对多账号场景很友好。开两个DataApi实例就能隔离不同 Token 的调用额度不需要改全局状态。再看客户端client.py里的核心调用逻辑class DataApi: def __init__(self, token, timeout30): self._token token self._timeout timeout self._http requests.Session() self._build_api() def _build_api(self): for name, spec in API_LIST.items(): setattr(self, name, partial(self._query, spec)) def _query(self, spec, **kwargs): params {} for field in spec[params]: val kwargs.get(field) if val is None: continue if isinstance(val, (datetime, date)): val val.strftime(%Y%m%d) params[field] val payload { token: self._token, api_name: spec[api_name], params: params, } resp self._http.post(http://server, jsonpayload, timeoutself._timeout) return self._parse(resp.json())两个细节是源码阅读者容易忽略的。第一参数校验非常“宽容”。未知字段传入时_query不会报错只会被静默丢弃。这意味着你把ts_code拼成tsCode时接口不会提示你而是返回空数据或者无效参数。拼参数时最好自己先做一层白名单校验把错误留在本地暴露出来。第二日期参数在进入 HTTP 请求前做了统一格式化。datetime对象会被转成YYYYMMDD字符串这一步在源头就兜住了最常见的传参错误。不过这个格式化只覆盖了注册表里的标准参数有些人给trade_date传2024-01-02这种带横线的字符串不会被格式化逻辑捕获请求到远端依然会报错。_query的返回结果交给_parse这一步把 JSON 转成 pandas DataFrame是后续所有数据处理的地基。2.3 响应解析JSON 到 DataFrame 的清洗细节服务端返回的 JSON 遵循一套固定协议{ code: 0, msg: , data: { fields: [ts_code, trade_date, open, high, low, close], items: [[000001.SZ, 20240102, 10.0, 10.2, 9.8, 10.1]] } }解析代码并不复杂但边界情况不少def _parse(self, resp): if resp.get(code) ! 0: raise Exception(f{resp.get(code)}: {resp.get(msg)}) data resp.get(data) or {} fields data.get(fields, []) items data.get(items, []) if not fields or not items: return pd.DataFrame() df pd.DataFrame(items, columnsfields) return df这里有四条源码级经验空数据不报错。区间内没有交易日、股票停牌、代码写错都可能返回空列表最终得到空 DataFrame。调用方拿到后必须先做df.empty判断否则后续df[close].mean()会计算出 NaN 甚至直接崩掉。数据类型完全靠服务端保证。客户端不主动转to_datetime也不把价格列统一转 float。你拿到的 DataFrame 里trade_date是字符串open、close也是字符串需要按需清洗。很多人本地拼接后时序图乱序就是少了把trade_date转成日期类型再排序这一步。code非 0 时直接抛异常但异常信息里只有服务端返回的msg。想区分权限问题和数据问题只能在异常类型之外再套一层业务判断否则重试逻辑无从下手。返回的浮点字段没有做精度规整。amount、vol这类大数字字段经常以字符串形式出现服务端没有统一规范所以落地到数据库前一定要做类型转换。2.4 动态注册机制与 IDE 提示缺失问题_build_api这一段是整个设计最精妙的地方。它利用 Python 的动态语言特性在实例化时遍历注册表用setattr为每个接口动态生成一个绑定方法。这样pro.daily(...)、pro.trade_cal(...)在运行时才存在而不是写死在类定义里。这种做法的好处是扩展成本极低。远端每增加一个数据接口本地只需要在注册表里追加一条声明客户端无需调整。缺点是 IDE 代码提示基本失效。你用 PyCharm 写pro.的时候自动补全不会弹出daily因为方法不在类定义中方法名拼错只能运行时见分晓。我在实际项目里习惯的做法是在服务层显式声明方法签名class TushareClient: 包一层理想类型提示源码动态方法不可靠时才手动声明 def daily(self, ts_code: str, start_date: str, end_date: str) - pd.DataFrame: return self._pro.daily(ts_code, start_date, end_date)这样既保住了源码的动态注册能力又让 IDE 和同事能看懂接口属于比较实际的妥协方案。3. 跑通最小可用工程环境、Token 与第一次历史行情回补3.1 环境安装与源码安装两条路线拿到最新源码之后有两种跑法。第一种直接pip install tushare适合只使用不改造第二种是把源码包解压在项目根目录执行源码安装适合接下来要盯client.py做二次开发的场景。# 方式A直接安装 pip install tushare pandas requests # 方式B源码安装 cd tushare python setup.py install补充说明我一般不会用方式 B 的默认命令而是改用可编辑安装这样源码里任何修改都会立即反映到环境中不用反复重装。pip install -e .依赖方面其实很轻。pandas和requests是硬依赖其余的可选依赖等用到再装。这一点在setup.py里能直观看到作者刻意把核心依赖做得薄降低部署门槛。如果你用的 Python 版本比较新源码安装时可能会在 setup.py 阶段碰到编码问题。常见做法是打开setup.py在文件头部补上 Unicode 声明或者干脆走 pip 路线把精力留给后面的数据部分。3.2 准备 Token 与第一个能跑通的接口Tushare 的鉴权模型是“Token 积分”。Token 是一段密钥积分决定你能访问哪一档接口。第一次跑通不需要高积分用交易日历接口最合适因为它的权限门槛低返回结构也最简单。import tushare as ts # 设置全局 Token换成你自己的 ts.set_token(你的token字符串) # 创建客户端实例 pro ts.pro_api() # 拉取 2024 年上半年交易日历 cal pro.trade_cal(exchangeSSE, start_date20240101, end_date20240630) print(cal.head()) print(cal.shape)参数说明exchange交易所代码SSE代表上交所SZSE代表深交所。沪深两市交易日历基本一致回测场景传SSE就够。start_date与end_date闭区间两端日期都会包含。返回的cal_date是字符串型YYYYMMDDis_open用 1/0 标记是否交易日。这个脚本跑通说明 Token、网络、客户端解析三个环节都没问题。后续任何接口报错我都会用trade_cal当“信号灯”做排除——trade_cal通了别的接口还报错问题基本出在接口权限或参数上而不是全局配置。3.3 实战回补一年日线数据并落盘日历打通后我们来干正事把某只股票过去一年的日线行情拉下来存成 CSV。这里我用分段拉取的方式避免一次请求返回过多数据。import time import pandas as pd import tushare as ts pro ts.pro_api() ts_code 000001.SZ # 示例代码可换成任意 ts_code start 20230101 end 20231231 # 按季度分四段降低单次数据量 periods [ (20230101, 20230331), (20230401, 20230630), (20230701, 20230930), (20231001, 20231231), ] frames [] for s, e in periods: df pro.daily(ts_codets_code, start_dates, end_datee) if not df.empty: frames.append(df) time.sleep(0.5) # 控制调用频率避免触发限流 result pd.concat(frames, ignore_indexTrue) result result.drop_duplicates(subset[trade_date]) result result.sort_values(trade_date) result.to_csv(f{ts_code}_daily.csv, indexFalse) print(result.info())这一段包含几个实战技巧按季度分段回补而不是一次性传一年是因为单次接口返回的行数有上限。日线一年约 240 行问题不大但换成分钟线或全市场行情一次性请求很容易被截断。drop_duplicates(subset[trade_date])按交易日去重防止分段区间重叠导致重复行。这个去重字段的选取很关键不能用行号必须用业务主键trade_date。sort_values(trade_date)一定要做。接口对返回排序不保证严格升序分多次拼接后顺序完全取决于你的分段方式不排序会让后续的策略信号全乱。执行完脚本本地就有了一份可复现的日线文件。文件大小不大但已经是策略回测的可靠底座。3.4 增量更新与全量补数的选择逻辑很多人把“拉数据”想成一锤子买卖实际在策略迭代里增量更新才是常态。我一般会在本地维护一个“最后交易日”作为游标每天收盘后只拉新增区间。def get_latest_date(ts_code): try: cache pd.read_csv(f{ts_code}_daily.csv) return cache[trade_date].max() except FileNotFoundError: return 20100101 latest get_latest_date(ts_code) new_data pro.daily(ts_codets_code, start_datelatest, end_date20241231) # 拼接前把 latest 当天剔除避免与旧数据重复 new_data new_data[new_data[trade_date] latest]全量补数通常只在三种场景出现本地缓存损坏、策略需要更长历史、接口升级导致字段变化。全量补数时不要一次性拉到内存按年分段循环写文件即可成本远低于一次拉爆内存的惨痛体验。这里还有个血泪经验增量更新时区间两端都别手写直接从trade_cal取最新的cal_date作为end_date能避开节假日补班、临时休市这些黑天鹅。4. 避坑指南我在跑 Tushare 源码时反复踩的五个坑以下五个问题按出现频率排序整理前两个几乎每天都会有人遇到后三个属于表面现象不明显、排查成本高的类型。每条都按“现象、原因、解决”三个步骤写可以直接抄进自己的排查清单。4.1 现象接口报错 Invalid params跑pro.daily时最容易遇到的就是Invalid params但报错信息里经常不告诉你具体是哪个参数非法。第一次遇到时我逐个参数试错最后发现是字段名拼错——把start_date写成了start。原因一类是字段名不在注册表中被静默忽略但若传入了服务端不认识的字段服务端会直接判定无效另一类是把datetime对象当字符串传虽然源码里做了格式化但部分接口的参数定义没走统一路径。解决在调用前统一做参数构造把所有日期转成YYYYMMDD字符串并对字段名做白名单校验未知字段直接抛异常。与其在远端排查不如把错误留在本地。4.2 现象返回空 DataFrame权限和代码都没问题很多初学者遇到空数据会怀疑 Token 或积分其实更常见的原因是选的那只股票在区间内停牌或者上市日期晚于start_date又或者已经是退市状态。daily接口对无数据区间不回抛错只给一张空表。解决先用stock_basic核对ts_code是否存在、上市日期是否早于区间起点再用trade_cal确认区间内是否有交易日最后才怀疑自己的代码。我把这个问题叫“数据黑洞”排查顺序要固定下来才不慌。4.3 现象本地拼接后的行数和远端对不上我遇到过一个非常隐蔽的丢行问题分 12 个月拉日线逐月写文件最后总行数少了三天。排查了很久才发现是分段边界重叠导致去重误伤以及部分自然月末和实际最后交易日不一致。原因分段区间重叠时drop_duplicates会保留第一段的数据但如果两段的同一交易日数据内容有细微差异去重后会被误认为重复而丢失。另一个常见原因是手写月末日期没考虑节假日end_date落在非交易日上导致漏掉区间尾部真实存在的交易日。解决不要手写日期边界。从trade_cal动态生成“上一段最后交易日 1”作为下一段起点区间末尾的值也用最近的交易日字符串而不是自然日历的月末。4.4 现象循环批量拉数据时频繁被限流批量循环场景下连续请求十几个接口后服务端开始返回频率超限的报错。本质是对端每分钟请求次数有上限而源码里没有内建限流所有频率控制都靠调用方自觉。解决循环体里加time.sleep(0.3~0.6)并把被限流的接口放进重试队列间隔 5 秒重试。不要无脑 sleep 后再立刻请求那样往往越等越糟。更工程化的做法是做一个简单的令牌桶每个接口消耗一个令牌队列满就等待。4.5 现象daily 接口算出的收益率和实盘对不上daily返回的是不复权价格。直接用不复权价格计算收益率遇到分红、送股的时间点收益率会出现明显跳变回测结果和实盘对不上。很多人忽略复权这个步骤直到策略净值曲线出现诡异的断层才返工。原因回测口径不一致。daily只为日线行情服务复权因子是独立接口adj_factor负责的。用户期望“拿到的价格就是可直接用于计算的最终价格”但接口设计上并没有替你做这笔账。解决确认策略用的是哪一档复权口径。做因子研究推荐前复权做当日实盘模拟推荐不复权价格加复权因子自行计算。下面这段是我常用的复权加工方式import tushare as ts pro ts.pro_api() df pro.daily(ts_code000001.SZ, start_date20230101, end_date20241231) adj pro.adj_factor(ts_code000001.SZ, start_date20230101, end_date20241231) merged df.merge(adj, on[ts_code, trade_date]) merged[close_adj] (merged[close] * merged[adj_factor] / merged[adj_factor].iloc[0])逻辑说明把日线行情和复权因子按ts_code trade_date关联再用区间第一个交易日的复权因子做基准得到前复权收盘价。注意iloc[0]取的是合并后结果的第一行合并且排序之后才准。5. 二次开发落地把 Tushare 包进自己的行情服务层5.1 用服务层解决三个真实痛点直接调用pro.daily()有三个不舒服的地方IDE 不提示方法名、限流要自己控制、字段类型需要自己洗。我的做法是在项目里加一层轻服务封装把这三个问题一次解决。核心代码如下import pandas as pd import tushare as ts class MarketDataService: def __init__(self, token: str): self._pro ts.pro_api(token) def get_daily(self, ts_code: str, start: str, end: str) - pd.DataFrame: df self._pro.daily(ts_codets_code, start_datestart, end_dateend) if df.empty: return df df[trade_date] pd.to_datetime(df[trade_date]) df[close] df[close].astype(float) return df参数说明方法签名里显式写出ts_code、start、endIDE 补全恢复的同时也堵住了动态注册表字段名拼错的口子。返回前统一转日期和浮点类型下游直接用不用再猜字段。5.2 加一层文件缓存回测不再反复打接口服务层再加上 parquet 文件缓存就构成一个最小可用的行情服务。回测时优先读本地读不到才回源。def get_daily_cached(self, ts_code, start, end): cache_file fcache/{ts_code}.parquet try: cache pd.read_parquet(cache_file) except FileNotFoundError: cache pd.DataFrame() if cache.empty or cache[trade_date].max() end: new_data self.get_daily(ts_code, start, end) cache pd.concat([cache, new_data]).drop_duplicates(trade_date) cache.to_parquet(cache_file) return cache[(cache[trade_date] start) (cache[trade_date] end)]代码逻辑先把全量数据落到本地 parquet后续读取直接命中缓存文件。回测脚本全换成get_daily_cached之后接口限流风险基本消失重复实验也不用重新拉数据。5.3 一致性校验别省略改完服务层我无条件执行一遍一致性校验同一只股票、同一时间段对比本地缓存与远端直接拉取的行数和最后一行记录。行数或收盘价对不上就不入库先查缓存逻辑。从那以后我每次接入行情数据都强制先跑一遍trade_cal再定区间最后再做一次远端对比校验踩坑率明显下降。希望帮到你。本文还有配套的精品资源点击获取