yfinance 进阶使用指南全局配置、日志、缓存、多级列索引与价格数据修复【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance本篇技术指南围绕开源项目 yfinanceYahoo! Finance 数据下载器官方文档的 Advanced进阶章节展开系统讲解项目在安装、全局配置、日志调试、持久化缓存、多级列索引处理以及价格数据自动修复Price Repair这六大进阶主题上的能力与用法。读完本文你将掌握如何为 yfinance 配置网络代理与重试、切换 Yahoo 本地化语言、迁移缓存目录、正确读写多级列 DataFrame以及通过repairTrue修复 Yahoo 返回的各种价格、分红与拆分数据错误。本文主体内容来源于仓库中的 doc/source/advanced/index.rst 及其下属六篇文档并以 yfinance/config.py、yfinance/cache.py、yfinance/scrapers/history.py 等源码实现和 tests 目录下的测试数据作为佐证。一、安装进阶无curl_cffi的安装方式默认情况下yfinance 依赖curl_cffi来获取 Cookies 与进行 HTTP 请求。如果你的环境例如某些容器或企业内网无法安装curl_cffi官方进阶文档 install.rst 提供了两段式的降级安装方案curl -fsSL https://raw.githubusercontent.com/ranaroussi/yfinance/main/requirements.txt | grep -vi ^curl_cffi | pip install -r /dev/stdin pip install --no-deps yfinance第一段命令先从项目根目录的requirements.txt中过滤掉curl_cffi行将其余依赖通过/dev/stdin管道交给pip安装第二段命令使用--no-deps安装 yfinance 本体避免 pip 再次拉取被过滤掉的curl_cffi。安装完成后yfinance 会回退到 requests 等标准库完成请求代价是部分依赖curl_cffi的高级行为如更完整的 TLS 指纹模拟不可用。二、全局配置yf.config统一入口2.1 配置结构与源码实现yfinance 在 config.rst 中引入了一个新的全局配置对象yf.config用于统一共享常见配置值。导入后即可查看完整默认配置 import yfinance as yf yf.config { network: { proxy: null, retries: 0 }, debug: { hide_exceptions: true, logging: false } } yf.config.network { proxy: null, retries: 0 }其底层实现位于 yfinance/config.pyConfigMgr通过__getattr__惰性加载并维护一个嵌套字典self.options每个子项由NestedConfig包装支持config.network.proxy ...这种链式读写语法且__repr__会以 JSON 格式输出当前全部配置。源码中默认值初始化逻辑yfinance/config.py与文档展示的默认值完全一致network.proxy Nonenetwork.retries 0debug.hide_exceptions Truedebug.logging Falselocale.lang en-US、locale.region US另外旧版set_config(proxy..., retries...)API 仍在 yfinance/init.py 中保留但会触发DeprecationWarning官方推荐改用新的yf.config.network.proxy/yf.config.network.retries写法。2.2 Network代理与自动重试proxy— 为 yfinance 的所有数据抓取统一设置代理yf.config.network.proxy PROXY_SERVER设置后所有向 Yahoo Finance API 发起的请求都会走该代理适合在需要出口代理的网络环境中使用。retries— 为瞬态网络错误配置自动重试。重试机制采用指数退避exponential backoff间隔依次为 1 秒、2 秒、4 秒……yf.config.network.retries 2即遇到瞬态错误时最多自动重试 2 次且每次重试前的等待时间按指数增长避免对 Yahoo 服务器造成瞬时请求风暴。2.3 Debug异常可见性与调试日志hide_exceptions— 默认为True即 yfinance 会吞掉隐藏部分异常。设置为False可让异常原样抛出便于定位问题yf.config.debug.hide_exceptions Falselogging— 设置为True开启详细的调试日志输出yf.config.debug.logging True三、日志系统从仅错误到完整调试logging.rst 指出yfinance 使用 Python 标准库logging模块处理消息默认只记录错误级别ERROR以上的日志。需要排查问题时可开启调试模式import yfinance as yf yf.config.debug.logging True这与上一节debug.logging配置是同一开关开启后底层调用链如 yfinance/scrapers/history.py 中价格修复、缓存查找等路径上的logger.debug(...)日志都会输出到控制台方便追踪每次请求、每次修复的详细过程。仓库中utils.py提供的enable_debug_mode()函数已在 yfinance/init.py 中导出同样可用于快速进入调试模式。四、持久化缓存位置、机制与迁移4.1 缓存了什么为了减少对 Yahoo 的请求次数caching.rst 说明 yfinance 会在本地持久化两类数据时区信息timezone用于正确本地化交易日期的时区映射Cookies用于鉴权/会话的 Cookie 数据。从 yfinance/cache.py 源码可以看到实际持久化缓存有三套均使用 peewee 管理的 SQLite 数据库存放在统一的py-yfinance缓存目录下tkr-tz.dbticker → 时区 的键值表_TZ_KVcookies.db按策略strategy存储 Cookie 字节与抓取时间_CookieSchemaisin-tkr.dbISIN → ticker 的反查缓存_ISIN_KV。数据库打开时设置了 WAL 日志模式与cache_size-64的页缓存参数兼顾读写性能进程退出时通过atexit注册的钩子安全关闭数据库yfinance/cache.py。4.2 默认缓存位置缓存目录基于platformdirs.user_cache_dir()计算见 yfinance/cache.py各平台默认位置为Windows C:/Users/USER/AppData/Local/py-yfinanceLinux /home/USER/.cache/py-yfinanceMacOS /Users/USER/Library/Caches/py-yfinance4.3 迁移缓存位置如果默认目录不可写例如无权限或只读环境可用set_tz_cache_location指定新目录import yfinance as yf yf.set_tz_cache_location(custom/cache/location)注意该函数是 yfinance/cache.py 中set_cache_location的别名会同时重定向时区、Cookie、ISIN 三套缓存到新位置yfinance/cache.py。文档与源码都强调必须在缓存被使用即开始抓取数据之前调用否则缓存数据库已初始化迁移不会生效。如果缓存目录创建或读写失败yfinance 不会崩溃而是降级为哑缓存_TzCacheDummy/_CookieCacheDummy并在日志中提示可用set_tz_cache_location(mylocation)重定向yfinance/cache.py。仓库中的 tests/test_cache.py 与 tests/test_cache_noperms.py 覆盖了正常迁移与无权限场景。五、多级列索引Multi-Level Column 的读写multi_level_columns.rst 聚焦于一个高频问题yfinance 返回的pandas.DataFrame默认带有多级列名MultiIndex columns一层是 ticker一层是行情字段Open/High/Low/Close/Adj Close/Volume 等。该文档围绕 Stack Overflow 上如何处理 yfinance 下载的多级列名这一问题展开核心要点有两条正确理解列结构下载多个 ticker 时列索引是两个 level —— 外层是 ticker 代码内层是行情字段。例如yf.download([AAPL, MSFT])返回的 DataFrame 列形如(AAPL, Close)、(MSFT, Close)。CSV 读写与扁平化使用pandas.DataFrame.to_csv保存后再读回时需要正确还原 MultiIndex 列通常用pd.read_csv(..., header[0, 1], index_col0)若希望得到单级列名 ticker 列的扁平结构可以下载单个 ticker 得到单级列或对多级列做展平处理如df.columns df.columns.to_flat_index()并辅以stack/melt添加 ticker 列。需要说明的是该章节本质上是社区问答的整理给出的是 pandas 层面的处理思路而非 yfinance 独有 API实际操作时以你所用 pandas 版本的 MultiIndex 读写语法为准。六、价格修复repairTrue深度解析6.1 概览与启用方式price_repair.rst 是本进阶章节中技术含量最高的一篇。yfinance 在history()与download()中新增了repairTrue参数用于修复 Yahoo 返回的各种价格错误。官方文档的原话是只有美股数据看起来是完美的言下之意是全球其他市场的价格错误相对常见这正是该功能存在的意义。启用方式import yfinance as yf df yf.Ticker(MOB.ST).history(period1y, repairTrue) # 或批量下载 df yf.download(MOB.ST, period1y, repairTrue)启用后返回的表格会新增一列Repaired?标记该行是否被修复过。此外价格修复还能处理货币混用currency mixup问题——若发生货币修复真正的货币应以Ticker.history_metadata[currency]为准而不要查看Ticker.info。在源码 yfinance/scrapers/history.py 中可以看到修复流程的关键约束修复前必须先做去重df df[~df.index.duplicated(keepfirst)]避免脏数据干扰100x错误与股票拆分split修复必须先于价格重建执行_fix_unit_mixups/ split 修复在重建之前资本利得capital gains重复计算由独立的_repair_capital_gains方法处理yfinance/scrapers/history.pyrepair开关会被记录进history_metadata[YF repair?]后续history_metadata[currency]等字段的取值会据此联动yfinance/scrapers/history.py。6.2 价格修复的四种场景1) 缺失股息调整Missing dividend adjustment如果数据中存在分红Dividends但其前一天的Adj Close与Close完全相等说明 Yahoo 漏做了复权调整此时会手动对Adj Close应用股息调整。注意由于该修复只改动Adj Close列Repaired?不会被置为True。2) 缺失拆股调整Missing split adjustment如果数据中存在股票拆分Stock Split但其前序价格数据未调整则会手动应用拆股比例。前提是请求的日期范围要包含拆股日后 1 天以便用该日价格做校准——因为 Yahoo 有时在拆股当天不调整价格。3) 缺失数据Missing data如果价格数据明显缺失或损坏会使用更小的时间间隔来重建例如用1h数据修复1d数据。这在单行缺失、以及成交量缺失但价格正常变动两种子场景下都有应用4) 100x 错误100x errorsYahoo 有时会混用货币单位例如$与cents、£与pence导致部分价格恰好相差 100 倍。这类错误有两种形态随机散布在数据中通过scipy模块的统计方法检测并修复成块出现说明 Yahoo 在某一天永久切换了计价货币形成整段 100x 偏差。6.3 价格重建的算法注意事项price_repair.rst 特别说明了价格重建reconstruction的工程细节尽量合并抓取grouping fetches以减少请求次数避免对 Yahoo 的无效骚扰对数据限制有感知例如1h间隔无法获取超过 2 年的历史重建时不会越界请求预期偏差如果 Yahoo 日后修复了原始数据你会看到重建价格与其略有不同成交量甚至可能差异显著——这是算法尽力而为的结果总比缺失数据强。6.4 股息修复六类错误的自动修复除价格修复外repairTrue还会修复分红Dividends数据中的错误官方文档列出的检查项包括调整缺失或调整相对股息 100 倍过大/过小7 天内出现重复股息股息相对除息日ex-dividend价格跌幅 100 倍过大/过小除息日标注错误价格跌幅出现在数天/数周之后新增资本利得被重复计算capital gains double-counted。文档直言多数错误出现在伦敦证券交易所£/pence 混用但没有任何交易所是绝对安全的。仓库测试目录 tests/data 中有大量针对性的回归样本例如1398-HK-1d-bad-div.csv/-fixed.csv调整缺失4063-T-1d-bad-stock-split.csv拆股调整缺失AET-L-1d-100x-error.csv100x 价格错误DODFX-1d-cg-double-count.csv资本利得重复计算8TRA-DE-1d-missing-div-adjust.csv股息调整缺失以及*-no-bad-divs.csv这类无错误对照样本用于校验修复逻辑不会误伤正常数据。6.5 误报False Positives风险与规避由于第 3 类修复股息与价格跌幅的 100x 比对依赖价格行为判断存在把好数据误判为坏数据的false positiveFP风险。文档给出了两条关键约束仅对 1d 间隔执行股息修复。更长间隔周线等的 FP 率会显著上升。如果你对多日间隔请求修复内部流程是先从 Yahoo 取 1d 数据 → 修复 → 再重采样resample成目标间隔。这还附带一个好处顺带解决了 Yahoo 对多日间隔做股息复权时的缺陷。1d 的 FP 率极小主要出现在极小股息如 0.5%场景算法可能把正常的股价波动误认为比股息大 100 倍的除息跌幅进而修复一个本不需要修复的小股息修复逻辑已通过减去中位数来尽量抵消正常波动的影响。规避方式是抓取 6–12 个月、包含至少 2 次分红的价格数据通过多笔股息联合分析来识别误报。6.6 修复效果对照真实数据示例下面完整收录官方文档中各类修复的前后对照便于理解修复逻辑与预期结果。调整缺失1398.HK# ORIGINAL: Close Adj Close Dividends 2024-07-08 00:00:0008:00 4.33 4.33 0.335715 2024-07-04 00:00:0008:00 4.83 4.83 0.000000 # REPAIRED: Close Adj Close Dividends 2024-07-08 00:00:0008:00 4.33 4.330000 0.335715 2024-07-04 00:00:0008:00 4.83 4.494285 0.000000调整太小3IN.L# ORIGINAL: Close Adj Close Dividends 2024-06-13 00:00:0001:00 3.185 3.185000 0.05950 2024-06-12 00:00:0001:00 3.270 3.269405 0.00000 # REPAIRED: Close Adj Close Dividends 2024-06-13 00:00:0001:00 3.185 3.185000 0.05950 2024-06-12 00:00:0001:00 3.270 3.210500 0.000007 天内重复ALC.SW# ORIGINAL: Close Adj Close Dividends 2023-05-10 00:00:0002:00 70.580002 70.352142 0.21 2023-05-09 00:00:0002:00 65.739998 65.318443 0.21 2023-05-08 00:00:0002:00 66.379997 65.745682 0.00 # REPAIRED: Close Adj Close Dividends 2023-05-10 00:00:0002:00 70.580002 70.352142 0.00 2023-05-09 00:00:0002:00 65.739998 65.527764 0.21 2023-05-08 00:00:0002:00 66.379997 65.956371 0.00股息太大HLCL.L# ORIGINAL: Close Adj Close Dividends 2024-06-27 00:00:0001:00 2.360 2.3600 1.78 2024-06-26 00:00:0001:00 2.375 2.3572 0.00 # REPAIRED: Close Adj Close Dividends 2024-06-27 00:00:0001:00 2.360 2.3600 0.0178 2024-06-26 00:00:0001:00 2.375 2.3572 0.0000股息与调整都太大LTI.L# ORIGINAL: Close Adj Close Adj Dividends 2024-08-08 00:00:0001:00 768.0 768.0 1.0000 5150.0 2024-08-07 00:00:0001:00 819.0 -4331.0 -5.2882 0.0 # REPAIRED: Close Adj Close Adj Dividends 2024-08-08 00:00:0001:00 768.0 768.0 1.0000 51.5 2024-08-07 00:00:0001:00 819.0 767.5 0.9371 0.0股息太小BVT.L# ORIGINAL: Close Adj Close Adj Dividends 2022-02-03 00:00:0000:00 0.7534 0.675197 0.8962 0.00001 2022-02-01 00:00:0000:00 0.7844 0.702970 0.8962 0.00000 # REPAIRED: Close Adj Close Adj Dividends 2022-02-03 00:00:0000:00 0.7534 0.675197 0.8962 0.001 2022-02-01 00:00:0000:00 0.7844 0.702075 0.8950 0.000前一日被多调整一次2020.OL线索Close Low# ORIGINAL: Low Close Adj Close Dividends 2023-12-21 00:00:0001:00 120.199997 121.099998 118.868782 0.18 2023-12-20 00:00:0001:00 122.000000 121.900002 119.477371 0.00 # REPAIRED: Low Close Adj Close Dividends 2023-12-21 00:00:0001:00 120.199997 121.099998 118.868782 0.18 2023-12-20 00:00:0001:00 122.000000 122.080002 119.654045 0.00除息日错误TETY.ST——价格跌幅出现在 6-20 与 6-17 之间而分红记录在 6-20修复将分红移动到正确的除息日# ORIGINAL: Close Adj Close Dividends 2022-06-22 00:00:0002:00 66.699997 60.085415 0.0 2022-06-21 00:00:0002:00 71.599998 64.499489 0.0 2022-06-20 00:00:0002:00 71.800003 64.679657 5.0 2022-06-17 00:00:0002:00 71.000000 59.454838 0.0 # REPAIRED: Close Adj Close Dividends 2022-06-22 00:00:0002:00 66.699997 60.085415 5.0 2022-06-21 00:00:0002:00 71.599998 60.007881 0.0 2022-06-20 00:00:0002:00 71.800003 60.175503 0.0 2022-06-17 00:00:0002:00 71.000000 59.505021 0.0资本利得被重复计算DODFX线索价格跌幅与股息更匹配而与股息资本利得之和匹配不上# ORIGINAL: Close Adj Close Dividends Capital Gains Date 2025-12-18 00:00:00-05:00 16.219999 16.219999 0.837 0.417 2025-12-17 00:00:00-05:00 16.920000 15.665999 0.000 0.000 # REPAIRED: Close Adj Close Dividends Capital Gains Date 2025-12-18 00:00:00-05:00 16.219999 16.219999 0.42 0.417 2025-12-17 00:00:00-05:00 16.920000 16.083000 0.00 0.000七、附录进阶主题速查与源码索引主题关联文档核心源码/测试一句话要点安装doc/source/advanced/install.rstpyproject.toml、requirements.txt无curl_cffi环境的降级安装配置doc/source/advanced/config.rstyfinance/config.pyyf.config统一管理 proxy / retries / debug / locale日志doc/source/advanced/logging.rstyfinance/utils.py默认仅 ERROR调试时开启debug.logging缓存doc/source/advanced/caching.rstyfinance/cache.pySQLite 持久化时区/Cookie/ISIN可迁移目录多级列doc/source/advanced/multi_level_columns.rstyf.download返回结构多 ticker 数据为 ticker×字段两层列索引价格修复doc/source/advanced/price_repair.rstyfinance/scrapers/history.py、tests/datarepairTrue修复价格/分红/拆分/货币错误进阶文档的整体结构即 doc/source/advanced/index.rst 的 toctree与本节一一对应。建议读者在读完本文后按需深入对应源码文件配置读写看 yfinance/config.py缓存机制看 yfinance/cache.py价格修复的完整判定与重建逻辑看 yfinance/scrapers/history.py 中_fix_unit_mixups、_reconstruct_intervals_batch、_repair_capital_gains等实现回归测试与样本数据则集中在 tests 目录。这样既能理解每个参数的行为边界也能在遇到异常数据时快速定位修复路径。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
yfinance 进阶使用指南：全局配置、日志、缓存、多级列索引与价格数据修复
yfinance 进阶使用指南全局配置、日志、缓存、多级列索引与价格数据修复【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance本篇技术指南围绕开源项目 yfinanceYahoo! Finance 数据下载器官方文档的 Advanced进阶章节展开系统讲解项目在安装、全局配置、日志调试、持久化缓存、多级列索引处理以及价格数据自动修复Price Repair这六大进阶主题上的能力与用法。读完本文你将掌握如何为 yfinance 配置网络代理与重试、切换 Yahoo 本地化语言、迁移缓存目录、正确读写多级列 DataFrame以及通过repairTrue修复 Yahoo 返回的各种价格、分红与拆分数据错误。本文主体内容来源于仓库中的 doc/source/advanced/index.rst 及其下属六篇文档并以 yfinance/config.py、yfinance/cache.py、yfinance/scrapers/history.py 等源码实现和 tests 目录下的测试数据作为佐证。一、安装进阶无curl_cffi的安装方式默认情况下yfinance 依赖curl_cffi来获取 Cookies 与进行 HTTP 请求。如果你的环境例如某些容器或企业内网无法安装curl_cffi官方进阶文档 install.rst 提供了两段式的降级安装方案curl -fsSL https://raw.githubusercontent.com/ranaroussi/yfinance/main/requirements.txt | grep -vi ^curl_cffi | pip install -r /dev/stdin pip install --no-deps yfinance第一段命令先从项目根目录的requirements.txt中过滤掉curl_cffi行将其余依赖通过/dev/stdin管道交给pip安装第二段命令使用--no-deps安装 yfinance 本体避免 pip 再次拉取被过滤掉的curl_cffi。安装完成后yfinance 会回退到 requests 等标准库完成请求代价是部分依赖curl_cffi的高级行为如更完整的 TLS 指纹模拟不可用。二、全局配置yf.config统一入口2.1 配置结构与源码实现yfinance 在 config.rst 中引入了一个新的全局配置对象yf.config用于统一共享常见配置值。导入后即可查看完整默认配置 import yfinance as yf yf.config { network: { proxy: null, retries: 0 }, debug: { hide_exceptions: true, logging: false } } yf.config.network { proxy: null, retries: 0 }其底层实现位于 yfinance/config.pyConfigMgr通过__getattr__惰性加载并维护一个嵌套字典self.options每个子项由NestedConfig包装支持config.network.proxy ...这种链式读写语法且__repr__会以 JSON 格式输出当前全部配置。源码中默认值初始化逻辑yfinance/config.py与文档展示的默认值完全一致network.proxy Nonenetwork.retries 0debug.hide_exceptions Truedebug.logging Falselocale.lang en-US、locale.region US另外旧版set_config(proxy..., retries...)API 仍在 yfinance/init.py 中保留但会触发DeprecationWarning官方推荐改用新的yf.config.network.proxy/yf.config.network.retries写法。2.2 Network代理与自动重试proxy— 为 yfinance 的所有数据抓取统一设置代理yf.config.network.proxy PROXY_SERVER设置后所有向 Yahoo Finance API 发起的请求都会走该代理适合在需要出口代理的网络环境中使用。retries— 为瞬态网络错误配置自动重试。重试机制采用指数退避exponential backoff间隔依次为 1 秒、2 秒、4 秒……yf.config.network.retries 2即遇到瞬态错误时最多自动重试 2 次且每次重试前的等待时间按指数增长避免对 Yahoo 服务器造成瞬时请求风暴。2.3 Debug异常可见性与调试日志hide_exceptions— 默认为True即 yfinance 会吞掉隐藏部分异常。设置为False可让异常原样抛出便于定位问题yf.config.debug.hide_exceptions Falselogging— 设置为True开启详细的调试日志输出yf.config.debug.logging True三、日志系统从仅错误到完整调试logging.rst 指出yfinance 使用 Python 标准库logging模块处理消息默认只记录错误级别ERROR以上的日志。需要排查问题时可开启调试模式import yfinance as yf yf.config.debug.logging True这与上一节debug.logging配置是同一开关开启后底层调用链如 yfinance/scrapers/history.py 中价格修复、缓存查找等路径上的logger.debug(...)日志都会输出到控制台方便追踪每次请求、每次修复的详细过程。仓库中utils.py提供的enable_debug_mode()函数已在 yfinance/init.py 中导出同样可用于快速进入调试模式。四、持久化缓存位置、机制与迁移4.1 缓存了什么为了减少对 Yahoo 的请求次数caching.rst 说明 yfinance 会在本地持久化两类数据时区信息timezone用于正确本地化交易日期的时区映射Cookies用于鉴权/会话的 Cookie 数据。从 yfinance/cache.py 源码可以看到实际持久化缓存有三套均使用 peewee 管理的 SQLite 数据库存放在统一的py-yfinance缓存目录下tkr-tz.dbticker → 时区 的键值表_TZ_KVcookies.db按策略strategy存储 Cookie 字节与抓取时间_CookieSchemaisin-tkr.dbISIN → ticker 的反查缓存_ISIN_KV。数据库打开时设置了 WAL 日志模式与cache_size-64的页缓存参数兼顾读写性能进程退出时通过atexit注册的钩子安全关闭数据库yfinance/cache.py。4.2 默认缓存位置缓存目录基于platformdirs.user_cache_dir()计算见 yfinance/cache.py各平台默认位置为Windows C:/Users/USER/AppData/Local/py-yfinanceLinux /home/USER/.cache/py-yfinanceMacOS /Users/USER/Library/Caches/py-yfinance4.3 迁移缓存位置如果默认目录不可写例如无权限或只读环境可用set_tz_cache_location指定新目录import yfinance as yf yf.set_tz_cache_location(custom/cache/location)注意该函数是 yfinance/cache.py 中set_cache_location的别名会同时重定向时区、Cookie、ISIN 三套缓存到新位置yfinance/cache.py。文档与源码都强调必须在缓存被使用即开始抓取数据之前调用否则缓存数据库已初始化迁移不会生效。如果缓存目录创建或读写失败yfinance 不会崩溃而是降级为哑缓存_TzCacheDummy/_CookieCacheDummy并在日志中提示可用set_tz_cache_location(mylocation)重定向yfinance/cache.py。仓库中的 tests/test_cache.py 与 tests/test_cache_noperms.py 覆盖了正常迁移与无权限场景。五、多级列索引Multi-Level Column 的读写multi_level_columns.rst 聚焦于一个高频问题yfinance 返回的pandas.DataFrame默认带有多级列名MultiIndex columns一层是 ticker一层是行情字段Open/High/Low/Close/Adj Close/Volume 等。该文档围绕 Stack Overflow 上如何处理 yfinance 下载的多级列名这一问题展开核心要点有两条正确理解列结构下载多个 ticker 时列索引是两个 level —— 外层是 ticker 代码内层是行情字段。例如yf.download([AAPL, MSFT])返回的 DataFrame 列形如(AAPL, Close)、(MSFT, Close)。CSV 读写与扁平化使用pandas.DataFrame.to_csv保存后再读回时需要正确还原 MultiIndex 列通常用pd.read_csv(..., header[0, 1], index_col0)若希望得到单级列名 ticker 列的扁平结构可以下载单个 ticker 得到单级列或对多级列做展平处理如df.columns df.columns.to_flat_index()并辅以stack/melt添加 ticker 列。需要说明的是该章节本质上是社区问答的整理给出的是 pandas 层面的处理思路而非 yfinance 独有 API实际操作时以你所用 pandas 版本的 MultiIndex 读写语法为准。六、价格修复repairTrue深度解析6.1 概览与启用方式price_repair.rst 是本进阶章节中技术含量最高的一篇。yfinance 在history()与download()中新增了repairTrue参数用于修复 Yahoo 返回的各种价格错误。官方文档的原话是只有美股数据看起来是完美的言下之意是全球其他市场的价格错误相对常见这正是该功能存在的意义。启用方式import yfinance as yf df yf.Ticker(MOB.ST).history(period1y, repairTrue) # 或批量下载 df yf.download(MOB.ST, period1y, repairTrue)启用后返回的表格会新增一列Repaired?标记该行是否被修复过。此外价格修复还能处理货币混用currency mixup问题——若发生货币修复真正的货币应以Ticker.history_metadata[currency]为准而不要查看Ticker.info。在源码 yfinance/scrapers/history.py 中可以看到修复流程的关键约束修复前必须先做去重df df[~df.index.duplicated(keepfirst)]避免脏数据干扰100x错误与股票拆分split修复必须先于价格重建执行_fix_unit_mixups/ split 修复在重建之前资本利得capital gains重复计算由独立的_repair_capital_gains方法处理yfinance/scrapers/history.pyrepair开关会被记录进history_metadata[YF repair?]后续history_metadata[currency]等字段的取值会据此联动yfinance/scrapers/history.py。6.2 价格修复的四种场景1) 缺失股息调整Missing dividend adjustment如果数据中存在分红Dividends但其前一天的Adj Close与Close完全相等说明 Yahoo 漏做了复权调整此时会手动对Adj Close应用股息调整。注意由于该修复只改动Adj Close列Repaired?不会被置为True。2) 缺失拆股调整Missing split adjustment如果数据中存在股票拆分Stock Split但其前序价格数据未调整则会手动应用拆股比例。前提是请求的日期范围要包含拆股日后 1 天以便用该日价格做校准——因为 Yahoo 有时在拆股当天不调整价格。3) 缺失数据Missing data如果价格数据明显缺失或损坏会使用更小的时间间隔来重建例如用1h数据修复1d数据。这在单行缺失、以及成交量缺失但价格正常变动两种子场景下都有应用4) 100x 错误100x errorsYahoo 有时会混用货币单位例如$与cents、£与pence导致部分价格恰好相差 100 倍。这类错误有两种形态随机散布在数据中通过scipy模块的统计方法检测并修复成块出现说明 Yahoo 在某一天永久切换了计价货币形成整段 100x 偏差。6.3 价格重建的算法注意事项price_repair.rst 特别说明了价格重建reconstruction的工程细节尽量合并抓取grouping fetches以减少请求次数避免对 Yahoo 的无效骚扰对数据限制有感知例如1h间隔无法获取超过 2 年的历史重建时不会越界请求预期偏差如果 Yahoo 日后修复了原始数据你会看到重建价格与其略有不同成交量甚至可能差异显著——这是算法尽力而为的结果总比缺失数据强。6.4 股息修复六类错误的自动修复除价格修复外repairTrue还会修复分红Dividends数据中的错误官方文档列出的检查项包括调整缺失或调整相对股息 100 倍过大/过小7 天内出现重复股息股息相对除息日ex-dividend价格跌幅 100 倍过大/过小除息日标注错误价格跌幅出现在数天/数周之后新增资本利得被重复计算capital gains double-counted。文档直言多数错误出现在伦敦证券交易所£/pence 混用但没有任何交易所是绝对安全的。仓库测试目录 tests/data 中有大量针对性的回归样本例如1398-HK-1d-bad-div.csv/-fixed.csv调整缺失4063-T-1d-bad-stock-split.csv拆股调整缺失AET-L-1d-100x-error.csv100x 价格错误DODFX-1d-cg-double-count.csv资本利得重复计算8TRA-DE-1d-missing-div-adjust.csv股息调整缺失以及*-no-bad-divs.csv这类无错误对照样本用于校验修复逻辑不会误伤正常数据。6.5 误报False Positives风险与规避由于第 3 类修复股息与价格跌幅的 100x 比对依赖价格行为判断存在把好数据误判为坏数据的false positiveFP风险。文档给出了两条关键约束仅对 1d 间隔执行股息修复。更长间隔周线等的 FP 率会显著上升。如果你对多日间隔请求修复内部流程是先从 Yahoo 取 1d 数据 → 修复 → 再重采样resample成目标间隔。这还附带一个好处顺带解决了 Yahoo 对多日间隔做股息复权时的缺陷。1d 的 FP 率极小主要出现在极小股息如 0.5%场景算法可能把正常的股价波动误认为比股息大 100 倍的除息跌幅进而修复一个本不需要修复的小股息修复逻辑已通过减去中位数来尽量抵消正常波动的影响。规避方式是抓取 6–12 个月、包含至少 2 次分红的价格数据通过多笔股息联合分析来识别误报。6.6 修复效果对照真实数据示例下面完整收录官方文档中各类修复的前后对照便于理解修复逻辑与预期结果。调整缺失1398.HK# ORIGINAL: Close Adj Close Dividends 2024-07-08 00:00:0008:00 4.33 4.33 0.335715 2024-07-04 00:00:0008:00 4.83 4.83 0.000000 # REPAIRED: Close Adj Close Dividends 2024-07-08 00:00:0008:00 4.33 4.330000 0.335715 2024-07-04 00:00:0008:00 4.83 4.494285 0.000000调整太小3IN.L# ORIGINAL: Close Adj Close Dividends 2024-06-13 00:00:0001:00 3.185 3.185000 0.05950 2024-06-12 00:00:0001:00 3.270 3.269405 0.00000 # REPAIRED: Close Adj Close Dividends 2024-06-13 00:00:0001:00 3.185 3.185000 0.05950 2024-06-12 00:00:0001:00 3.270 3.210500 0.000007 天内重复ALC.SW# ORIGINAL: Close Adj Close Dividends 2023-05-10 00:00:0002:00 70.580002 70.352142 0.21 2023-05-09 00:00:0002:00 65.739998 65.318443 0.21 2023-05-08 00:00:0002:00 66.379997 65.745682 0.00 # REPAIRED: Close Adj Close Dividends 2023-05-10 00:00:0002:00 70.580002 70.352142 0.00 2023-05-09 00:00:0002:00 65.739998 65.527764 0.21 2023-05-08 00:00:0002:00 66.379997 65.956371 0.00股息太大HLCL.L# ORIGINAL: Close Adj Close Dividends 2024-06-27 00:00:0001:00 2.360 2.3600 1.78 2024-06-26 00:00:0001:00 2.375 2.3572 0.00 # REPAIRED: Close Adj Close Dividends 2024-06-27 00:00:0001:00 2.360 2.3600 0.0178 2024-06-26 00:00:0001:00 2.375 2.3572 0.0000股息与调整都太大LTI.L# ORIGINAL: Close Adj Close Adj Dividends 2024-08-08 00:00:0001:00 768.0 768.0 1.0000 5150.0 2024-08-07 00:00:0001:00 819.0 -4331.0 -5.2882 0.0 # REPAIRED: Close Adj Close Adj Dividends 2024-08-08 00:00:0001:00 768.0 768.0 1.0000 51.5 2024-08-07 00:00:0001:00 819.0 767.5 0.9371 0.0股息太小BVT.L# ORIGINAL: Close Adj Close Adj Dividends 2022-02-03 00:00:0000:00 0.7534 0.675197 0.8962 0.00001 2022-02-01 00:00:0000:00 0.7844 0.702970 0.8962 0.00000 # REPAIRED: Close Adj Close Adj Dividends 2022-02-03 00:00:0000:00 0.7534 0.675197 0.8962 0.001 2022-02-01 00:00:0000:00 0.7844 0.702075 0.8950 0.000前一日被多调整一次2020.OL线索Close Low# ORIGINAL: Low Close Adj Close Dividends 2023-12-21 00:00:0001:00 120.199997 121.099998 118.868782 0.18 2023-12-20 00:00:0001:00 122.000000 121.900002 119.477371 0.00 # REPAIRED: Low Close Adj Close Dividends 2023-12-21 00:00:0001:00 120.199997 121.099998 118.868782 0.18 2023-12-20 00:00:0001:00 122.000000 122.080002 119.654045 0.00除息日错误TETY.ST——价格跌幅出现在 6-20 与 6-17 之间而分红记录在 6-20修复将分红移动到正确的除息日# ORIGINAL: Close Adj Close Dividends 2022-06-22 00:00:0002:00 66.699997 60.085415 0.0 2022-06-21 00:00:0002:00 71.599998 64.499489 0.0 2022-06-20 00:00:0002:00 71.800003 64.679657 5.0 2022-06-17 00:00:0002:00 71.000000 59.454838 0.0 # REPAIRED: Close Adj Close Dividends 2022-06-22 00:00:0002:00 66.699997 60.085415 5.0 2022-06-21 00:00:0002:00 71.599998 60.007881 0.0 2022-06-20 00:00:0002:00 71.800003 60.175503 0.0 2022-06-17 00:00:0002:00 71.000000 59.505021 0.0资本利得被重复计算DODFX线索价格跌幅与股息更匹配而与股息资本利得之和匹配不上# ORIGINAL: Close Adj Close Dividends Capital Gains Date 2025-12-18 00:00:00-05:00 16.219999 16.219999 0.837 0.417 2025-12-17 00:00:00-05:00 16.920000 15.665999 0.000 0.000 # REPAIRED: Close Adj Close Dividends Capital Gains Date 2025-12-18 00:00:00-05:00 16.219999 16.219999 0.42 0.417 2025-12-17 00:00:00-05:00 16.920000 16.083000 0.00 0.000七、附录进阶主题速查与源码索引主题关联文档核心源码/测试一句话要点安装doc/source/advanced/install.rstpyproject.toml、requirements.txt无curl_cffi环境的降级安装配置doc/source/advanced/config.rstyfinance/config.pyyf.config统一管理 proxy / retries / debug / locale日志doc/source/advanced/logging.rstyfinance/utils.py默认仅 ERROR调试时开启debug.logging缓存doc/source/advanced/caching.rstyfinance/cache.pySQLite 持久化时区/Cookie/ISIN可迁移目录多级列doc/source/advanced/multi_level_columns.rstyf.download返回结构多 ticker 数据为 ticker×字段两层列索引价格修复doc/source/advanced/price_repair.rstyfinance/scrapers/history.py、tests/datarepairTrue修复价格/分红/拆分/货币错误进阶文档的整体结构即 doc/source/advanced/index.rst 的 toctree与本节一一对应。建议读者在读完本文后按需深入对应源码文件配置读写看 yfinance/config.py缓存机制看 yfinance/cache.py价格修复的完整判定与重建逻辑看 yfinance/scrapers/history.py 中_fix_unit_mixups、_reconstruct_intervals_batch、_repair_capital_gains等实现回归测试与样本数据则集中在 tests 目录。这样既能理解每个参数的行为边界也能在遇到异常数据时快速定位修复路径。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
