yfinance Market 类实战指南一行代码获取全球市场摘要与交易状态【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance导读yfinance.Market是 yfinance 库中用于以 Pythonic 方式访问 Yahoo Finance 市场级数据的核心类它面向「市场」而非「个股」可让你一次性拉取整个市场区域的行情摘要summary与开闭市状态status。读完本文你将掌握 8 个市场区域的正确用法、Market(US)与Market(EUROPE)的输出差异、summary与status两个属性的数据形态以及markettime端点对非 US 市场的已知限制与规避方式——全部基于当前仓库源码yfinance/domain/market.py与测试用例tests/test_market.py逐行印证。Market 类是什么根据 API 参考文档doc/source/reference/index.rst的定义Market是 yfinance 对外公开的核心类之一专门用于「accessing market summary」。它对应的是 Yahoo Finance 的v6/finance/quote/marketSummary与v6/finance/markettime两个接口返回的不是单只股票的报价而是一个区域内所有主要交易所/市场快照的聚合数据。在 doc/source/reference/yfinance.market.rst 中官方对它的定位描述为TheMarketclass, allows you to access market data in a Pythonic way.也就是说Market是对 Yahoo 底层 REST 端点的封装把「构造 URL、拼参数、发请求、解析 JSON」这一整套过程收敛为两个属性summary、status用户无需关心 HTTP 细节。8 个市场区域MarketRegionYahoo Finance 支持 8 个市场区域文档原文与源码中的MarketRegion枚举完全一致。源码位于 yfinance/domain/market.py市场区域枚举成员说明USMarketRegion.US美国市场GBMarketRegion.GB英国市场ASIAMarketRegion.ASIA亚洲市场EUROPEMarketRegion.EUROPE欧洲市场RATESMarketRegion.RATES利率市场COMMODITIESMarketRegion.COMMODITIES大宗商品市场CURRENCIESMarketRegion.CURRENCIES外汇市场CRYPTOCURRENCIESMarketRegion.CRYPTOCURRENCIES加密货币市场MarketRegion是一个str枚举class MarketRegion(str, Enum)成员本身就是普通字符串因此MarketRegion.EUROPE EUROPE成立Market(EUROPE)这种传字符串的写法也完全兼容。源码注释明确指出传字符串保证向后兼容传枚举成员则能获得 IDE 自动补全与静态类型检查的收益Members are plain strings, soMarketRegion.EUROPE EUROPEandMarket(EUROPE)continues to work. Pass an enum member for IDE autocomplete and static checking:Market(MarketRegion.EUROPE).这一点在测试 tests/test_market.py 中得到了三重验证yf.Market(EUROPE)字符串入参可用yf.Market(yf.MarketRegion.EUROPE)枚举入参可用且m.market是str类型传入非法值如FR会抛出ValueError异常信息中同时包含非法输入与合法的候选列表EUROPE等。快速上手官方示例文档使用literalinclude直接内嵌了官方示例脚本doc/source/reference/examples/market.py全貌如下import yfinance as yf EUROPE yf.Market(EUROPE) status EUROPE.status summary EUROPE.summary三段代码即完成「构造 Market 对象 → 获取交易状态 → 获取市场摘要」的完整闭环。Market与MarketRegion均已从包的顶层导出见 yfinance/init.py无需额外导入子模块。构造参数详解Market.__init__的签名与实现位于 yfinance/domain/market.pydef __init__(self, market, sessionNone, timeout30): try: self.market MarketRegion(market).value except ValueError: valid [m.value for m in MarketRegion] raise ValueError( fUnknown market {market!r}. Valid markets: {valid} ) from None self.session session self.timeout timeout self._data YfData(sessionself.session) self._logger utils.get_yf_logger() self._status None self._summary None三个入参的含义与约束market必填市场区域名称或MarketRegion枚举成员。构造时立即做合法性校验非法值抛出ValueError并列出全部合法取值属于「快速失败」设计——错误在构造阶段暴露而不是等到访问属性时才报错。session可选默认None可传入自定义的requests.Session例如配置了代理、连接池或 Cookie 的会话透传给内部的YfData实例用于所有 HTTP 请求不传则使用默认会话。timeout可选默认 30 秒每次请求的超时秒数透传给YfData.cache_get()的timeout参数。内部缓存_status与_summary初始均为None首次访问对应属性时才触发实际请求惰性加载见下文。summary属性市场摘要summary属性yfinance/domain/market.py访问时触发_parse_data()请求 Yahoo 的marketSummary端点summary_url f{_QUERY1_URL_}/v6/finance/quote/marketSummary summary_fields [shortName, regularMarketPrice, regularMarketChange, regularMarketChangePercent] summary_params { fields: ,.join(summary_fields), formatted: False, lang: en-US, market: self.market }其中_QUERY1_URL_ https://query1.finance.yahoo.com定义于 yfinance/const.py。请求字段固定为 4 个shortName简称、regularMarketPrice最新价、regularMarketChange涨跌额、regularMarketChangePercent涨跌幅。formattedFalse表示返回原始数值而非格式化字符串便于程序处理。响应解析yfinance/domain/market.py的逻辑值得注意self._summary self._summary[marketSummaryResponse][result] self._summary {x[exchange]: x for x in self._summary}返回值是一个以交易所代码为键的字典。例如Market(US).summary的键可能包含SNP标普、NMS纳斯达克等而测试 tests/test_market.py 验证了Market(EUROPE).summary返回的是欧洲区域交易所断言结果中不包含SNP从而证明summary确实按market参数返回了对应区域的数据。解析失败的兜底行为如果响应结构异常例如 Yahoo 返回错误格式在YfConfig.debug.hide_exceptions为默认值True时默认值见 yfinance/config.py会记录 error 级日志并把_summary留空不向调用方抛出异常只有在显式关闭hide_exceptions后才重新抛出原始异常。status属性交易状态含非 US 市场的重大限制status属性yfinance/domain/market.py请求的是 Yahoo 的markettime端点status_url f{_QUERY1_URL_}/v6/finance/markettime status_params { formatted: True, key: finance, lang: en-US, market: self.market }响应解析yfinance/domain/market.py依次完成取出finance.marketTimes[0].marketTime[0]作为状态主体展开timezone取出数组首个元素删除冗余的time字段补充三个派生字段open开盘时间解析为datetime.datetimeclose收盘时间解析为datetime.datetimetz时区对象由gmtoffset毫秒数与short名称构造datetime.timezone。关键警告markettime 端点忽略 market 参数这是本文档中最重要的「已知限制」官方文档以note明确警示OnlyMarket.summaryreturns regional data for all of the values above.Market.statusis backed by Yahoosmarkettimeendpoint, which currently ignores themarketparameter and only returns U.S. data; for any non-USmarket,statuswill therefore beNoneand a warning is logged.翻译并拆解为三点summary是唯一真正支持全部 8 个区域的数据源markettime端点会静默忽略market参数无论你传什么区域它实际都返回美国数据因此对任何非US市场status将返回None并记录一条 warning 日志。这一行为在源码中有对应的主动检测逻辑yfinance/domain/market.py当请求的非 US 市场返回的状态id us时说明端点无视了market参数库会打印形如EUROPE: Yahoo markettime endpoint does not support marketEUROPE; status data unavailable.的警告并把_status置为None避免调用方把「美国数据」误当成「区域数据」使用。测试 tests/test_market.py 将上述行为固化为契约Market(US).status非空且status.get(id) usMarket(EUROPE).status is None。实战建议如果你需要欧洲、亚洲等区域的盘中交易状态目前不能依赖status应当改用summary中各家交易所的regularMarketPrice等字段自行判断status仅在Market(US)场景下可用。惰性加载与双请求同时获取status与summary共享同一个_parse_data()yfinance/domain/market.py并且源码特意保证了「两个端点同时请求」# Fetch both to ensure they are at the same time if (self._status is not None) and (self._summary is not None): return这带来两个好处数据一致性marketSummary与markettime在同一时间点抓取避免两次请求间隔导致的快照偏差结果缓存_status与_summary一旦解析完成即被缓存后续访问属性直接命中缓存不再重复发请求。注意由于缓存是实例级的不同时刻需要刷新数据时应重新构造Market对象。底层调用链与 HTTP 错误处理Market的所有请求最终都经由YfData.cache_get()见 yfinance/domain/market.py。该方法定义于 yfinance/data.py带有两层装饰器lru_cache_freezeargs lru_cache(maxsizecache_maxsize) def cache_get(self, url, paramsNone, timeout30): return self.get(url, params, timeout)cache_get基于lru_cache实现了 URL参数的请求级缓存同一url, params组合在缓存有效期内不会重复发起网络请求——这既是Market惰性加载的底层支撑也意味着相同请求在多个 Market 实例间可能共享缓存lru_cache作用于YfData实例的方法具体取决于实例是否共享 session。_fetch_json中的两个关键兜底yfinance/domain/market.py响应为空或正文包含Will be right back时抛出YFDataException(*** YAHOO! FINANCE IS CURRENTLY DOWN! ***)明确告知 Yahoo 服务当前不可用JSON 解析失败时依据YfConfig.debug.hide_exceptions决定是抛出还是吞掉异常并记录 error 日志。回归测试验证仓库为Market提供了完整的单元测试tests/test_market.py按关注点分为两组TestMarketValidation入参校验字符串与枚举两种入参均能得到str类型的m.market非法区域抛ValueError且错误信息包含合法候选MarketRegion恰有 8 个成员且MarketRegion.EUROPE EUROPE成立。TestMarketFetch真实抓取USsummary 非空、status 非空且id usEUROPEsummary 返回区域交易所不含SNP非 US 市场 status 为None。这三条测试与文档 note、源码检测逻辑形成了「文档 — 实现 — 测试」三方互证是理解Market行为边界的权威依据。常见问题速查Q1Market(GB)与Market(EUROPE)有什么区别区域枚举不同summary会请求不同的区域市场数据GB 对应英国、EUROPE 对应整个欧洲但两者的status都因markettime限制而返回None。Q2为什么Market(EUROPE).status是None不是 bug而是 Yahoomarkettime端点目前忽略market参数、只返回美国数据库主动检测到这一不一致后置空并告警防止误用见上文「关键警告」。Q3summary 返回的数据长什么样一个以交易所代码为键的字典每个值包含shortName、regularMarketPrice、regularMarketChange、regularMarketChangePercent四个字段formattedFalse时为原始数值。Q4能自定义请求超时或代理吗可以。构造时传入timeout秒数与自定义session如带代理的requests.Session即可两者都会透传到YfData.cache_get()。Q5如何看到请求与解析过程的调试日志开启 yfinance 调试日志yf.config.debug.logging True即可看到Market内部打印的Parsing market data等 debug 信息解析失败时则会有 error 级日志默认不抛异常。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考