yfinance WebSocket 实时行情流式订阅指南WebSocket 与 AsyncWebSocket 用法详解【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinanceyfinance 的WebSocket模块允许开发者通过 Yahoo Finance 的 WebSocket 服务流式获取实时价格数据并同时提供同步WebSocket与异步AsyncWebSocket两种客户端接口。本文以 yfinance.websocket.rst 为骨架结合 live.py 源码、pricing.proto 协议定义与 test_live.py 测试用例系统讲解如何订阅股票、加密货币等多类标的的实时行情如何编写消息回调、管理订阅生命周期并深入剖析底层的连接、心跳与 Protobuf 解码机制。读完本文你将能够在自己项目中直接接入实时行情推送并理解同步/异步两种模式各自的适用场景与注意事项。模块概览一个模块两种客户端WebSocket模块是 yfinance 对外暴露的公开 API 之一在 yfinance/init.py 中通过from .live import WebSocket, AsyncWebSocket导入并列入包的__all__导出列表因此可以直接通过yf.WebSocket与yf.AsyncWebSocket使用。该模块提供两个核心类见 API Reference 索引类接口风格适用场景WebSocket同步阻塞式脚本、命令行工具、简单轮询式应用AsyncWebSocket异步asyncio协程高并发服务、需要与其他异步 I/O 协同的程序两者共享同一个基类BaseWebSocket位于 yfinance/live.py因此具备一致的默认 URL、日志对象、订阅集合维护逻辑与消息解码逻辑差异主要体现在连接、收发消息与生命周期管理的实现方式上。安装与依赖实时行情功能依赖两个关键第三方库已在 pyproject.toml 中声明为硬性依赖websockets13.0提供同步websockets.sync.client与异步websockets.asyncio.client两种 WebSocket 客户端实现protobuf3.19.0用于解析 Yahoo Finance 下发的 Protobuf 二进制行情消息。使用pip install yfinance或从仓库安装pip install -e .即可自动带上这两个依赖无需额外配置。同步客户端WebSocketWebSocket类提供了阻塞式的订阅接口。原文档引用的完整示例位于 live_sync.py下面结合源码逐段拆解。基础用法回调模式import yfinance as yf # 定义消息回调函数每收到一条行情都会被调用一次 def message_handler(message): print(Received message:, message) # # 使用上下文管理器推荐 # with yf.WebSocket() as ws: ws.subscribe([AAPL, BTC-USD]) ws.listen(message_handler) # # 不使用上下文管理器需手动关闭 # ws yf.WebSocket() ws.subscribe([AAPL, BTC-USD]) ws.listen(message_handler)两点值得注意订阅标的即传即用subscribe()同时接受单个字符串或字符串列表源码中isinstance(symbols, str)判断后自动包装为列表见 live.py示例中的BTC-USD表明该接口不仅支持股票也支持加密货币等 Yahoo Finance 覆盖的标的类型。上下文管理器WebSocket实现了__enter__/__exit__live.py进入时自动建立连接退出时自动调用close()避免连接泄漏。手工创建实例时则需自行管理close()。listen 的两种模式listen(message_handlerNone)是核心的收流方法live.py传入回调每条解码后的消息作为dict传入回调函数回调抛出的异常会被捕获记录可通过YfConfig.debug.hide_exceptions控制是否继续抛出不传回调默认直接print(decoded_message)适合快速验证连通性。由于listen内部是while True死循环WebSocket还监听KeyboardInterrupt收到 CtrlC 时打印提示并调用close()后退出循环live.py。若流中出现其他异常同步客户端会记录日志并退出循环不会自动重连因此长时间运行的同步程序需要自己在外层处理重连逻辑。动态管理订阅ws yf.WebSocket() ws.subscribe(AAPL) # 订阅单只 ws.subscribe([MSFT, GOOG]) # 追加订阅多只 ws.unsubscribe(AAPL) # 取消订阅subscribe会把新标的合并进内部_subscriptions集合并发送{subscribe: [...]}消息unsubscribe则从集合中移除并发送{unsubscribe: [...]}消息live.py。订阅集合的去重由set天然保证。异步客户端AsyncWebSocketAsyncWebSocket提供asyncio风格的接口全部核心方法均为协程。原文档示例见 live_async.pyimport asyncio import yfinance as yf # 消息回调此处为普通同步函数也支持协程函数 def message_handler(message): print(Received message:, message) async def main(): # # 使用异步上下文管理器 # async with yf.AsyncWebSocket() as ws: await ws.subscribe([AAPL, BTC-USD]) await ws.listen() # # 不使用上下文管理器 # ws yf.AsyncWebSocket() await ws.subscribe([AAPL, BTC-USD]) await ws.listen() asyncio.run(main())与同步客户端的差异全部方法都是协程subscribe、unsubscribe、listen、close均需await示例中listen()未传回调默认打印解码消息支持异步回调listen(message_handler)内部会检测回调是否为协程函数asyncio.iscoroutinefunction是则await调用否则直接调用live.py因此同步与异步两种回调写法都合法async def async_handler(message): # 可以在回调里继续 await 其他 I/O ... await ws.listen(async_handler)自动重连与同步版本不同异步listen捕获异常后会在asyncio.sleep(3)退避后尝试重新_connect()live.py对长时间运行的守护进程更友好优雅退出捕获KeyboardInterrupt或asyncio.CancelledError时关闭连接并退出live.py。AsyncWebSocket同样实现异步上下文管理器__aenter__/__aexit__live.py退出时自动close()。在 Jupyter Notebook 中使用异步代码原文档特别强调了一个实战坑Jupyter Notebook 自带一个正在运行的事件循环直接在单元格里await会因嵌套事件循环报错。解决办法是引入nest_asyncio允许嵌套事件循环在运行异步代码前执行import nest_asyncio nest_asyncio.apply()之后即可在 Notebook 中正常await yf.AsyncWebSocket()相关操作。若使用同步WebSocket则无需此处理。构造函数参数与全局配置两个类的构造函数签名一致继承自BaseWebSocket见 live.pyWebSocket(urlwss://streamer.finance.yahoo.com/?version2, verboseTrue) AsyncWebSocket(urlwss://streamer.finance.yahoo.com/?version2, verboseTrue)参数默认值说明urlwss://streamer.finance.yahoo.com/?version2Yahoo Finance 实时行情 WebSocket 服务地址一般无需修改verboseTrue是否打印连接、订阅、关闭等过程信息生产环境建议置为False并使用日志过程日志通过utils.get_yf_logger()获取的 yfinance 统一 logger 输出异常行为受全局配置YfConfig.debug.hide_exceptions控制默认True即吞掉异常并记日志见 config.py。可借助该配置在开发阶段临时打开异常透传以排查问题。底层原理连接、心跳与 Protobuf 解码连接与订阅协议客户端默认连接wss://streamer.finance.yahoo.com/?version2。建立连接后订阅/取消订阅通过发送 JSON 文本消息完成live.py{subscribe: [AAPL, BTC-USD]} {unsubscribe: [AAPL]}心跳保活机制为避免空闲连接被服务端断开两个客户端都内置了周期性订阅心跳任务_periodic_subscribelive.py每15 秒_subscription_interval 15见 live.py将当前全部订阅标的重新发送一遍{subscribe: [...]}。该任务在首次subscribe或listen时通过asyncio.create_task启动close()时被取消。行情消息的解码链路服务端下发的原始消息是 JSON 包装的 base64 字符串其message字段承载二进制 Protobuf 数据。解码过程在BaseWebSocket._decode_message中完成live.pybase64 字符串 │ base64.b64decode ▼ 二进制 PricingData │ PricingData.ParseFromString ▼ Protobuf 对象 │ MessageToDict(preserving_proto_field_nameTrue) ▼ Python dict回调收到的 message调用链为listen收到文本 →json.loads解析 → 取出message字段 →_decode_message→ 交给回调或直接打印。解码失败时如非法 base64返回{error: ..., raw_base64: ...}字典便于定位问题test_live.py 对该容错路径有专门断言。PricingData 消息结构二进制协议的字段定义在 pricing.proto 中共 33 个字段覆盖股票与加密货币两类行情通用行情id标的标识、price现价、time时间戳、currency计价货币、exchange交易所、quote_type、market_hours市场状态、change_percent涨跌幅、change涨跌额、day_volume当日成交量、day_high/day_low日内高低、open_price、previous_close、short_name简称。盘口数据bid/ask买一卖一价、bid_size/ask_size买一卖一量、last_size最后一笔成交量、price_hint。期权字段部分标的可用expire_date到期日、strike_price行权价、underlying_symbol标的证券、open_interest未平仓量、options_type、mini_option。加密货币字段vol_24hr24 小时成交量、vol_all_currencies、from_currency来源币种、last_market、circulating_supply流通供应量、market_cap市值。测试用例 test_live.py 用一段真实的BTC-USDbase64 消息验证了解码结果期望字典中包含idBTC-USD、price、currencyUSD、exchangeCCC等字段可作为理解消息结构的直观样例。验证与测试仓库在 test_live.py 中提供了两个单元测试test_decode_message_valid解码真实的 base64 行情消息并断言各字段值test_decode_message_invalid解码非法 base64断言返回error与raw_base64字段。运行方式参考 development/testing.rstpytest tests/test_live.py注意_decode_message在YfConfig.debug.hide_exceptionsTrue默认时返回错误字典而非抛出异常测试正是依赖这一行为。最佳实践与注意事项优先使用上下文管理器with/async with能自动完成连接建立与释放避免listen死循环退出后连接残留。同步 vs 异步选型单机脚本、快速验证用同步WebSocket常驻服务、需要并发处理多个标的或与其他异步库协作时用AsyncWebSocket后者还自带 3 秒退避重连。Jupyter 环境异步示例在 Notebook 中运行前务必nest_asyncio.apply()同步版本则不受事件循环影响。生产环境关闭 verbose将verboseFalse并配合 yfinance logger 统一管理日志避免海量行情打印刷屏。订阅集合去重重复subscribe同一标的是安全的set去重但取消订阅后再订阅同一标的会重新加入集合。回调异常处理回调内的业务逻辑应自行 try/except底层对回调异常的默认行为是记录日志后继续不会中断收流受hide_exceptions配置影响。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考