Bokeh Server 参考解析bokeh.server 模块的架构、核心类与 ASGI/Tornado 双前端【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 的bokeh.server模块是 Python 侧与浏览器侧实现“双向同步”的全部服务端能力的入口它负责用应用代码为每个新连接创建独立的 BokehDocument、维护ServerSession生命周期并把属性变更与回调结果通过 WebSocket 协议同步回客户端。本篇以官方参考文档 bokeh.server 索引页 为主体结合src/bokeh/server下的源码实现梳理该模块的整体架构、两个前端ASGI 与 Tornado、核心类参数以及参考文档树toctree中 12 个子模块文档与源码文件的对应关系。读完后你应能判断何时用BokehASGI何时用Server/BokehTornado理解Server各配置项的底层行为并知道每个子模块文档对应哪份源码。模块定位为什么需要 Bokeh Server参考文档开篇即给出核心定位使用 Bokeh server 创建交互式可视化“最灵活的方式”是创建 Bokeh Application 并交由 Bokeh server 提供服务。在这种模式下server 会用应用代码为所有连接进来的客户端通常是浏览器创建会话Session和文档Document。每次有新的连接建立时应用代码都会在 server 中重新执行只为该会话生成一份新的 BokehDocument并与浏览器同步应用代码同时还负责注册各类回调以便在属性如控件值变化时运行相应逻辑。这一“Python ↔ 浏览器同步”定位在模块 docstring 中表述得更为完整。src/bokeh/server/init.py 指出Bokeh 的架构是高层“模型对象”图、range、轴、glyph 等在 Python 中创建并转换为 JSON 交给 BokehJS 消费而一旦让 Python 侧与浏览器侧的模型对象保持同步就解锁了三类能力用完整 Python 计算能力响应浏览器产生的 UI 与工具事件自动把服务端更新推送到浏览器 UI控件、图使用周期、超时和异步回调驱动流式更新。docstring 明确写道“Python 与浏览器之间的这种同步能力是 Bokeh Server 的主要目的。” 该文件还给出了当前版本的两个前端入口使用BokehASGIbokeh.server.asgi配合 ASGI 服务器或框架Tornado 前端则通过Server和BokehTornado继续可用。这与参考文档索引页指向的bokeh.server.asgi、bokeh.server.server等子文档一致。架构总览Application、Session 与 Document原文档配有一张架构图即上文所引bokeh_serve.svg其要点是左侧的 Bokeh server 使用 Application 代码创建 Bokeh Document右侧浏览器的每一个新连接都会让 server 为该会话单独创建一份 Document。这个“每连接一份 Document”的隔离模型正是理解bokeh.server各子模块的钥匙源码结构上可以对应为三层应用层Application/ handler 负责“每次连接执行一次”的文档构建逻辑定义在 src/bokeh/application 包中bokeh.server通过 TYPE_CHECKING 导入其Application、ModifyDoc类型会话层ServerSessionsrc/bokeh/server/session.py持有Document、管理连接、回调与文档锁传输/路由层Tornado 前端src/bokeh/server/tornado.py、views 下的WSHandler等或 ASGI 前端src/bokeh/server/asgi.py负责 HTTP 路由与 WebSocket 消息收发。从源码结构看tornado.py从bokeh.server.core导入了一组默认值常量DEFAULT_CHECK_UNUSED_MS、DEFAULT_SESSION_TOKEN_EXPIRATION、DEFAULT_STATS_LOG_FREQ_MS、DEFAULT_UNUSED_LIFETIME_MS、DEFAULT_WEBSOCKET_MAX_MESSAGE_SIZE_BYTES以及create_session工厂——这说明“会话闲置检测、会话过期、统计日志、WebSocket 消息大小上限”等运行时参数在 Tornado 与 ASGI 两个前端共享同一套核心core.py中的BokehServerCore前端只负责传输与鉴权。两个前端BokehASGI 与 Server/BokehTornadoBokehASGI框架无关的 ASGI 前端bokeh.server.asgi 参考页 用automodule自动列出bokeh.server.asgi的全部成员并特别指向AuthPolicy作为“ASGI HTTP 与 websocket 请求的框架无关鉴权”。从 src/bokeh/server/asgi.py 的模块 docstring“A framework-neutral ASGI frontend for Bokeh server applications”和实现可以看到公开 API 只有一个类__all__ (BokehASGI,)即它被设计为可直接挂载到任意 ASGI 服务器Uvicorn、Hypercorn 等或框架上的单例入口内部通过_ASGIWebSocketTransport把 Bokeh 协议消息Message.fragments()产出的文本/二进制片段封装为websocket.send事件发出并用asyncio.Lock保护写操作体现 ASGI 异步传输层的职责边界会话令牌校验复用 src/bokeh/util/token.py 的check_token_signature、get_session_id、get_token_payload静态文件、图标、根页面等视图逻辑则集中在views/子包中ASGI 与 Tornado 前端共用。__init__.py的推荐语“UseBokehASGIwith an ASGI server or framework”意味着在能选择部署栈的场景下ASGI 前端是当前版本的首要入口。Server 与 BokehTornadoTornado 前端bokeh.server.server 参考页 自动展开bokeh.server.server成员。src/bokeh/server/server.py 的模块 docstring 明确该模块有两个公开类BaseServer轻量协调类显式组织运行一个 Bokeh server 所需的三个 Tornado 组件——运行 server 机制的IOLoop、定义 Bokeh server 机制的BokehTornado应用、负责 HTTP 请求的HTTPServer。三者必须显式传入BaseServer会在io_loop上初始化BokehTornado。Server高层便利类只需配置 BokehApplication实例自动创建并协调上述 Tornado 组件另提供Server.from_settings类方法自动把 Bokeh 全局 settings认证、SSL、会话签名、cookie 等应用到服务器参数上方便以与bokeh serve相同的环境变量约定进行程序化建服。Server构造函数源码中可见几个关键约束与行为server.pyapplications参数接受Mapping[str, Application | ModifyDoc]URL 路径到应用的映射、单个Application自动挂到根 URL/或一个可调用对象会用FunctionHandler包装成 Application。每个应用由 URL 路径标识如/或/myappnum_procs 1与显式io_loop不能同时设置否则抛出RuntimeError需要改用BaseServer手动协调num_procs 1在 Windows 上不支持unix_socket在 Windows 上也不支持设置ssl_certfile时构造ssl.SSLContextssl.Purpose.CLIENT_AUTH并注入http_server_kwargs[ssl_options]即由 TornadoHTTPServer直接做 TLS 终结allow_websocket_origin经create_hosts_allowlistsrc/bokeh/server/util.py解析后作为extra_websocket_origins传给BokehTornado用于放行 WebSocket 握手来源如bokeh serve --allow-websocket-origin对应的能力prefix、index根路径 Jinja2 模板、websocket_max_message_size一并透传给BokehTornadonum_procs ! 1时会检查所有应用是否safe_to_fork防止在 fork 前运行过用户代码造成多进程不安全。BaseServer还提供运行期 APIstart()非阻塞安装到 IOLoop、run_until_shutdown()注册atexit钩子与非 Windows 下的SIGTERM信号处理阻塞直到用户中断、stop()/stop_async()/wait_until_stopped()从源码注释可见同事件循环内同步调用无法阻塞该循环因此改为调度清理任务并暴露异步等待屏障、show(app_path)本地测试用app_path必须以/开头、以及get_sessions()、port、address、prefix、index等属性。BokehTornado本身src/bokeh/server/tornado.py是一个 Tornadoweb.Application导入关系显示它装配了根路由RootHandler、faviconIcoHandler、静态文件StaticHandler/AsyncStaticFileHandler与 WebSocketviews.ws.WSHandler路由规则来自 src/bokeh/server/urls.py 的per_app_patterns与toplevel_patterns并使用PeriodicCallback实现闲置会话检查与统计日志。会话与文档ServerSession 的核心机制bokeh.server.session 参考页 对应 src/bokeh/server/session.py核心是ServerSession类。源码中可以确认的关键机制文档锁装饰器_needs_document_lock把所有会操纵会话文档的方法包成协程先block_expiration()防止会话在异步任务执行中途被回收再持有self._lock串行化对Document的修改回调若需执行耗时 Python 代码会经_run_in_executorsrc/bokeh/server/executor.py卸载到线程池避免阻塞事件循环——这正是“回调不卡 UI”的实现基础。补丁序列化文档变更先收集为_PendingPatch事件 受影响连接列表再由_serialize_patches通过协议层的patch_doc/patch_doc_reply等src/bokeh/protocol转成发给浏览器连接的Message实现“一次变更、多连接推送”。连接生命周期会话引入ConnectionLost事件与_log_connection_lost_error等辅助配合 src/bokeh/server/connection.py 的ServerConnection完成“浏览器断开 → 会话感知 → 通知回调”的链路。参考文档树与源码模块对照参考文档索引页用toctree:glob: server/*列出了bokeh.server的全部子模块文档。下表将其与源码文件对照方便按图索骥各.rst均通过automodule ... :members:自动展开对应模块的公共成员参考文档源码文件主题bokeh.server.asgisrc/bokeh/server/asgi.py框架无关 ASGI 前端BokehASGIbokeh.server.authsrc/bokeh/server/auth.pyAuthPolicyASGI 请求的框架无关鉴权bokeh.server.auth_providersrc/bokeh/server/auth_provider.pyAuthProvider/AuthModule/NullAuth等鉴权提供者bokeh.server.callbackssrc/bokeh/server/callbacks.py文档/会话回调分组DocumentCallbackGroup等bokeh.server.connectionsrc/bokeh/server/connection.pyServerConnection一条浏览器连接bokeh.server.contextssrc/bokeh/server/contexts.pyApplicationContext等应用/会话上下文管理bokeh.server.serversrc/bokeh/server/server.pyBaseServer/Server/bind_socketsbokeh.server.sessionsrc/bokeh/server/session.pyServerSessionbokeh.server.tornadosrc/bokeh/server/tornado.pyBokehTornadoTornado 应用bokeh.server.urlssrc/bokeh/server/urls.pyURL 路由规则bokeh.server.utilsrc/bokeh/server/util.py工具函数如create_hosts_allowlistbokeh.server.viewssrc/bokeh/server/views/各 HTTP/WS 处理器WSHandler等原文档同时提醒侧边栏这些参考链接面向的是 Bokeh Server 的细节实现多数用户若无特殊需求应直接查阅 Users Guide 的 server 章节ug_server锚点对应的用户指南了解“如何使用” Bokeh Server而不是“如何实现”。这一分工在源码中也有对应——例如 examples/output/apis 下提供server_document、server_session等输出 API 示例而 examples/server/app 展示了典型的服务端应用写法可作为从参考层回到使用层的实践入口。程序化使用要点小结结合Server的 docstring 与实现程序化启动一个 Bokeh server 的最小事实依据是均来自 server.py 的 API 定义传入applications单应用自动挂载到/多应用使用{/path: app}映射纯函数应用可直接传可调用对象常用运行参数经**kwargs进入_ServerOptsbokeh.server.server模块的 options 表docstring 中以.. bokeh-options:: _ServerOpts自动渲染涵盖address、port、num_procs、prefix、index、ssl_certfile/ssl_keyfile/ssl_password、allow_websocket_origin、unix_socket、use_xheaders、websocket_max_message_size等启动流程构造Server后调用run_until_shutdown()阻塞、响应 Ctrl-C/SIGTERM需要嵌入已有事件循环时用start() 自行驱动 IOLoop若需沿用bokeh serve的环境变量约定认证、SSL、会话签名、cookie 等使用Server.from_settings它显式接收auth_provider、secret_key、sign_sessions、ssl_certfile/ssl_keyfile/ssl_password、cookie_secret等关键字参数并从全局settings补齐生产部署优先评估BokehASGI 你的 ASGI 服务器仅在需要 Tornado 多进程num_procs、Unix socket 直挂等 Tornado 特性时选择Server/BokehTornado路径num_procs 1不支持 Windows。小结bokeh.server参考文档索引页的价值在于给出该包的“地图”以 Application→Session→Document 的每连接隔离模型为核心以ServerSession的文档锁与补丁广播为同步机制以 ASGIBokehASGI与 TornadoServer/BokehTornado双前端为部署形态。本文所有结论均可回溯到 src/bokeh/server/init.py、src/bokeh/server/server.py、src/bokeh/server/session.py、src/bokeh/server/tornado.py 与 src/bokeh/server/asgi.py 等源码文件以及 docs/bokeh/source/docs/reference/server 下的各子模块参考页。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考