企业官网建设流程全解析

yfinance API Reference 全指南：从 Ticker、download 到 WebSocket 的公开接口详解

【免费下载链接】yfinanceDownload market data from Yahoo! Finance's API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance

本篇技术指南以 yfinance 官方文档中的API Reference（doc/source/reference/index.rst）为核心骨架，系统梳理该库对外暴露的全部公开类、函数与配置项，覆盖行情历史下载、个股信息、市场摘要、日历事件、实时流、筛选器、认证与缓存等完整能力。读完本文，你将掌握yf.Ticker、yf.download、yf.Market、yf.WebSocket、yf.EquityQuery等核心 API 的调用方式、参数语义与底层实现，可直接在自己的量化脚本或数据服务中按需组合使用。

一、yfinance 公开 API 总览

yfinance 是一个封装 Yahoo! Finance API 的 Python 库，用于便捷地获取市场数据。从 yfinance/init.py 可以看到，包顶层统一导出了以下公开对象（__all__列表），这也是文档中 "Public API" 一节列出的全部内容：

此外还有PREDEFINED_SCREENER_QUERIES（预置筛选查询）与enable_debug_mode（已弃用，见下文）等。文档将其划分为四个子参考页面：Ticker 与 Tickers、Stock 方法、Functions and Utilities，以及 Market、WebSocket 等专项模块。

二、核心入口：Ticker 与 Tickers

2.1 Ticker：单标的的 Pythonic 访问

Ticker模块允许你以 Pythonic 的方式访问单个 ticker 的全部数据。参考文档 yfinance.ticker_tickers.rst 给出了最小示例（见 examples/ticker.py）：

import yfinance as yf dat = yf.Ticker("MSFT") # 获取历史行情 dat.history(period='1mo') # 期权链：取第一个到期日的 calls dat.option_chain(dat.options[0]).calls # 财务报表 dat.balance_sheet dat.quarterly_income_stmt # 日历（财报、除息等） dat.calendar # 综合信息 dat.info # 分析师目标价 dat.analyst_price_targets # 实时数据流 dat.live()

从源码看，yf.Ticker定义在 yfinance/ticker.py，继承自yfinance.base.TickerBase，构造函数签名Ticker(ticker, session=None)——ticker为标的代码，session可选，用于传入自定义请求会话。其__repr__输出yfinance.Ticker object <MSFT>便于调试。

值得注意的调用约定：history()返回历史行情 DataFrame；option_chain(date)返回包含calls/puts的期权链对象，可先用dat.options获取到期日列表；live()则返回一个实时数据流对象。对于 ETF/共同基金，Ticker.funds_data提供了基金专属数据入口（详见下文 2.3）。

2.2 Tickers：批量管理多个标的

当需要同时处理多个标的时，使用Tickers模块（examples/tickers.py）：

import yfinance as yf tickers = yf.Tickers('msft aapl goog') # 通过 tickers 字典按代码访问（大写键） tickers.tickers['MSFT'].info tickers.tickers['AAPL'].history(period="1mo") tickers.tickers['GOOG'].actions # 批量实时流 tickers.live()

Tickers接受以空格分隔的代码字符串，内部会按代码构建Ticker对象字典，并自动对代码做大小写规范化。需要说明的是：如果在意批量下载的效率（多线程），应优先使用下一节的yf.download，Tickers更适合逐个访问不同标的不同维度的数据。

2.3 FundsData：ETF 与基金的持仓数据

文档特别指出：对于 ETF/共同基金，Ticker.funds_data提供基金专属数据，且 Top Holdings、行业权重等"带类别平均对比"的数据以pd.DataFrame返回。示例见 examples/funds_data.py：

import yfinance as yf spy = yf.Ticker('SPY') data = spy.funds_data # 基金描述 data.description # 运营信息 data.fund_overview data.fund_operations # 持仓相关信息 data.asset_classes data.top_holdings data.equity_holdings data.bond_holdings data.bond_ratings data.sector_weightings

该实现位于 yfinance/scrapers/funds.py，是Ticker在__init__中实例化的FundsData对象，负责向 Yahoo 的基金数据端点发起请求并解析为 DataFrame。

三、批量下载：yf.download 全参数详解

download函数允许一次请求多个 ticker 的历史行情，是数据获取的入口级工具（参考文档 yfinance.functions.rst 与示例 examples/download.py）：

