Bokeh 3.3.1 补丁版本解析从修复清单看 BokehJS 渲染与地图、色彩映射的底层实现【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh3.3.1是发布于 2023 年 11 月的补丁版本patch release主要修复了一批小的 bug/回归问题regressions与文档问题。本篇技术指南以官方发布说明 docs/bokeh/source/docs/releases/3.3.1.rst 为主体骨架逐一拆解 11 项变更的触发场景、修复思路并深入到 Bokeh 的 Python 模型层src/bokeh与 BokehJS 前端渲染层bokehjs/src/lib核实其底层实现帮助你在升级到 3.3.1 后准确理解每个修复所影响的代码路径。1. 版本定位一次聚焦回归修复的补丁发布与引入新特性的 minor 版本不同3.3.1的定位非常明确——修复 3.3.x 系列中暴露出的行为回归与文档问题。发布说明中明确写道Bokeh version3.3.1(Nov 2023) is a patch release that fixes a number of minor bugs/regressions and docs issues.这意味着如果你当前使用 3.3.0 并遇到下述任一症状地图瓦片加载失败、日期轴微秒格式化异常、Spinner 精度错误等3.3.1 就是应优先升级的目标版本。下面按前端组件/渲染 → 数据与映射 → 地理与时间 → WebGL四个维度组织这 11 项修复。2. 组件与渲染层的修复2.1 Spinner 精度修复PR 13078Spinner数值微调器在部分场景下会出现精度误差例如浮点步进累加后显示0.30000000000000004这类问题。该 PR 修复了 Spinner 在特定精度设置下的数值处理。从源码看Spinner 的步进逻辑位于 bokehjs/src/lib/models/widgets/spinner.ts长按按钮时通过setInterval以递增速率调用increment_with_increasing_rate(step)累加step键盘方向键ArrowUp/ArrowDown与翻页键PageUp/PageDown乘以page_step_multiplier最终都汇聚到increment(step)方法并在写入this.model.value前经过bound_value()做上下界约束。浮点累加场景正是该修复的核心作用域当step为小数如 0.1且连续触发长按累加时精度丢失会被放大3.3.1 针对此类情况修正了精度表现。2.2 更新子节点时递归执行 after_render()PR 13424after_render()是 BokehJS 中所有DOMView在渲染完成后执行后置逻辑如重新定位、布局修正的生命周期钩子。3.3.1 之前当父组件更新其子节点时子视图的after_render()可能不会被正确触发。修复的核心在于 bokehjs/src/lib/core/dom_view.ts 中的r_after_render()实现r_after_render(): void { for (const child_view of this.children_views()) { if (child_view instanceof DOMView) { child_view.r_after_render() } } this.after_render() this._was_built true }该方法会先递归遍历所有子视图并逐个调用其r_after_render()最后再执行自身的after_render()。而rerender()dom_view.ts在重新调用render()后也会立即调用r_after_render()。3.3.1 的修复正是确保这条递归链在更新 children的路径上也能完整执行避免子组件例如 bokehjs/src/lib/models/annotations/legend.ts 中重写的after_render在父级更新后遗漏后置处理。2.3 IconView 中连接 change 信号PR 13427IconView 是 BokehJS 中负责渲染图标Icon的视图。3.3.1 为其补上了change信号的连接使得图标模型属性变化时视图能够及时响应并重绘。这属于典型的信号-槽连接遗漏修复影响的是使用自定义图标如Icon组件的 UI 场景。2.4 Tooltip 在contain: strict下的定位问题PR 13431当页面 CSS 对某个容器设置了contain: strict或contain: paint/layout时浏览器的包含containment语义会改变元素的定位上下文导致 Bokeh 的 Tooltip 位置计算偏移。3.3.1 修复了 Tooltip 在此类 CSS 环境下的定位问题让 HoverTool 的提示框在布局被包含约束的宿主页面中依然能准确跟随光标/锚点。2.5 DataRangePicker 的日历点击行为改进PR 13466DataRangePicker日期范围选择器此前在日历上点击日期时的交互行为存在瑕疵如无法快速选择范围、点击反馈不正确。该 PR 改进了日历点击的交互流程使日期范围的选取更符合直觉。3. 数据、色彩映射与图元修复3.1 允许将非因子值映射到 nan_colorPR 13420这是 3.3.1 中比较有代表性的色彩映射修复。在CategoricalColorMapper中凡是不在factors列表中的值都会被映射到nan_color。修复前部分非因子non-factors输入无法正确落到nan_color而是可能抛出异常或产生意外颜色。Python 侧的模型定义位于 src/bokeh/models/mappers.pynan_color Color(defaultgray, help Color to be used if data is NaN or otherwise not mappable. )ColorMapper基类为所有色彩映射器统一提供nan_color默认gray而CategoricalColorMappermappers.py明确声明未出现在 factors 中的值将被映射到nan_color。同时当palette长度小于factors长度时_check_palette_length()校验mappers.py会发出PALETTE_LENGTH_FACTORS_MISMATCH警告并提示多余的因子将被分配给nan_color。实战含义升级到 3.3.1 后你可以放心地给分类数据传入未知类别值例如from bokeh.models import CategoricalColorMapper mapper CategoricalColorMapper( palette[red, blue, green], factors[foo, bar, baz], nan_colorlightgray, # 数据中出现 qux 等未知因子时显示浅灰 )未知因子不再破坏映射流程而是稳定回落到你指定的nan_color。3.2 ImageStack 数据在 HoverTool 提示中的正确解析PR 13454ImageStack是 Bokeh 3.3 引入的图元用于在单次绘制中渲染多层图像栈。此前 HoverTool 对ImageStack的数据解析不正确导致悬停提示无法显示正确的像素值。该 PR 修正了 HoverTool 对ImageStack数据的读取路径相关图元实现位于 bokehjs/src/lib/models/glyphs/image_stack.ts它继承自ImageBaseView其 hover 数据解析在 3.3.1 中与栈式数据结构对齐。3.3 RangeTool 覆盖层的节点唯一化PR 13457RangeToolbokehjs/src/lib/models/tools/gestures/range_tool.ts在关联两个坐标轴范围时会在副图上绘制覆盖层overlay。此前覆盖层的 DOM 节点可能在不同视图间被共享/复用造成样式或交互串扰。3.3.1 保证每个 overlay 使用唯一节点避免多视图下的节点冲突。4. 地图瓦片与时间格式化修复4.1 Stamen* 瓦片替换为 Stadia.Stamen*PR 13491Stamen 地图服务迁移到了 Stadia 平台原Stamen*瓦片 URL 已不再可用。3.3.1 将内置的 Stamen 瓦片源全部替换为Stadia.Stamen*系列。在 src/bokeh/models/tiles.py 的TileSource文档字符串中Stadia 已被列为主要的瓦片服务提供商之一Such companies as Google, MapQuest, Stadia, Esri, and OpenStreetMap provide...升级提示如果你在 3.3.0 中使用过WMTSTileSource指向 Stamen 瓦片需要同步将 URL 更新为 Stadia 域名如https://tiles.stadiamaps.com/tiles/stamen_toner/{Z}/{X}/{Y}.png。TileSource的通用配置url、tile_size、min_zoom、max_zoom、attribution等定义在 tiles.py替换服务商时只需更换url与attribution。4.2 %f 格式处理负微秒PR 13495%f是 Python 风格时间格式化指令表示微秒6 位小数。BokehJS 的DatetimeTickFormatter需要自行将%f翻译为 JS 可理解的微秒值——因为底层timezone库并不原生支持%f。修复前的 bug 在于当时间戳为负数1970 年之前时微秒计算会得到负值导致格式化结果错误。核心修复位于 bokehjs/src/lib/models/formatters/datetime_tick_formatter.ts 的_us()函数export function _us(t: number): number { // ... let us Math.round(((t / 1000) % 1) * 1000000) if (t 0.0) { us (1000000 us) % 1000000 } return us }对于 pre-epoch负数时间戳(1000000 us) % 1000000将微秒归一化到[0, 1000000)区间从而保证%f输出始终为非负的 6 位数字。随后_strftime()同文件 L79-L111通过正则/((^|[^%])(%%)*)%f/将%f指令替换为补零后的微秒串。实战含义当你的数据包含 1970 年之前的日期且轴刻度格式化器使用DatetimeTickFormatter默认的microseconds/seconds格式串如%fus、%Ss时3.3.1 确保刻度标签不会再出现负数微秒或%-000001之类的异常文本。5. WebGL 渲染修复宽高单边为 0 的标记点PR 13482Bokeh 的 WebGL 渲染后端bokehjs/src/lib下的 WebGL 实现在处理宽度和高度只有一个为 0的标记marker时3.3.1 之前可能产生异常的绘制结果如不渲染或渲染成异常形状。该 PR 修正了 WebGL 路径对这类退化尺寸标记的容错使其与 Canvas 后端行为一致。6. 升级与验证建议升级方式通过pip install --upgrade bokeh3.3.1或根据你的包管理器安装 3.3.1 版本BokehJS 随 Python 包一同分发无需单独安装。重点回归验证清单对应本文 2~5 节使用CategoricalColorMapper且数据含未知因子的图表——验证是否回落到nan_color日期轴包含 pre-epoch 时间戳——验证%f微秒格式化输出使用 Stamen 风格地图瓦片的TileRenderer——确认已切换至 Stadia.Stamen* URL包含Icon、DataRangePicker、RangeTooloverlay、ImageStack HoverTool 的组合页面——逐项确认交互与提示正常WebGL 渲染下宽或高为 0 的 marker——确认不再丢失绘制。7. 小结Bokeh 3.3.1 虽然规模不大但每一项修复都能在 src/bokeh/modelsPython 模型层与 bokehjs/src/lib前端渲染层中找到明确的实现落点从r_after_render()的递归调用链core/dom_view.ts到_us()对负时间戳微秒的归一化datetime_tick_formatter.ts再到nan_color在CategoricalColorMapper中的回退语义src/bokeh/models/mappers.py。对于从 3.3.0 升级的用户本文第 6 节的验证清单可以直接作为发布验收用例对于希望深入 Bokeh 渲染管线的读者这些修复点也是阅读 BokehJS 视图生命周期、时间格式化与 WebGL 绘制代码的绝佳入口。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Bokeh 3.3.1 补丁版本解析：从修复清单看 BokehJS 渲染与地图、色彩映射的底层实现
Bokeh 3.3.1 补丁版本解析从修复清单看 BokehJS 渲染与地图、色彩映射的底层实现【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh3.3.1是发布于 2023 年 11 月的补丁版本patch release主要修复了一批小的 bug/回归问题regressions与文档问题。本篇技术指南以官方发布说明 docs/bokeh/source/docs/releases/3.3.1.rst 为主体骨架逐一拆解 11 项变更的触发场景、修复思路并深入到 Bokeh 的 Python 模型层src/bokeh与 BokehJS 前端渲染层bokehjs/src/lib核实其底层实现帮助你在升级到 3.3.1 后准确理解每个修复所影响的代码路径。1. 版本定位一次聚焦回归修复的补丁发布与引入新特性的 minor 版本不同3.3.1的定位非常明确——修复 3.3.x 系列中暴露出的行为回归与文档问题。发布说明中明确写道Bokeh version3.3.1(Nov 2023) is a patch release that fixes a number of minor bugs/regressions and docs issues.这意味着如果你当前使用 3.3.0 并遇到下述任一症状地图瓦片加载失败、日期轴微秒格式化异常、Spinner 精度错误等3.3.1 就是应优先升级的目标版本。下面按前端组件/渲染 → 数据与映射 → 地理与时间 → WebGL四个维度组织这 11 项修复。2. 组件与渲染层的修复2.1 Spinner 精度修复PR 13078Spinner数值微调器在部分场景下会出现精度误差例如浮点步进累加后显示0.30000000000000004这类问题。该 PR 修复了 Spinner 在特定精度设置下的数值处理。从源码看Spinner 的步进逻辑位于 bokehjs/src/lib/models/widgets/spinner.ts长按按钮时通过setInterval以递增速率调用increment_with_increasing_rate(step)累加step键盘方向键ArrowUp/ArrowDown与翻页键PageUp/PageDown乘以page_step_multiplier最终都汇聚到increment(step)方法并在写入this.model.value前经过bound_value()做上下界约束。浮点累加场景正是该修复的核心作用域当step为小数如 0.1且连续触发长按累加时精度丢失会被放大3.3.1 针对此类情况修正了精度表现。2.2 更新子节点时递归执行 after_render()PR 13424after_render()是 BokehJS 中所有DOMView在渲染完成后执行后置逻辑如重新定位、布局修正的生命周期钩子。3.3.1 之前当父组件更新其子节点时子视图的after_render()可能不会被正确触发。修复的核心在于 bokehjs/src/lib/core/dom_view.ts 中的r_after_render()实现r_after_render(): void { for (const child_view of this.children_views()) { if (child_view instanceof DOMView) { child_view.r_after_render() } } this.after_render() this._was_built true }该方法会先递归遍历所有子视图并逐个调用其r_after_render()最后再执行自身的after_render()。而rerender()dom_view.ts在重新调用render()后也会立即调用r_after_render()。3.3.1 的修复正是确保这条递归链在更新 children的路径上也能完整执行避免子组件例如 bokehjs/src/lib/models/annotations/legend.ts 中重写的after_render在父级更新后遗漏后置处理。2.3 IconView 中连接 change 信号PR 13427IconView 是 BokehJS 中负责渲染图标Icon的视图。3.3.1 为其补上了change信号的连接使得图标模型属性变化时视图能够及时响应并重绘。这属于典型的信号-槽连接遗漏修复影响的是使用自定义图标如Icon组件的 UI 场景。2.4 Tooltip 在contain: strict下的定位问题PR 13431当页面 CSS 对某个容器设置了contain: strict或contain: paint/layout时浏览器的包含containment语义会改变元素的定位上下文导致 Bokeh 的 Tooltip 位置计算偏移。3.3.1 修复了 Tooltip 在此类 CSS 环境下的定位问题让 HoverTool 的提示框在布局被包含约束的宿主页面中依然能准确跟随光标/锚点。2.5 DataRangePicker 的日历点击行为改进PR 13466DataRangePicker日期范围选择器此前在日历上点击日期时的交互行为存在瑕疵如无法快速选择范围、点击反馈不正确。该 PR 改进了日历点击的交互流程使日期范围的选取更符合直觉。3. 数据、色彩映射与图元修复3.1 允许将非因子值映射到 nan_colorPR 13420这是 3.3.1 中比较有代表性的色彩映射修复。在CategoricalColorMapper中凡是不在factors列表中的值都会被映射到nan_color。修复前部分非因子non-factors输入无法正确落到nan_color而是可能抛出异常或产生意外颜色。Python 侧的模型定义位于 src/bokeh/models/mappers.pynan_color Color(defaultgray, help Color to be used if data is NaN or otherwise not mappable. )ColorMapper基类为所有色彩映射器统一提供nan_color默认gray而CategoricalColorMappermappers.py明确声明未出现在 factors 中的值将被映射到nan_color。同时当palette长度小于factors长度时_check_palette_length()校验mappers.py会发出PALETTE_LENGTH_FACTORS_MISMATCH警告并提示多余的因子将被分配给nan_color。实战含义升级到 3.3.1 后你可以放心地给分类数据传入未知类别值例如from bokeh.models import CategoricalColorMapper mapper CategoricalColorMapper( palette[red, blue, green], factors[foo, bar, baz], nan_colorlightgray, # 数据中出现 qux 等未知因子时显示浅灰 )未知因子不再破坏映射流程而是稳定回落到你指定的nan_color。3.2 ImageStack 数据在 HoverTool 提示中的正确解析PR 13454ImageStack是 Bokeh 3.3 引入的图元用于在单次绘制中渲染多层图像栈。此前 HoverTool 对ImageStack的数据解析不正确导致悬停提示无法显示正确的像素值。该 PR 修正了 HoverTool 对ImageStack数据的读取路径相关图元实现位于 bokehjs/src/lib/models/glyphs/image_stack.ts它继承自ImageBaseView其 hover 数据解析在 3.3.1 中与栈式数据结构对齐。3.3 RangeTool 覆盖层的节点唯一化PR 13457RangeToolbokehjs/src/lib/models/tools/gestures/range_tool.ts在关联两个坐标轴范围时会在副图上绘制覆盖层overlay。此前覆盖层的 DOM 节点可能在不同视图间被共享/复用造成样式或交互串扰。3.3.1 保证每个 overlay 使用唯一节点避免多视图下的节点冲突。4. 地图瓦片与时间格式化修复4.1 Stamen* 瓦片替换为 Stadia.Stamen*PR 13491Stamen 地图服务迁移到了 Stadia 平台原Stamen*瓦片 URL 已不再可用。3.3.1 将内置的 Stamen 瓦片源全部替换为Stadia.Stamen*系列。在 src/bokeh/models/tiles.py 的TileSource文档字符串中Stadia 已被列为主要的瓦片服务提供商之一Such companies as Google, MapQuest, Stadia, Esri, and OpenStreetMap provide...升级提示如果你在 3.3.0 中使用过WMTSTileSource指向 Stamen 瓦片需要同步将 URL 更新为 Stadia 域名如https://tiles.stadiamaps.com/tiles/stamen_toner/{Z}/{X}/{Y}.png。TileSource的通用配置url、tile_size、min_zoom、max_zoom、attribution等定义在 tiles.py替换服务商时只需更换url与attribution。4.2 %f 格式处理负微秒PR 13495%f是 Python 风格时间格式化指令表示微秒6 位小数。BokehJS 的DatetimeTickFormatter需要自行将%f翻译为 JS 可理解的微秒值——因为底层timezone库并不原生支持%f。修复前的 bug 在于当时间戳为负数1970 年之前时微秒计算会得到负值导致格式化结果错误。核心修复位于 bokehjs/src/lib/models/formatters/datetime_tick_formatter.ts 的_us()函数export function _us(t: number): number { // ... let us Math.round(((t / 1000) % 1) * 1000000) if (t 0.0) { us (1000000 us) % 1000000 } return us }对于 pre-epoch负数时间戳(1000000 us) % 1000000将微秒归一化到[0, 1000000)区间从而保证%f输出始终为非负的 6 位数字。随后_strftime()同文件 L79-L111通过正则/((^|[^%])(%%)*)%f/将%f指令替换为补零后的微秒串。实战含义当你的数据包含 1970 年之前的日期且轴刻度格式化器使用DatetimeTickFormatter默认的microseconds/seconds格式串如%fus、%Ss时3.3.1 确保刻度标签不会再出现负数微秒或%-000001之类的异常文本。5. WebGL 渲染修复宽高单边为 0 的标记点PR 13482Bokeh 的 WebGL 渲染后端bokehjs/src/lib下的 WebGL 实现在处理宽度和高度只有一个为 0的标记marker时3.3.1 之前可能产生异常的绘制结果如不渲染或渲染成异常形状。该 PR 修正了 WebGL 路径对这类退化尺寸标记的容错使其与 Canvas 后端行为一致。6. 升级与验证建议升级方式通过pip install --upgrade bokeh3.3.1或根据你的包管理器安装 3.3.1 版本BokehJS 随 Python 包一同分发无需单独安装。重点回归验证清单对应本文 2~5 节使用CategoricalColorMapper且数据含未知因子的图表——验证是否回落到nan_color日期轴包含 pre-epoch 时间戳——验证%f微秒格式化输出使用 Stamen 风格地图瓦片的TileRenderer——确认已切换至 Stadia.Stamen* URL包含Icon、DataRangePicker、RangeTooloverlay、ImageStack HoverTool 的组合页面——逐项确认交互与提示正常WebGL 渲染下宽或高为 0 的 marker——确认不再丢失绘制。7. 小结Bokeh 3.3.1 虽然规模不大但每一项修复都能在 src/bokeh/modelsPython 模型层与 bokehjs/src/lib前端渲染层中找到明确的实现落点从r_after_render()的递归调用链core/dom_view.ts到_us()对负时间戳微秒的归一化datetime_tick_formatter.ts再到nan_color在CategoricalColorMapper中的回退语义src/bokeh/models/mappers.py。对于从 3.3.0 升级的用户本文第 6 节的验证清单可以直接作为发布验收用例对于希望深入 Bokeh 渲染管线的读者这些修复点也是阅读 BokehJS 视图生命周期、时间格式化与 WebGL 绘制代码的绝佳入口。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考