Bokeh 3.8.1 补丁发布解析$name占位符恢复与replace_placeholders()模板引擎改进【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh本篇基于 Bokeh 官方发布说明 docs/bokeh/source/docs/releases/3.8.1.rst 编写聚焦 3.8.1 补丁版本的两项核心变更——恢复$name间接列名占位符支持、改进replace_placeholders()占位符替换实现并结合仓库源码BokehJS 模板引擎、HoverTool 与 OpenURL 的实现及单元测试深入讲解其底层原理与实际用法。读完本文你将理解 Bokeh hover 工具提示tooltip占位符体系的工作机制并能在自己的图表中正确使用$name、自定义格式化与safe格式等能力。版本概览一次聚焦回归修复的补丁发布Bokeh3.8.12025 年 11 月是一个补丁版本patch release其定位是修复 3.8.0 以来引入的一批小 bug、回归问题regressions以及文档问题不包含破坏性变更。官方发布说明共列出两项变更恢复对$name的支持并改进replace_placeholders()对应 PR 14652文档构建的回归修复尤其是 Windows 平台上的文档构建问题对应 PR 14627、14625虽然变更清单很短但第一项直接触及 Bokeh 前端BokehJS中 hover 工具提示与回调模板渲染的核心逻辑。下面我们以源码为据逐项展开。变更一恢复$name间接列名占位符什么是$name在 Bokeh 的 HoverTool 中tooltips字段名以开头时表示引用ColumnDataSource中的列column。例如price会在鼠标悬停时显示price列对应行即被悬停的第 17 个 glyph 对应的第 17 个数据值的值当列名包含空格时需要用花括号包裹如{adjusted close}。$name则是一个特殊的间接引用它不会直接指定列名而是先读取被悬停 glyph renderer 的name属性再把该值作为列名去数据源中取值。官方文档在 src/bokeh/models/tools.py 中对此有明确描述The field name$nameis distinguished in that it will look up thenamefield on the hovered glyph renderer, and use that value as the column name. For instance, if a user hovers with the nameUS East, then$nameis equivalent to{US East}.也就是说当悬停的 glyph renderer 的name为US East时$name等价于{US East}。这一能力在**堆叠图stacked charts**等需要根据 renderer 名称动态切换数据列的场景中尤其有价值——把 renderer 的name与数据列名建立约定就无需为每个 renderer 手写独立的 tooltip。源码中的实现证据$name的解析逻辑位于 BokehJS 的模板引擎 bokehjs/src/lib/core/util/templating.ts。该文件定义了三种占位符类型并在get_value()中按类型分发type PlaceholderType $ | | $ export function get_value(type: PlaceholderType, name: string, data_source: ColumnarDataSource, index: Index | null, vars: Vars) { switch (type) { case $: return _get_special_value(name, vars) case : return _get_column_value(name, data_source, index) case $: return name name isString(vars.name) ? _get_column_value(vars.name, data_source, index) : null } }可以清楚地看到$xxx走_get_special_value()读取的是special_vars中的特殊变量如$x、$y、$sx、$sy、$index、$name等这在 src/bokeh/models/tools.py 中有完整清单xxx走_get_column_value()直接以name作为列名在data_source中取数支持普通索引、ImageIndex图像索引、多维数组切片等多种情形$name是特例仅当name name且vars.name是字符串时才把vars.name当作列名执行列取值否则返回null在渲染阶段null会显示为???缺失标记见同文件的MISSING常量。vars.name正是被悬停 glyph renderer 的name属性。在 bokehjs/src/lib/models/tools/inspectors/hover_tool.tsx 中HoverToolView.render_entries()为每个被命中的 glyph 构造vars时都注入了name: renderer.name。单元测试的佐证BokehJS 的测试 bokehjs/test/unit/core/util/templating.ts 专门覆盖了这一回归场景it(should handle special $name case by using special_vars.name as the column, () { const s tmpl.replace_placeholders(stuff $name, source, 0, {}, {name: foo})即在special_vars.name foo的前提下字符串stuff $name应被替换为stuff foo 列第 0 行的值。同一文件中bokehjs/test/unit/core/util/templating.ts还有对process_placeholders的解析级断言验证$name与${name}两种写法都会被解析为type $、name name的占位符结构从而保证替换管线行为一致。实战示例堆叠图按 renderer 名称动态取列结合上述机制一个典型用法是为每个堆叠的vbar_stack段设置与数据列同名的nametooltip 统一使用$namefrom bokeh.plotting import figure, show from bokeh.models import ColumnDataSource, HoverTool from bokeh.transform import dodge source ColumnDataSource(data{ year: [2019, 2020, 2021], US East: [100, 110, 120], US West: [80, 90, 95], }) p figure(x_range[2019, 2020, 2021], height300) p.vbar_stack( [US East, US West], xyear, width0.5, color[#c9d9d3, #718dbf], sourcesource, name[US East, US West], legend_label[US East, US West], ) p.add_tools(HoverTool(tooltips[ (Year, year), (Region, $name), (Value, $name), ])) show(p)当鼠标悬停到nameUS East的柱子段时$name会自动等价于{US East}显示该列当前年份的值。这正是 3.8.1 恢复的能力如果回归未被修复$name会解析失败并回退为???。变更二replace_placeholders()占位符替换引擎的改进占位符语法与正则实现replace_placeholders()是 BokehJS 中所有工具提示与回调字符串模板的通用入口位于 bokehjs/src/lib/core/util/templating.ts。它支持的占位符语法在同文件注释中有精确定义bokehjs/src/lib/core/util/templating.ts简单变量$x、x后跟 Unicode 字母、数字或下划线因此支持słowa_0、Wörter这类非 ASCII 列名完整变量/列名含空格${one two}、{one two}花括号内可以是除花括号外的任意内容可选格式后缀$x{format}、${x}{format}、x{format}、{one two}{format}对应的解析正则位于 bokehjs/src/lib/core/util/templating.tsconst regex /(\$||\$)((?:[\p{Letter}\p{Number}_])|(?:\{(?:[^{}])\}))(?:\{([^{}])\})?/gu注意(\$||\$)中的备选顺序$必须先于匹配否则$name会被误拆成 列名$name。这是$name能正确工作的语法基础也是本次修复的关键点之一。process_placeholders()bokehjs/src/lib/core/util/templating.ts负责按该正则扫描文本对每个匹配调用回调fn(type, name, format, i, spec)将占位符替换为回调返回值回调返回null/undefined时统一替换为???MISSING。replace_placeholders()在此基础上完成取值、格式化与 HTML 编码取值为null时显示???数值为NaN时显示NaN通过get_formatter()bokehjs/src/lib/core/util/templating.ts选择格式化器——内置的raw、basic、numeral、datetime、printf五种对应DEFAULT_FORMATTERS或由formatters参数传入的CustomJSHover自定义格式化器支持{safe}格式跳过 HTML 转义直接把数据值作为 HTML 渲染replace_placeholders_html与replace_placeholders中均有此分支最终结果如果是纯文本则返回字符串若含 HTML 则通过DOMParser解析为 DOM 节点数组返回。应用场景一HoverTool 提示渲染在 bokehjs/src/lib/models/tools/inspectors/hover_tool.tsx 中HoverToolView._render_vdom()对每条(label, value)提示对调用replace_placeholders_html()完成模板替换并支持$swatch/$color颜色特殊语法。因此官方文档src/bokeh/models/tools.py中列出的格式化写法都可以直接使用foo{0,0.000} # 将 10000.1234 格式化为: 10,000.123 foo{(.00)} # 将 -10000.1234 格式化为: (10000.123) foo{($ 0.00 a)} # 将 1230974 格式化为: $ 1.23 m foo{safe} # 不转义 foo 列中的 HTML 标签直接渲染同时HoverTool.formatters属性src/bokeh/models/tools.py允许按列指定格式化方案tool.formatters {date: datetime}支持numeral、datetime、printf以及CustomJSHover实例。应用场景二OpenURL 回调的 URL 模板replace_placeholders()同样驱动着OpenURL回调点击选中点后跳转 URL。在 bokehjs/src/lib/models/callbacks/open_url.ts 中execute(_cb_obj: unknown, {source}: {source: ColumnarDataSource}): void { const open_url (i: number) { const url replace_placeholders(this.url, source, i, undefined, undefined, encodeURI) if (!isString(url)) { throw new Error(HTML output is not supported in this context) } this.navigate(url) } // ...遍历 selected.indices / selected.line_indices 逐个打开 }这里replace_placeholders的最后一个参数传入了encodeURI即对替换结果做 URL 编码同时它显式要求返回值为字符串若模板中含有safe等导致 HTML 输出的情况会抛出错误。用法示例from bokeh.models import OpenURL, TapTool url OpenURL(urlhttps://example.com/detail?ididregion{US East}) p.add_tools(TapTool(callbackurl))3.8.1 对replace_placeholders()的改进确保了这类模板在含$name等复合占位符时也能被正确解析与替换而不会因解析器回归导致跳转 URL 出现字面量$name。变更三文档构建回归修复尤其针对 Windows发布说明的第二项变更涉及文档构建documentation build的回归修复对应 PR 14627 与 14625重点覆盖Windows 平台。这类问题通常表现为文档构建脚本对路径分隔符、大小写敏感文件名或 shell 语义的假设在 Windows 上不成立导致 Sphinx 构建失败或生成内容不一致。仓库中的文档工程位于 docs/bokeh入口包括conf.py、Makefile与make.bat——make.bat的存在本身就说明该项目需要同时支持 Windows 与 Unix 两套构建入口。相关发布说明文件全部集中在 docs/bokeh/source/docs/releases 目录本次修复即是对该构建管线的回归修补。由于该变更属于工程维护性质对最终用户的功能 API 无影响升级后最直观的收益是在 Windows 环境从源码构建官方文档包括本发布说明页面时不再遇到中断。如何验证与跟进查看版本升级后可通过python -c import bokeh; print(bokeh.__version__)确认版本为3.8.1版本号由 src/bokeh/init.py 与 bokehjs/src/lib/version.ts 定义。复现$name行为直接运行上文堆叠图示例将鼠标悬停在不同分段上观察 tooltip 的Value行是否随 renderer 名称切换数据列若切换正常即说明修复生效。阅读测试$name与占位符解析的回归测试位于 bokehjs/test/unit/core/util/templating.ts覆盖了replace_placeholders与process_placeholders两条路径是理解该修复行为边界的第一手资料。阅读引擎源码模板替换的全部实现集中在 bokehjs/src/lib/core/util/templating.ts包含占位符正则、取值分派、格式化器与 HTML 安全处理可作为深入理解 Bokeh tooltip 机制的入口。官方文档入口HoverTool 的完整属性说明tooltips、formatters、$特殊变量清单、列引用与$name语义见 src/bokeh/models/tools.py。小结Bokeh 3.8.1 作为 3.8 系列的首个补丁版本体量虽小但$name的恢复与replace_placeholders()的改进触及了 Bokeh 前端模板引擎的解析核心$name通过renderer 名称即列名的间接寻址为堆叠图等动态列场景提供了统一的 tooltip 写法而replace_placeholders()则统一承载了 hover 提示、OpenURL 跳转等场景的占位符解析、格式化与转义职责。配合 bokehjs/test/unit/core/util/templating.ts 中的回归测试可以确信这两处行为在后续版本中持续受保护。对于从 3.8.0 升级的用户这是一次低成本、低风险的平滑升级。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考