import yfinance as yf data = yf.download("SPY AAPL", period="1mo")

其完整签名定义于 yfinance/multi.py，参数语义如下（与官方 docstring 一致）：

从实现看，每次调用download()都会创建独立的_DownloadCtx上下文（yfinance/multi.py），内部用multitasking并发拉取各 ticker 后合并，因此多个并发调用之间不会发生共享状态污染；当threads=False时则退化为串行。

四、Stock 方法：Ticker 的行情与基本面接口

参考页 yfinance.stock.rst 专门列出了Ticker上与"股票数据"直接相关的方法（通过 autosummary 自动生成 API 文档），可归纳为几类：

历史行情类：

• history/get_history_metadata：历史行情与元数据（如交易所时区、首尾交易日），底层由 yfinance/scrapers/history.py 的PriceHistory实现，文档通过seealso指引到该 scraper 及价格修复专题 doc/source/advanced/price_repair.rst；
• get_dividends/dividends、get_splits/splits、get_actions/actions、get_capital_gains/capital_gains：股息、拆股、公司行为、资本利得数据（get_*前缀为显式拉取方法，无前缀属性走缓存）；
• get_shares_full：完整股本历史。

信息类：

• get_info/info：综合基本面信息（市值、PE、行业等）；
• get_fast_info/fast_info：轻量快速信息接口，只请求少量字段，速度明显更快；
• get_news/news：相关新闻；
• get_isin/isin：ISIN 代码。

代理服务器支持

如果你的网络环境需要代理，参考文档给出了逐一传递proxy参数的示例（examples/proxy.py）：

import yfinance as yf msft = yf.Ticker("MSFT") msft.history(..., proxy="PROXY_SERVER") msft.get_actions(proxy="PROXY_SERVER") msft.get_dividends(proxy="PROXY_SERVER") msft.get_splits(proxy="PROXY_SERVER") msft.get_capital_gains(proxy="PROXY_SERVER") msft.get_balance_sheet(proxy="PROXY_SERVER") msft.get_cashflow(proxy="PROXY_SERVER") msft.option_chain(..., proxy="PROXY_SERVER")

现代版本更推荐通过全局配置设置代理：yf.config.network.proxy = "PROXY_SERVER"。旧版顶层函数yf.set_config(proxy=..., retries=...)已标记DeprecationWarning，提示改用新的 config 控制（见 yfinance/init.py）。

五、Market：市场摘要与开闭市状态

Market类用于以 Pythonic 方式访问市场数据（参考 yfinance.market.rst 与 examples/market.py）：

import yfinance as yf EUROPE = yf.Market("EUROPE") status = EUROPE.status # 开闭市状态 summary = EUROPE.summary # 市场摘要

Yahoo Finance 中共有 8 个市场：

• US、GB（股票市场）
• ASIA、EUROPE（区域市场）
• RATES、COMMODITIES、CURRENCIES、CRYPTOCURRENCIES（利率、大宗商品、外汇、加密货币）

文档特别给出了两点使用提示：

1. 只有Market.summary会为上述所有市场返回区域数据；
2. Market.status由 Yahoo 的markettime端点支撑，该端点目前忽略market参数、只返回美国数据——因此对任何非US市场，status都会返回None并记录一条警告日志，使用时应做好空值处理。

六、WebSocket：实时行情流

WebSocket模块提供同步与异步两种客户端来订阅 Yahoo Finance 的实时价格更新（参考 yfinance.websocket.rst）：

• yf.WebSocket：同步接口；
• yf.AsyncWebSocket：异步接口，需在asyncio事件循环中使用。

两个类的示例分别见 examples/live_sync.py 与 examples/live_async.py。同步用法形如：

import yfinance as yf ws = yf.WebSocket() ws.start() # 启动连接 ws.subscribe("MSFT") # 订阅标的 # 在回调中处理推送的行情消息

异步用法的订阅流程一致，但需运行在事件循环中。文档给出了一条重要实战提示：在 Jupyter Notebook 中运行异步代码可能遇到事件循环冲突，需先安装并应用nest_asyncio允许嵌套事件循环：

import nest_asyncio nest_asyncio.apply()

再执行异步操作即可。同步/异步实现分别位于 yfinance/live.py 中，底层基于 Yahoo 的 quote stream 端点，Ticker.live()与Tickers.live()是它的便捷入口。

七、筛选器与搜索：Screener、Search、Lookup

