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

yfinance API Reference 全指南从 Ticker、download 到 WebSocket 的公开接口详解【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance本篇技术指南以 yfinance 官方文档中的API Referencedoc/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 一节列出的全部内容公开 API类型职责yf.Ticker类访问单只股票/基金/ETF 的完整数据yf.Tickers类批量管理多个 Ticker 对象yf.Market/yf.MarketRegion类访问市场摘要与开闭市状态yf.Calendars类访问日历事件财报、除息日等yf.download函数一次下载多个 ticker 的历史行情yf.Search类访问 Yahoo 搜索建议结果yf.Lookup类按名称/关键词查找 tickeryf.WebSocket类同步流式获取实时行情yf.AsyncWebSocket类异步流式获取实时行情yf.Sector/yf.Industry域类访问行业与板块数据yf.EquityQuery/yf.FundQuery/yf.ETFQuery类构建股票/基金/ETF 筛选查询yf.screen函数执行筛选查询并返回结果yf.Auth类处理 Yahoo Finance 认证Cookie/CRUMByf.config.debug.logging配置项开启详细调试日志yf.set_tz_cache_location函数设置时区缓存目录此外还有PREDEFINED_SCREENER_QUERIES预置筛选查询与enable_debug_mode已弃用见下文等。文档将其划分为四个子参考页面Ticker 与 Tickers、Stock 方法、Functions and Utilities以及 Market、WebSocket 等专项模块。二、核心入口Ticker 与 Tickers2.1 Ticker单标的的 Pythonic 访问Ticker模块允许你以 Pythonic 的方式访问单个 ticker 的全部数据。参考文档 yfinance.ticker_tickers.rst 给出了最小示例见 examples/ticker.pyimport yfinance as yf dat yf.Ticker(MSFT) # 获取历史行情 dat.history(period1mo) # 期权链取第一个到期日的 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, sessionNone)——ticker为标的代码session可选用于传入自定义请求会话。其__repr__输出yfinance.Ticker object MSFT便于调试。值得注意的调用约定history()返回历史行情 DataFrameoption_chain(date)返回包含calls/puts的期权链对象可先用dat.options获取到期日列表live()则返回一个实时数据流对象。对于 ETF/共同基金Ticker.funds_data提供了基金专属数据入口详见下文 2.3。2.2 Tickers批量管理多个标的当需要同时处理多个标的时使用Tickers模块examples/tickers.pyimport yfinance as yf tickers yf.Tickers(msft aapl goog) # 通过 tickers 字典按代码访问大写键 tickers.tickers[MSFT].info tickers.tickers[AAPL].history(period1mo) tickers.tickers[GOOG].actions # 批量实时流 tickers.live()Tickers接受以空格分隔的代码字符串内部会按代码构建Ticker对象字典并自动对代码做大小写规范化。需要说明的是如果在意批量下载的效率多线程应优先使用下一节的yf.downloadTickers更适合逐个访问不同标的不同维度的数据。2.3 FundsDataETF 与基金的持仓数据文档特别指出对于 ETF/共同基金Ticker.funds_data提供基金专属数据且 Top Holdings、行业权重等带类别平均对比的数据以pd.DataFrame返回。示例见 examples/funds_data.pyimport 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.pyimport yfinance as yf data yf.download(SPY AAPL, period1mo)其完整签名定义于 yfinance/multi.py参数语义如下与官方 docstring 一致参数默认值说明tickers—代码字符串或列表如SPY AAPL或[SPY, AAPL]period1mo合法值1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max与start/end二选一interval1d合法值1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo日内数据最长只能回溯 60 天start/end99 年前 / 现在起始日含inclusive结束日不含exclusive如start2020-01-01首条数据即为该日group_bycolumn结果按ticker或column分组prepostFalse是否包含盘前盘后数据auto_adjustTrue是否自动调整 OHLC 价格复权back_adjustFalse是否再做后复权repairFalse检测并尝试修复货币单位 100 倍错位见 doc/source/advanced/price_repair.rstkeepnaFalse是否保留 Yahoo 返回的 NaN 行actionsFalse是否同时下载股息 拆股数据threadsTrue批量下载的线程数True表示按需启用多线程ignore_tz依 interval合并不同时区数据时是否忽略时区日内默认False日线及以上默认True。同时控制返回索引True时索引为 tz-naiveFalse时转换为请求标的中最常见的交易所时区roundingFalse是否将数值四舍五入到 2 位小数timeout10请求超时秒数可为小数如0.01sessionNone传入自定义 Session 复用于所有请求multi_level_indexTrue是否始终返回 MultiIndex DataFrame从实现看每次调用download()都会创建独立的_DownloadCtx上下文yfinance/multi.py内部用multitasking并发拉取各 ticker 后合并因此多个并发调用之间不会发生共享状态污染当threadsFalse时则退化为串行。四、Stock 方法Ticker 的行情与基本面接口参考页 yfinance.stock.rst 专门列出了Ticker上与股票数据直接相关的方法通过 autosummary 自动生成 API 文档可归纳为几类历史行情类history/get_history_metadata历史行情与元数据如交易所时区、首尾交易日底层由 yfinance/scrapers/history.py 的PriceHistory实现文档通过seealso指引到该 scraper 及价格修复专题 doc/source/advanced/price_repair.rstget_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/isinISIN 代码。代理服务器支持如果你的网络环境需要代理参考文档给出了逐一传递proxy参数的示例examples/proxy.pyimport yfinance as yf msft yf.Ticker(MSFT) msft.history(..., proxyPROXY_SERVER) msft.get_actions(proxyPROXY_SERVER) msft.get_dividends(proxyPROXY_SERVER) msft.get_splits(proxyPROXY_SERVER) msft.get_capital_gains(proxyPROXY_SERVER) msft.get_balance_sheet(proxyPROXY_SERVER) msft.get_cashflow(proxyPROXY_SERVER) msft.option_chain(..., proxyPROXY_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.pyimport yfinance as yf EUROPE yf.Market(EUROPE) status EUROPE.status # 开闭市状态 summary EUROPE.summary # 市场摘要Yahoo Finance 中共有 8 个市场US、GB股票市场ASIA、EUROPE区域市场RATES、COMMODITIES、CURRENCIES、CRYPTOCURRENCIES利率、大宗商品、外汇、加密货币文档特别给出了两点使用提示只有Market.summary会为上述所有市场返回区域数据Market.status由 Yahoo 的markettime端点支撑该端点目前忽略market参数、只返回美国数据——因此对任何非US市场status都会返回None并记录一条警告日志使用时应做好空值处理。六、WebSocket实时行情流WebSocket模块提供同步与异步两种客户端来订阅 Yahoo Finance 的实时价格更新参考 yfinance.websocket.rstyf.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、Lookup7.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 与 Lookupyf.Search访问 Yahoo 搜索建议结果返回与关键词匹配的标的列表含代码、类型、交易所等yf.Lookup按名称/关键词查找 ticker实现位于 yfinance/lookup.py。两者常用于用户输入自然语言或非标准代码 → 解析出标准 ticker的前置环节。八、域模型Sector 与 Industryyf.Sector与yf.Industry是域domain层面的类分别用于访问板块与行业数据实现位于 yfinance/domain/sector.py 与 yfinance/domain/industry.py共享 yfinance/domain/domain.py 的基础逻辑。它们可将一只股票映射到所属板块/行业并获取该板块/行业的成员与概况数据是行业轮动、板块跟踪类策略的常用入口。九、认证、调试与缓存Auth、config 与 set_tz_cache_location9.1 AuthYahoo 认证Cookie / CRUMB部分 Yahoo 接口尤其高频率访问需要有效的 Cookie 与 CRUMB 令牌。yf.Auth类用于获取并维护这些凭据实现位于 yfinance/data.py。可实例化后传入Ticker/download的session以规避访问被限流的问题。9.2 调试日志config.debug.logging文档给出的现代调试开关是配置项yf.config.debug.loggingimport 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_locationyfinance/cache.py会一次性重定向三类缓存的存放目录时区缓存_TzDBManagerCookie 缓存_CookieDBManagerISIN 缓存_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! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考