yfinance Financials 财务报表与业绩数据 API 完全指南Ticker 三大报表、盈余日历与 SEC 备案详解【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance本篇技术指南围绕 yfinance 仓库中 yfinance.financials.rst 所定义的Ticker财务数据接口展开系统讲解利润表、资产负债表、现金流量表、盈余数据、盈余日历与 SEC 备案六大类 API 的方法/属性双形态用法、参数语义、底层数据流水线与缓存机制。读完本文你将能够熟练通过yf.Ticker拉取标准化的年度/季度/TTM 财务报表掌握pretty、as_dict、freq、limit等关键参数的精确行为并理解这些接口背后的 Yahoo 财报时序数据通道及其边界限制。一、接口全景方法Method与属性Property的双形态设计yfinance 的财务数据 API 全部挂在yfinance.Ticker对象上文档将其归类为 Financials 模块。其核心设计是一套「方法为底层实现、属性为便捷封装」的双形态结构方法形态如get_income_stmt()允许传入as_dict、pretty、freq等参数灵活控制输出属性形态如income_stmt无参数访问内部固定使用prettyTrue直接返回格式化好的pd.DataFrame或dict。属性的实现定义在 yfinance/ticker.py 中例如income_stmt属性就是get_income_stmt(prettyTrue)的别名yfinance/ticker.py。方法本体集中在 yfinance/base.py 的TickerBase中。完整接口清单如下与 yfinance.financials.rst 的 autosummary 一一对应类别方法属性利润表get_income_stmt()income_stmt/quarterly_income_stmt/ttm_income_stmt资产负债表get_balance_sheet()balance_sheet现金流量表get_cashflow()cashflow/quarterly_cashflow/ttm_cashflow盈余摘要get_earnings()earnings盈余日历get_earnings_dates()earnings_dates事件日历get_calendar()calendarSEC 备案get_sec_filings()sec_filings从源码结构看属性形态还保留了一批历史兼容别名如incomestmt、financials、balancesheet、cash_flow等它们与主属性返回完全一致的数据见 yfinance/ticker.py。二、三大财务报表利润表、资产负债表与现金流量表三大报表是 Financials 模块的核心三者的方法签名高度一致均接受as_dict、pretty、freq三个参数返回以报告日期为列、以科目为行的pd.DataFrame。2.1 通用参数语义以利润表为例yfinance/base.py 中get_income_stmt()的参数定义如下参数类型默认值说明as_dictboolFalse为True时将DataFrame转为 Pythondict返回prettyboolFalse为True时将驼峰命名的行索引格式化为人读的标题如TotalRevenue→Total Revenuefreqstryearly报告频率yearly年度、quarterly季度、trailing近 12 个月TTMpretty的格式化底层调用utils.camel2title()利润表对EBIT、EBITDA、EPS、NI等缩写做了保留处理yfinance/base.py资产负债表则对PPE做了缩写保护yfinance/base.py。典型用法import yfinance as yf t yf.Ticker(AAPL) # 年度利润表方法形态原始驼峰行名 raw t.get_income_stmt(prettyFalse, freqyearly) print(raw.head()) # 季度利润表属性形态自动 pretty q t.quarterly_income_stmt print(q) # TTM 利润表 ttm t.ttm_income_stmt # 转为 dict便于 JSON 序列化 d t.get_income_stmt(as_dictTrue)2.2freq参数的三档语义与约束差异虽然三个freq取值在三个方法中外观一致但底层校验并不完全相同。核心校验逻辑位于 yfinance/scrapers/fundamentals.py 的_fetch_time_series()合法freq仅为yearly、quarterly、trailing三者否则抛出ValueErrortrailingTTM仅对利润表和现金流量表开放若对资产负债表传入freqtrailing会直接抛错frequency trailing only available for cash-flow or income data。因此ttm_income_stmt、ttm_cashflow存在但不存在ttm_balance_sheet。此外TTM 数据在底层还有一个特殊行为时序接口只返回最近一列数据。在 yfinance/scrapers/fundamentals.py 中可以看到if (timescale trailing): df df.iloc[:, [0]]即 TTM 结果永远只有「最近 12 个月」这一列。2.3 各报表的典型输出内容仓库测试 tests/test_ticker.py 对各报表的返回内容做了明确断言可作为字段预期利润表至少包含Total Revenue总营收与Basic EPS基本每股收益两行年度数据相邻两列间隔约 365 天tests/test_ticker.py资产负债表至少包含Total Assets总资产与Net PPE净固定资产两行tests/test_ticker.py所有报表的列按报告日期降序排列最新报告期在最左列行顺序与 Yahoo 官网展示顺序一致yfinance/scrapers/fundamentals.py。可复制的验证代码import yfinance as yf t yf.Ticker(MSFT) assert Total Revenue in t.income_stmt.index assert Basic EPS in t.income_stmt.index assert Total Assets in t.balance_sheet.index assert Net PPE in t.balance_sheet.index # 年度与季度数据的时间间隔天 import pandas as pd annual_period abs((t.income_stmt.columns[0] - t.income_stmt.columns[1]).days) assert abs(annual_period - 365) 20三、盈余数据earnings与earnings_dates3.1get_earnings()盈余摘要已标记废弃get_earnings(as_dictFalse, freqyearly)返回freq为yearly、quarterly或trailing的盈余表yfinance/base.py。需要特别提示该接口在底层已不可用——yfinance/scrapers/fundamentals.py 中的earnings属性会直接发出DeprecationWarning并返回None警告文案明确建议改用Ticker.income_stmt中的Net Income净利润行。因此在新代码中应避免使用earnings/get_earnings()改用利润表数据。3.2get_earnings_dates()盈余公告日期与预期/实际 EPSget_earnings_dates(limit12, offset0)是盈余日历的核心接口返回以盈余公告日期为索引、含EPS Estimate预期 EPS、Reported EPS实际 EPS、Surprise(%)超预期幅度三列的DataFrameyfinance/base.py。参数行为参数默认值约束与语义limit12请求的盈余公告行数上限 100超过会抛出ValueError(Yahoo caps limit at 100)。默认 12 大致对应未来 4 个季度 历史 8 个季度offset0搜索偏移0从未来 EPS 预期开始1从最近一次实际 EPS 开始x从第 x 次历史 EPS 开始结果会按limit做内存缓存self._earnings_dates[limit] df重复以相同limit调用不会重复请求网络yfinance/base.py。其数据来源值得说明。实现上存在两条通道HTML 爬取当前默认_get_earnings_dates_using_scrape()请求https://finance.yahoo.com/calendar/earnings?symbol{ticker}offset{offset}size{size}用 BeautifulSoup 解析页面table再经pd.read_html()转表并将EDT/EST时区转换为America/New_Yorkyfinance/base.py。size会根据limit自动取 25 / 50 / 100 三档。Screener API已停用_get_earnings_dates_using_screener()使用v1/finance/visualization接口。源码注释明确记录2025 年夏季 Yahoo 停止更新该端点的数据因此实现已回退到 HTML 爬取yfinance/base.py。仓库测试覆盖了earnings_dates的基本返回与limit100场景tests/test_ticker.py。实际返回格式示例来源为源码 docstringEPS Estimate Reported EPS Surprise(%) Date 2025-10-30 2.97 - - 2025-07-22 1.73 1.54 -10.88 2025-05-06 2.63 2.7 2.57四、calendar事件、盈余预期与股息日期get_calendar()返回一个dict包含近期公司事件与盈余预估区间yfinance/base.py。底层实现位于 yfinance/scrapers/quote.py 的_fetch_calendar()通过拉取 Yahoo 的calendarEvents模块构建字典常见键如下键类型含义Dividend Datedatetime.date股息发放日Ex-Dividend Datedatetime.date除息日Earnings Datelist[datetime.date]预计盈余公告日期列表Earnings High/Earnings Low/Earnings Average数值分析师盈余预期的高值 / 低值 / 均值Revenue High/Revenue Low/Revenue Average数值分析师营收预期的高值 / 低值 / 均值测试 tests/test_ticker.py 断言该 dict 至少包含Earnings Date、Earnings Average、Earnings Low、Earnings High四个键且验证了结果会被缓存连续两次t.calendar返回同一对象。import yfinance as yf t yf.Ticker(AAPL) cal t.calendar # 等价于 t.get_calendar() print(cal[Earnings Date]) print(cal[Earnings Average], cal[Earnings Low], cal[Earnings High])五、sec_filingsSEC 备案文件检索get_sec_filings()返回公司向美国 SEC 提交的备案文件列表yfinance/base.py。底层_fetch_sec_filings()yfinance/scrapers/quote.py拉取 Yahoo 的secFilings模块并对原始结构做两处规整每条备案的exhibits附件被转换为{类型: 链接}的字典如{EX-10.1: https://...}备案date从%Y-%m-%d字符串解析为datetime.date对象。返回的每条记录通常包含备案类型如 10-K 年报、10-Q 季报、8-K 重大事件公告、提交日期、附件链接等字段。适合用于构建「该公司最近申报了哪些文件」的监控清单import yfinance as yf t yf.Ticker(NVDA) for filing in t.sec_filings: # 等价于 t.get_sec_filings() print(filing.get(date), filing.get(type)) # exhibits 为 {类型: url} 字典 print(filing.get(exhibits))六、底层数据通道财报时序 API 与工程细节理解上述接口的底层实现有助于判断数据边界与异常场景。三大报表最终都汇聚到yfinance/scrapers/fundamentals.py的Financials类6.1 数据来源与时序端点数据来自 Yahoo 的fundamentals-timeseries时序端点/ws/fundamentals-timeseries/v1/finance/timeseries/{symbol}yfinance 明确注释选择该通道是因为它返回的数据与 Yahoo 官网展示一致优于刮取QuoteSummaryStoreyfinance/scrapers/fundamentals.py请求的科目键如TotalRevenue、NetIncome、TotalAssets集中定义在 yfinance/const.py 的fundamentals_keys中分为financials利润表、balance-sheet、cash-flow三组其中利润表在 Yahoo 内部存储键为financials需要做一次键名映射yfinance/scrapers/fundamentals.py时间范围限制无论period1如何设置Yahoo 最多返回 4 个年度或 5 个季度的数据start_dt固定为 2016-12-31yfinance/scrapers/fundamentals.pyyearly在请求层被翻译为annual前缀annualTotalRevenue等quarterly与trailing保持原样yfinance/scrapers/fundamentals.py。6.2 结果缓存Financials类为每个freq维护独立的缓存字典_income_time_series、_balance_sheet_time_series、_cash_flow_time_series同一次会话内重复访问同一频率不会重复发起网络请求yfinance/scrapers/fundamentals.py。6.3 分块请求回退机制WSL2 / 受限代理适配这是一个值得关注的工程细节拼接全部科目键的单条 URL 可能超过约 2KB在 WSL2 的 NAT 或受限代理环境下会被静默丢弃。因此实现做了两层处理定义_CHUNK_KEYS 60即每个分块最多 60 个科目键yfinance/scrapers/fundamentals.py默认先尝试单条长 URL快速路径失败后自动切换为分块请求并通过YfData.fundamentals_use_chunked标志粘性记住该失败状态避免在遍历多个 ticker 时每个都浪费一次超时若分块也失败则回滚标志并重新抛出yfinance/scrapers/fundamentals.py。仓库测试专门覆盖了该回退场景如 tests/test_ticker.py 的test_balance_sheet_chunked_fallback_on_timeout与test_cash_flow_chunked_fallback_on_timeout。6.4 异常处理策略_fetch_time_series()捕获到建表异常时默认通过YfConfig.debug.hide_exceptions决定是否抛出开启调试隐藏后仅记录错误日志并返回空DataFrameyfinance/scrapers/fundamentals.py。也就是说某些 ticker 财报数据不可得时接口可能静默返回空表调用方应自行判空。七、最佳实践与注意事项汇总综合源码与测试使用 Financials 系列接口时建议遵循以下要点优先使用属性形态income_stmt、balance_sheet、cashflow、calendar、earnings_dates、sec_filings无需记忆参数且内部已做prettyTrue格式化与结果缓存。TTM 仅限利润表与现金流量表需要近 12 个月数据用ttm_income_stmt/ttm_cashflow且注意 TTM 表只有最新一列。远离earnings该接口已废弃并固定返回None净利润请从income_stmt的Net Income行读取。get_earnings_dates的limit不要超过 100否则直接抛ValueErroroffset语义从 0 开始未来预期起。注意静默空表财报时序通道对部分 ticker 可能返回空YfConfig.debug.hide_exceptions开启时异常被吞掉建议对返回结果做df.empty判空。理解数据边界年度最多 4 年、季度最多 5 期且起始时间不早于 2016 年底需要更长历史请配合Ticker.history()或download()等其他数据通道。calendar与earnings_dates语义不同calendar给出单只股票未来事件与分析师预期区间dictearnings_dates给出逐期盈余公告日期与预期/实际 EPS 对比DataFrame按需选用。八、扩展阅读doc/source/reference/yfinance.financials.rst本文所依据的 API Reference 原始页面doc/source/reference/index.rstyfinance 全部公开 API 索引Ticker与download等入口一览yfinance/base.py三大报表与盈余方法的具体实现yfinance/ticker.py属性形态的封装与历史别名yfinance/scrapers/fundamentals.py财报时序数据抓取、分块回退与缓存yfinance/scrapers/quote.pycalendar与sec_filings的数据来源yfinance/const.py财报科目键fundamentals_keys完整清单tests/test_ticker.py各接口的字段与行为断言可作为使用预期参考。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考