7.1 EquityQuery / FundQuery / ETFQuery 与 screen

文档公开了三个查询构建类与一个执行函数：

• yf.EquityQuery：构建股票筛选条件（如市值、PE、派息率等）；
• yf.FundQuery：构建基金筛选条件；
• yf.ETFQuery：构建 ETF 筛选条件；
• yf.screen(...)：执行查询并返回结果。

底层实现在 yfinance/screener/query.py 与 yfinance/screener/screener.py，后者同时导出了PREDEFINED_SCREENER_QUERIES预置查询集。典型用法是先用 Query 类组合过滤条件，再传给screen获取符合条件标的列表。

7.2 Search 与 Lookup

• yf.Search：访问 Yahoo 搜索建议结果，返回与关键词匹配的标的列表（含代码、类型、交易所等）；
• yf.Lookup：按名称/关键词查找 ticker，实现位于 yfinance/lookup.py。

两者常用于"用户输入自然语言或非标准代码 → 解析出标准 ticker"的前置环节。

八、域模型：Sector 与 Industry

yf.Sector与yf.Industry是域（domain）层面的类，分别用于访问板块与行业数据，实现位于 yfinance/domain/sector.py 与 yfinance/domain/industry.py，共享 yfinance/domain/domain.py 的基础逻辑。它们可将一只股票映射到所属板块/行业，并获取该板块/行业的成员与概况数据，是行业轮动、板块跟踪类策略的常用入口。

九、认证、调试与缓存：Auth、config 与 set_tz_cache_location

9.1 Auth：Yahoo 认证（Cookie / CRUMB）

部分 Yahoo 接口（尤其高频率访问）需要有效的 Cookie 与 CRUMB 令牌。yf.Auth类用于获取并维护这些凭据，实现位于 yfinance/data.py。可实例化后传入Ticker/download的session，以规避访问被限流的问题。

9.2 调试日志：config.debug.logging

文档给出的现代调试开关是配置项yf.config.debug.logging：

import yfinance as yf yf.config.debug.logging = True # 开启 verbose 调试日志

其背后的配置管理器YfConfig实现于 yfinance/config.py：采用惰性初始化，首次访问时写入默认值——network.proxy = None、network.retries = 0、debug.hide_exceptions = True、debug.logging = False、locale.lang = "en-US"、locale.region = "US"。因此你还可以：

yf.config.network.proxy = "http://your-proxy:port" yf.config.network.retries = 3 yf.config.debug.hide_exceptions = False

与之对应的旧式函数yf.enable_debug_mode()已标记弃用，源码（yfinance/utils.py）明确提示"由yf.config.debug.logging = True取代"，新代码请直接使用配置项。

9.3 set_tz_cache_location：设置时区缓存目录

yf.set_tz_cache_location(cache_dir)用于设置时区数据的缓存位置。源码中它等价于set_cache_location（yfinance/cache.py），会一次性重定向三类缓存的存放目录：

• 时区缓存（_TzDBManager）；
• Cookie 缓存（_CookieDBManager）；
• ISIN 缓存（_ISINDBManager）。

默认情况下缓存位于platformdirs.user_cache_dir()下的"py-yfinance"目录；当该默认目录不可写（如受限的服务器环境）时，应在首次发起任何数据请求之前调用此函数指定一个可写路径。

import yfinance as yf yf.set_tz_cache_location("/path/to/writable/cache")

十、参考文档导航

yfinance 官方文档还按模块细分了以下参考页，读者可按需查阅更详细的类与方法签名：

• Ticker 与 Tickers 参考
• Stock 方法参考
• Market 参考
• Calendars 参考
• Financials 参考
• Analysis 参考
• Search 参考
• Lookup 参考
• WebSocket 参考
• Sector / Industry 参考
• Screener 参考
• Auth 参考
• 函数与工具参考
• FundsData 参考
• PriceHistory 参考

结语

yfinance 的公开 API 设计遵循"单一入口 + 模块化能力"的组织方式：Ticker/Tickers覆盖单标的与多标的的深度数据，download面向批量历史行情，Market面向市场级快照，WebSocket面向实时流，Screener / Search / Lookup 面向标的发现，Auth/config/ 缓存函数则解决认证、调参与运行环境问题。组合使用这些接口即可搭建从"标的发现 → 历史回测 → 实时监控"的完整数据链路。

【免费下载链接】yfinanceDownload market data from Yahoo! Finance's API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance