Bokeh 3.8.0 新特性全解析HoverTool 过滤排序、SizeBar 尺寸标注与会话重连机制【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh本文以 Bokeh 官方 3.8.0 版本发布说明docs/bokeh/source/docs/releases/3.8.0.rst为核心脉络结合当前仓库中的 Python 与 BokehJS 源码、官方示例与测试配置逐项深入解读该里程碑版本引入的新能力。读完本文你将掌握如何用filters/sort_by/limit精确控制 HoverTool 的提示内容与数量、如何用SizeBar为径向散点图补充第三维度、如何通过Document.config统一配置会话重连、通知与色彩模式以及缓冲区压缩、SVG 图标、CSS 变量主题等底层改进的来龙去脉。版本概览3.8.0 在 Bokeh 演进中的定位Bokeh3.8.02025 年 8 月发布是 Bokeh 项目的一个 minor milestone次要里程碑。它并非一次破坏性大重构而是沿着三条主线稳步推进交互体验深化让 HoverTool 具备类表格查询能力的过滤、排序与数量限制为服务端会话引入自动重连与连接状态通知。可视化表达能力扩展新增Plot侧边面板side panel布局支持与SizeBar尺寸标注并引入legend_name参数简化多图例管理。工程与性能基建升级序列化协议支持缓冲区压缩、图标全面 SVG 化、CSS 变量主题初探、BokehJS 性能优化以及 TypeScript 5.9 构建系统升级。下文将逐条展开每条均给出可复制的配置/代码示例并附上仓库内的源码证据路径。HoverTool 的数据洞察能力升级filters、sort_by 与 limit3.8.0 之前HoverTool会对命中点的所有数据行弹出 tooltip当散点图数据密集、命中点众多时提示内容会变得杂乱无章。3.8.0 为HoverTool增加了三个互补的能力对应 src/bokeh/models/tools.py 中HoverTool模型的定义属性类型默认值作用filtersDict(String, Either(Instance(CustomJS), List(Instance(CustomJS)))){}按字段对命中结果做自定义过滤sort_byNullable(Either(String, List(...)))None按单个字段或字段序列排序悬停结果limitNullable(Positive(Int))None限制显示 tooltip 的数据点数量filters按字段精细过滤命中点filters以字段名为键、CustomJS回调为值在渲染 tooltip 之前过滤命中结果。回调函数签名与 BokehJS 侧一致可解构出value、row、index、field、data_source、vars等上下文。源码中的文档示例src/bokeh/models/tools.py#L1630-L1643演示了只显示x 0的命中点from bokeh.models import CustomJS, HoverTool filter_code export default (args, tool, {value: x, row, index, field, data_source, vars}) { return x 0 } tool HoverTool(filters{x: CustomJS(args{}, codefilter_code)})从 BokehJS 实现看bokehjs/src/lib/models/tools/inspectors/hover_tool.tsxfilters变化时会触发_update_filters()约第 187 行并在渲染 tooltip 前对每条命中记录逐字段执行过滤器仅保留全部通过的数据行。sort_by让提示内容按需有序sort_by支持两种形态简单字符串sort_byy按单个字段排序序列形式sort_by[(y, descending), x]支持逐字段指定排序方向ascending/descending对应 src/bokeh/core/enums.py#L600-L602 的SortDirection枚举。需要说明的是sort_by影响的是 tooltip 列表的展示顺序而不是数据源本身。默认排序基于数据索引和/或与命中点的邻近程度一旦指定sort_by则按指定字段重新排序命中结果。limit限制 tooltip 条数上限limit直接对最终展示的 tooltip 数量做截断Positive(Int)不可为负。BokehJS 侧在收集命中条目后执行entries.splice(limit)hover_tool.tsx 约第 633-635 行。合理的limit能显著降低密集散点图在 hover 时的渲染开销与视觉噪声。三者可以组合使用先filters剔除无关点再sort_by排列优先级最后用limit兜底条数从而把 HoverTool 从全量罗列升级为精准投递。会话可靠性自动重连、连接事件与 UI 通知3.8.0 为 Bokeh Server 场景引入了会话层面的可靠性机制当 WebSocket 会话意外断开时自动尝试恢复连接并通过 UI 通知用户连接状态的变化。该能力由新增的文档配置模型DocumentConfig统一管理其实现位于 src/bokeh/document/config.py。DocumentConfig目前暴露四个可配置属性属性类型默认值说明reconnect_sessionBoolTrue是否启用会话重连逻辑若禁用断开后不再自动恢复notify_connection_statusBoolTrue是否在 UI 中告知用户连接状态使用自定义通知系统时可关闭notificationsNullable(Instance(Notifications))Notifications()配置或替换通知 UI 与逻辑color_schemeEnum(ColorScheme)auto界面配色方案取值auto/light/dark其中notifications指向的Notifications模型src/bokeh/models/ui/notifications.py是一个UIElement用于在浏览器视口中显示全局通知消息/错误即连接状态横幅背后的承载组件。color_scheme的取值来自 src/bokeh/core/enums.py#L341-L343 定义的ColorScheme字符串枚举。一个典型的自定义配置示例from bokeh.document import Document from bokeh.models import Notifications doc Document() doc.config.reconnect_session True # 保持自动重连默认即开启 doc.config.notify_connection_status True # 显示连接状态通知 doc.config.notifications Notifications() # 可替换为自定义通知组件 doc.config.color_scheme dark # 强制深色 UI对于部署了自定义前端通知体系如独立的消息中心的用户将notify_connection_status设为False可避免 Bokeh 默认横幅与自有系统重复提示。Plot 侧边面板布局与 SizeBar 标注3.8.0 引入的SizeBar是本次发布中最具可视化表现力的新增标注它允许在 2D 散点图上为径向 glyph如Circle、Ngon提供尺寸比例尺等价于给散点图增加第三维度——用圆半径编码数据值再用SizeBar告诉读者多大的圆对应多大的数值。SizeBar 的完整属性面SizeBar继承自BaseBar两者均定义于 src/bokeh/models/annotations/legends.pySizeBar本体见 第 915-952 行。从基类继承的布局与刻度属性legends.py#L785-L913包括locationtop_right等锚点枚举或(x, y)屏幕坐标元组若放置在侧边面板中通常需要设为(0, 0)orientationvertical/horizontal/autowidth/height像素尺寸支持max或整数默认 200 / 50margin/padding外部边距默认 30与内部留白默认 10title与title_standoff标题文本及与条身的间距标题默认字号 13px、斜体ticker/formatter刻度计算器与格式化器默认automajor_label_overrides/major_label_policy刻度标签覆盖与防重叠策略默认NoOverlapmajor_tick_in/major_tick_out、minor_tick_in/minor_tick_out主/次刻度内外延伸长度bar_*/border_*/background_*条身轮廓、边框与背景填充样式背景默认白色、alpha 0.95。SizeBar自身专属的三个属性legends.py#L926-L952rendererEither(GlyphRendererOf(RadialGlyph), Auto)默认auto。当图中只有一个径向 glyph renderer 时可安全使用自动模式多个时需显式指定目标 rendererboundsEither(Auto, Tuple(Float, Float))默认auto用于限制显示半径的数值范围glyph_*glyph_line_props/glyph_fill_props/glyph_hatch_props条内示意 glyph 的线/填充/填充纹理样式glyph_line_color默认None。BokehJS 侧的实现bokehjs/src/lib/models/annotations/size_bar.ts印证了上述设计renderer auto时会在 plot 的所有 renderer 中筛选径向 glyph renderer找不到或找到多个时分别给出警告并回退约第 264-284 行bounds为auto时展开为[-Infinity, Infinity]并基于glyph_view.radius的最小/最大值与 bounds 求交集约第 304-310 行绘制时按方向组合标题、条身与刻度约第 123-213 行。官方示例SizeBar 实战仓库自带可直接运行的示例 examples/basic/annotations/size_bar.pyimport numpy as np from bokeh.models import SizeBar from bokeh.plotting import figure, show N 100 x np.random.random(sizeN) * 100 y np.random.random(sizeN) * 100 radii np.random.random(sizeN) * 10 colors np.array([(r, g, 150) for r, g in zip(50 2*x, 30 2*y)], dtypenp.uint8) p figure() cr p.circle(x, y, radiusradii, fill_colorcolors, fill_alpha0.6, line_colorNone) size_bar SizeBar( renderercr, # 绑定圆 renderer也可省略以使用 auto titleSizeBar component, widthmax, # 条宽占满可用空间 orientationhorizontal, # 水平条 glyph_fill_colorviolet, glyph_fill_alpha0.8, glyph_line_colorblack, border_line_colorgray, border_line_dashdotted, ) p.add_layout(size_bar, below) # 挂载到下方侧边面板 show(p)注意p.add_layout(size_bar, below)正是 3.8.0 侧边面板side panel布局能力的一种体现——SizeBar被安放在 plot 的 below 面板中而非叠加在绘图区域内部。Document.config文档级配置的统一入口DocumentConfig不仅承载会话重连相关配置它同时也是 3.8.0 引入的文档配置Document.config入口本身。通过doc.config这一属性开发者可以在一个位置集中控制文档级行为避免散落在各处的手工模型属性调整。从 src/bokeh/document/config.py 可以看到DocumentConfig本身是一个Model子类因此它同样遵循 Bokeh 的属性系统与序列化流程可以在服务端设置、随文档传输到前端生效。这一设计的意义在于连接策略、通知样式、配色方案等应用级偏好从此有了明确的归属与统一的编程接口也为后续版本扩展更多文档级配置项预留了空间。legend_name更简单的多图例管理3.8.0 为 glyph API 增加了legend_name关键字参数用于按图例名归组彻底简化了多图例场景下的 renderer 分配。其实现位于 src/bokeh/plotting/_legends.pypop_legend_kwarg约第 62-63 行从调用参数中取出legend_nameupdate_legend第 65-67 行根据legend_name查找或创建对应的Legend实例_get_or_create_legend第 81-107 行的核心逻辑是先收集图中所有legend类型的 renderer若指定了legend_name则筛选出name legend_name的图例——找不到时抛出RuntimeError(cant find Legend instance with ... name)找到多个时抛出RuntimeError(found multiple Legend instances with ... name)若未指定名称则沿用图中只允许一个图例的传统约束否则提示用户用 name 区分图例并用 legend_name 参数将 renderer 指派到对应图例。典型用法区别于旧的p.legend单例模式from bokeh.plotting import figure p figure() p.add_layout(Legend(namefirst), right) p.add_layout(Legend(namesecond), right) p.circle(x, y, legend_labelfirst, legend_namefirst) p.square(x, y, legend_labelsecond, legend_namesecond)配合Legend.name属性开发者可以在同一张图中维护多个独立图例并精准控制每个 renderer 归属于哪个图例无需再手动拼接p.legend的 renderer 列表。序列化协议缓冲区压缩的底层实现3.8.0 为 Bokeh 序列化协议加入了 buffer如大型数值数组的压缩支持这对大数据集的前端传输有明显收益。其 Python 侧核心位于 src/bokeh/core/serialization.py 的Buffer数据类第 159-180 行dataclass class Buffer: id: ID data: bytes | memoryview def to_compressed_bytes(self) - bytes: level settings.compression_level() # Python 3.11/3.12 存在 mtime0 时 Gzip 头部 OS 字段不稳定的问题 # 因此这里使用 mtime1 以保证可复现输出 return gzip.compress(self.to_bytes(), mtime1, compresslevellevel) def to_base64(self) - str: return base64.b64encode(self.to_compressed_bytes()).decode(utf-8)对应地BokehJS 侧的解压逻辑位于 bokehjs/src/lib/core/util/buffer.tsbuffer_to_base64使用fflate的gzipSync(bytes, {mtime: 0})压缩后 base64 编码第 32-38 行注释说明固定mtime0是为了测试结果可复现base64_to_buffer则用gunzipSync解压还原第 40-43 行。压缩级别通过BOKEH_COMPRESSION_LEVEL环境变量控制默认值为 2src/bokeh/settings.py#L656 附近的compression_level设置即默认启用但级别偏低、速度优先。此外bokeh serve命令行也暴露了websocket_compression_level与websocket_compression_mem_level参数见 src/bokeh/command/subcommands/serve.py#L860-L876 的参数收集列表以及 src/bokeh/server/tornado.py 中对应的 WebSocket 压缩配置用于调整 WebSocket 通道自身的压缩级别。视觉与主题SVG 图标与 CSS 变量主题初探3.8.0 将原先的 PNG 图标全面转换为 SVG并对既有图标做了一轮整体刷新。仓库中可见佐证是 bokehjs/src/less/icons/ 目录下 83 个.svg图标文件它们由 bokehjs/src/less/icons.less 统一组织为图标字体/样式资源。SVG 化的收益在于任意分辨率下保持清晰、易于通过 CSS 着色与缩放、资源体积更小。同期引入的基于 CSS 变量的主题化属于初步支持preliminary support。相关 CSS 变量定义集中在 bokehjs/src/less/vars.less配合上文的DocumentConfig.color_schemeauto/light/dark可让 Bokeh UI 初步跟随系统或应用指定的明暗模式。值得强调的是该特性在 3.8.0 中仍处于早期阶段主题变量的覆盖面与稳定性会随后续版本逐步完善。BokehJS 性能改进与 TypeScript 5.9 构建升级3.8.0 还包含多项 BokehJS 性能改进涉及渲染管线与序列化相关路径以及将 bokehjs 构建系统升级至 TypeScript 5.9 的工程调整。TypeScript 版本升级主要影响库内部开发与构建对最终用户 API 透明。性能改进的细节分散在 bokehjs/src/lib 各模块中若需进一步定位可重点检索核心渲染core/visuals、models/glyphs与序列化core/util相关目录的近期改动。升级与验证建议升级方式通过pip install bokeh3.8.0安装对应版本运行bokeh serve前可通过BOKEH_COMPRESSION_LEVEL调整 buffer 压缩级别默认 2。快速验证新特性运行 examples/basic/annotations/size_bar.py 查看SizeBar效果为HoverTool组合filters/sort_by/limit观察密集散点图 tooltip 的数量与排序变化在 Bokeh Server 应用中通过doc.config开启重连并切换color_scheme测试断线恢复与通知展示。回归测试参考仓库的测试套件tests/unit/bokeh、bokehjs/test覆盖了上述模型属性与序列化路径升级后建议运行相关单元测试以确认与自定义扩展的兼容性。总体而言3.8.0 是一个体验与基建并重的版本面向用户的新交互能力HoverTool 三件套、SizeBar、legend_name直接提升了图表的可用性而会话重连、缓冲区压缩、SVG 图标与 CSS 变量主题则为更大规模、更可靠、更现代的应用形态打下了基础。开发者可以根据自身场景优先采用其中与业务最相关的若干项能力。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Bokeh 3.8.0 新特性全解析：HoverTool 过滤排序、SizeBar 尺寸标注与会话重连机制
Bokeh 3.8.0 新特性全解析HoverTool 过滤排序、SizeBar 尺寸标注与会话重连机制【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh本文以 Bokeh 官方 3.8.0 版本发布说明docs/bokeh/source/docs/releases/3.8.0.rst为核心脉络结合当前仓库中的 Python 与 BokehJS 源码、官方示例与测试配置逐项深入解读该里程碑版本引入的新能力。读完本文你将掌握如何用filters/sort_by/limit精确控制 HoverTool 的提示内容与数量、如何用SizeBar为径向散点图补充第三维度、如何通过Document.config统一配置会话重连、通知与色彩模式以及缓冲区压缩、SVG 图标、CSS 变量主题等底层改进的来龙去脉。版本概览3.8.0 在 Bokeh 演进中的定位Bokeh3.8.02025 年 8 月发布是 Bokeh 项目的一个 minor milestone次要里程碑。它并非一次破坏性大重构而是沿着三条主线稳步推进交互体验深化让 HoverTool 具备类表格查询能力的过滤、排序与数量限制为服务端会话引入自动重连与连接状态通知。可视化表达能力扩展新增Plot侧边面板side panel布局支持与SizeBar尺寸标注并引入legend_name参数简化多图例管理。工程与性能基建升级序列化协议支持缓冲区压缩、图标全面 SVG 化、CSS 变量主题初探、BokehJS 性能优化以及 TypeScript 5.9 构建系统升级。下文将逐条展开每条均给出可复制的配置/代码示例并附上仓库内的源码证据路径。HoverTool 的数据洞察能力升级filters、sort_by 与 limit3.8.0 之前HoverTool会对命中点的所有数据行弹出 tooltip当散点图数据密集、命中点众多时提示内容会变得杂乱无章。3.8.0 为HoverTool增加了三个互补的能力对应 src/bokeh/models/tools.py 中HoverTool模型的定义属性类型默认值作用filtersDict(String, Either(Instance(CustomJS), List(Instance(CustomJS)))){}按字段对命中结果做自定义过滤sort_byNullable(Either(String, List(...)))None按单个字段或字段序列排序悬停结果limitNullable(Positive(Int))None限制显示 tooltip 的数据点数量filters按字段精细过滤命中点filters以字段名为键、CustomJS回调为值在渲染 tooltip 之前过滤命中结果。回调函数签名与 BokehJS 侧一致可解构出value、row、index、field、data_source、vars等上下文。源码中的文档示例src/bokeh/models/tools.py#L1630-L1643演示了只显示x 0的命中点from bokeh.models import CustomJS, HoverTool filter_code export default (args, tool, {value: x, row, index, field, data_source, vars}) { return x 0 } tool HoverTool(filters{x: CustomJS(args{}, codefilter_code)})从 BokehJS 实现看bokehjs/src/lib/models/tools/inspectors/hover_tool.tsxfilters变化时会触发_update_filters()约第 187 行并在渲染 tooltip 前对每条命中记录逐字段执行过滤器仅保留全部通过的数据行。sort_by让提示内容按需有序sort_by支持两种形态简单字符串sort_byy按单个字段排序序列形式sort_by[(y, descending), x]支持逐字段指定排序方向ascending/descending对应 src/bokeh/core/enums.py#L600-L602 的SortDirection枚举。需要说明的是sort_by影响的是 tooltip 列表的展示顺序而不是数据源本身。默认排序基于数据索引和/或与命中点的邻近程度一旦指定sort_by则按指定字段重新排序命中结果。limit限制 tooltip 条数上限limit直接对最终展示的 tooltip 数量做截断Positive(Int)不可为负。BokehJS 侧在收集命中条目后执行entries.splice(limit)hover_tool.tsx 约第 633-635 行。合理的limit能显著降低密集散点图在 hover 时的渲染开销与视觉噪声。三者可以组合使用先filters剔除无关点再sort_by排列优先级最后用limit兜底条数从而把 HoverTool 从全量罗列升级为精准投递。会话可靠性自动重连、连接事件与 UI 通知3.8.0 为 Bokeh Server 场景引入了会话层面的可靠性机制当 WebSocket 会话意外断开时自动尝试恢复连接并通过 UI 通知用户连接状态的变化。该能力由新增的文档配置模型DocumentConfig统一管理其实现位于 src/bokeh/document/config.py。DocumentConfig目前暴露四个可配置属性属性类型默认值说明reconnect_sessionBoolTrue是否启用会话重连逻辑若禁用断开后不再自动恢复notify_connection_statusBoolTrue是否在 UI 中告知用户连接状态使用自定义通知系统时可关闭notificationsNullable(Instance(Notifications))Notifications()配置或替换通知 UI 与逻辑color_schemeEnum(ColorScheme)auto界面配色方案取值auto/light/dark其中notifications指向的Notifications模型src/bokeh/models/ui/notifications.py是一个UIElement用于在浏览器视口中显示全局通知消息/错误即连接状态横幅背后的承载组件。color_scheme的取值来自 src/bokeh/core/enums.py#L341-L343 定义的ColorScheme字符串枚举。一个典型的自定义配置示例from bokeh.document import Document from bokeh.models import Notifications doc Document() doc.config.reconnect_session True # 保持自动重连默认即开启 doc.config.notify_connection_status True # 显示连接状态通知 doc.config.notifications Notifications() # 可替换为自定义通知组件 doc.config.color_scheme dark # 强制深色 UI对于部署了自定义前端通知体系如独立的消息中心的用户将notify_connection_status设为False可避免 Bokeh 默认横幅与自有系统重复提示。Plot 侧边面板布局与 SizeBar 标注3.8.0 引入的SizeBar是本次发布中最具可视化表现力的新增标注它允许在 2D 散点图上为径向 glyph如Circle、Ngon提供尺寸比例尺等价于给散点图增加第三维度——用圆半径编码数据值再用SizeBar告诉读者多大的圆对应多大的数值。SizeBar 的完整属性面SizeBar继承自BaseBar两者均定义于 src/bokeh/models/annotations/legends.pySizeBar本体见 第 915-952 行。从基类继承的布局与刻度属性legends.py#L785-L913包括locationtop_right等锚点枚举或(x, y)屏幕坐标元组若放置在侧边面板中通常需要设为(0, 0)orientationvertical/horizontal/autowidth/height像素尺寸支持max或整数默认 200 / 50margin/padding外部边距默认 30与内部留白默认 10title与title_standoff标题文本及与条身的间距标题默认字号 13px、斜体ticker/formatter刻度计算器与格式化器默认automajor_label_overrides/major_label_policy刻度标签覆盖与防重叠策略默认NoOverlapmajor_tick_in/major_tick_out、minor_tick_in/minor_tick_out主/次刻度内外延伸长度bar_*/border_*/background_*条身轮廓、边框与背景填充样式背景默认白色、alpha 0.95。SizeBar自身专属的三个属性legends.py#L926-L952rendererEither(GlyphRendererOf(RadialGlyph), Auto)默认auto。当图中只有一个径向 glyph renderer 时可安全使用自动模式多个时需显式指定目标 rendererboundsEither(Auto, Tuple(Float, Float))默认auto用于限制显示半径的数值范围glyph_*glyph_line_props/glyph_fill_props/glyph_hatch_props条内示意 glyph 的线/填充/填充纹理样式glyph_line_color默认None。BokehJS 侧的实现bokehjs/src/lib/models/annotations/size_bar.ts印证了上述设计renderer auto时会在 plot 的所有 renderer 中筛选径向 glyph renderer找不到或找到多个时分别给出警告并回退约第 264-284 行bounds为auto时展开为[-Infinity, Infinity]并基于glyph_view.radius的最小/最大值与 bounds 求交集约第 304-310 行绘制时按方向组合标题、条身与刻度约第 123-213 行。官方示例SizeBar 实战仓库自带可直接运行的示例 examples/basic/annotations/size_bar.pyimport numpy as np from bokeh.models import SizeBar from bokeh.plotting import figure, show N 100 x np.random.random(sizeN) * 100 y np.random.random(sizeN) * 100 radii np.random.random(sizeN) * 10 colors np.array([(r, g, 150) for r, g in zip(50 2*x, 30 2*y)], dtypenp.uint8) p figure() cr p.circle(x, y, radiusradii, fill_colorcolors, fill_alpha0.6, line_colorNone) size_bar SizeBar( renderercr, # 绑定圆 renderer也可省略以使用 auto titleSizeBar component, widthmax, # 条宽占满可用空间 orientationhorizontal, # 水平条 glyph_fill_colorviolet, glyph_fill_alpha0.8, glyph_line_colorblack, border_line_colorgray, border_line_dashdotted, ) p.add_layout(size_bar, below) # 挂载到下方侧边面板 show(p)注意p.add_layout(size_bar, below)正是 3.8.0 侧边面板side panel布局能力的一种体现——SizeBar被安放在 plot 的 below 面板中而非叠加在绘图区域内部。Document.config文档级配置的统一入口DocumentConfig不仅承载会话重连相关配置它同时也是 3.8.0 引入的文档配置Document.config入口本身。通过doc.config这一属性开发者可以在一个位置集中控制文档级行为避免散落在各处的手工模型属性调整。从 src/bokeh/document/config.py 可以看到DocumentConfig本身是一个Model子类因此它同样遵循 Bokeh 的属性系统与序列化流程可以在服务端设置、随文档传输到前端生效。这一设计的意义在于连接策略、通知样式、配色方案等应用级偏好从此有了明确的归属与统一的编程接口也为后续版本扩展更多文档级配置项预留了空间。legend_name更简单的多图例管理3.8.0 为 glyph API 增加了legend_name关键字参数用于按图例名归组彻底简化了多图例场景下的 renderer 分配。其实现位于 src/bokeh/plotting/_legends.pypop_legend_kwarg约第 62-63 行从调用参数中取出legend_nameupdate_legend第 65-67 行根据legend_name查找或创建对应的Legend实例_get_or_create_legend第 81-107 行的核心逻辑是先收集图中所有legend类型的 renderer若指定了legend_name则筛选出name legend_name的图例——找不到时抛出RuntimeError(cant find Legend instance with ... name)找到多个时抛出RuntimeError(found multiple Legend instances with ... name)若未指定名称则沿用图中只允许一个图例的传统约束否则提示用户用 name 区分图例并用 legend_name 参数将 renderer 指派到对应图例。典型用法区别于旧的p.legend单例模式from bokeh.plotting import figure p figure() p.add_layout(Legend(namefirst), right) p.add_layout(Legend(namesecond), right) p.circle(x, y, legend_labelfirst, legend_namefirst) p.square(x, y, legend_labelsecond, legend_namesecond)配合Legend.name属性开发者可以在同一张图中维护多个独立图例并精准控制每个 renderer 归属于哪个图例无需再手动拼接p.legend的 renderer 列表。序列化协议缓冲区压缩的底层实现3.8.0 为 Bokeh 序列化协议加入了 buffer如大型数值数组的压缩支持这对大数据集的前端传输有明显收益。其 Python 侧核心位于 src/bokeh/core/serialization.py 的Buffer数据类第 159-180 行dataclass class Buffer: id: ID data: bytes | memoryview def to_compressed_bytes(self) - bytes: level settings.compression_level() # Python 3.11/3.12 存在 mtime0 时 Gzip 头部 OS 字段不稳定的问题 # 因此这里使用 mtime1 以保证可复现输出 return gzip.compress(self.to_bytes(), mtime1, compresslevellevel) def to_base64(self) - str: return base64.b64encode(self.to_compressed_bytes()).decode(utf-8)对应地BokehJS 侧的解压逻辑位于 bokehjs/src/lib/core/util/buffer.tsbuffer_to_base64使用fflate的gzipSync(bytes, {mtime: 0})压缩后 base64 编码第 32-38 行注释说明固定mtime0是为了测试结果可复现base64_to_buffer则用gunzipSync解压还原第 40-43 行。压缩级别通过BOKEH_COMPRESSION_LEVEL环境变量控制默认值为 2src/bokeh/settings.py#L656 附近的compression_level设置即默认启用但级别偏低、速度优先。此外bokeh serve命令行也暴露了websocket_compression_level与websocket_compression_mem_level参数见 src/bokeh/command/subcommands/serve.py#L860-L876 的参数收集列表以及 src/bokeh/server/tornado.py 中对应的 WebSocket 压缩配置用于调整 WebSocket 通道自身的压缩级别。视觉与主题SVG 图标与 CSS 变量主题初探3.8.0 将原先的 PNG 图标全面转换为 SVG并对既有图标做了一轮整体刷新。仓库中可见佐证是 bokehjs/src/less/icons/ 目录下 83 个.svg图标文件它们由 bokehjs/src/less/icons.less 统一组织为图标字体/样式资源。SVG 化的收益在于任意分辨率下保持清晰、易于通过 CSS 着色与缩放、资源体积更小。同期引入的基于 CSS 变量的主题化属于初步支持preliminary support。相关 CSS 变量定义集中在 bokehjs/src/less/vars.less配合上文的DocumentConfig.color_schemeauto/light/dark可让 Bokeh UI 初步跟随系统或应用指定的明暗模式。值得强调的是该特性在 3.8.0 中仍处于早期阶段主题变量的覆盖面与稳定性会随后续版本逐步完善。BokehJS 性能改进与 TypeScript 5.9 构建升级3.8.0 还包含多项 BokehJS 性能改进涉及渲染管线与序列化相关路径以及将 bokehjs 构建系统升级至 TypeScript 5.9 的工程调整。TypeScript 版本升级主要影响库内部开发与构建对最终用户 API 透明。性能改进的细节分散在 bokehjs/src/lib 各模块中若需进一步定位可重点检索核心渲染core/visuals、models/glyphs与序列化core/util相关目录的近期改动。升级与验证建议升级方式通过pip install bokeh3.8.0安装对应版本运行bokeh serve前可通过BOKEH_COMPRESSION_LEVEL调整 buffer 压缩级别默认 2。快速验证新特性运行 examples/basic/annotations/size_bar.py 查看SizeBar效果为HoverTool组合filters/sort_by/limit观察密集散点图 tooltip 的数量与排序变化在 Bokeh Server 应用中通过doc.config开启重连并切换color_scheme测试断线恢复与通知展示。回归测试参考仓库的测试套件tests/unit/bokeh、bokehjs/test覆盖了上述模型属性与序列化路径升级后建议运行相关单元测试以确认与自定义扩展的兼容性。总体而言3.8.0 是一个体验与基建并重的版本面向用户的新交互能力HoverTool 三件套、SizeBar、legend_name直接提升了图表的可用性而会话重连、缓冲区压缩、SVG 图标与 CSS 变量主题则为更大规模、更可靠、更现代的应用形态打下了基础。开发者可以根据自身场景优先采用其中与业务最相关的若干项能力。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考