Bokeh 3.3.2 补丁版本深度解析BoxAnnotation 默认值回退、bokehjs 算法库性能回归修复与 mypy 1.7 升级【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 3.3.22023 年 11 月发布是一个针对 3.3 系列的小型补丁版本patch release核心工作是修复少量 bug/回归regressions与文档问题未引入任何新特性。本文以官方发布说明 docs/bokeh/source/docs/releases/3.3.2.rst 为骨架逐一剖析三项变更的来龙去脉并结合当前仓库中的 Python 与 bokehjs TypeScript 源码、配置与测试文件深入讲解其底层实现与对日常开发的实际影响。读完本文你将清楚理解本次补丁版本动了哪些代码、为什么改、以及在使用 Bokeh 时如何规避相关坑点。版本概况与定位Bokeh3.3.2于 2023 年 11 月发布属于补丁版本patch release。根据官方发布说明本次发布的唯一目标就是修复 3.3 系列引入的少量 bug/回归以及文档问题因此不包含新功能API 层面与 3.3.1 完全兼容升级不会破坏既有代码修复集中在三个方向bokehjs 算法库的性能回归、BoxAnnotation交互相关属性默认值的回退、以及 Python 侧类型检查工具 mypy 的升级与类型问题修复升级建议凡是正在使用 3.3.x 系列的用户都建议升级到 3.3.2正在使用 3.3.0/3.3.1 且大量使用BoxAnnotation可编辑交互或依赖 bokehjs 图形边界计算的用户尤其值得关注。修复一bokehjs 算法库algorithms library的性能回归回归背景官方发布说明指出本次修复了 bokehjs 的algorithms库中的性能回归performance regression对应 PR 为#13543。这里的algorithms库在仓库中的实际位置是 bokehjs/src/lib/core/util/algorithms.ts。底层实现什么是“算法库”algorithms.ts并非一套复杂的通用算法框架而是专门服务于 bokehjs 渲染引擎的图形边界计算bounding box工具集其中最关键的两个导出函数是qbb(x0, y0, cx, cy, x1, y1)计算二次贝塞尔曲线quadratic Bézier的包围盒。核心思路是若控制点落在起点与终点之间则直接采用线性包围盒否则按公式bound u(1-t)^2 2v(1-t)t wt^2其中t (u - v) / (u - 2v w)计算极值点再对[起点, 终点, 极值]取最小/最大值。源码中还特别处理了v (u w)/2的退化情形此时直接返回[u, w]。cbb(x0, y0, cx0, cy0, cx1, cy1, x1, y1)计算三次贝塞尔曲线cubic Bézier的包围盒。实现上先构造关于参数t的一元二次方程并加入数值鲁棒性处理当系数a的绝对值小于1e-12时按线性方程退化处理随后用判别式b² - 4ac判断实根收集位于(0, 1)区间的t值再求极值点包围盒。// bokehjs/src/lib/core/util/algorithms.ts节选 export function qbb(x0, y0, cx, cy, x1, y1): Rect { function _qbb(u, v, w): [number, number] { if (v (u w)/2) { return [u, w] // 退化情形直接返回线性边界 } else { const t (u - v) / (u - 2*v w) // 极值参数 const bd u*(1 - t)**2 2*v*(1 - t)*t w*t**2 return [min(u, w, bd), max(u, w, bd)] } } // ... }这两个函数在 bokehjs 渲染管线中会被高频调用凡是涉及贝塞尔曲线图形例如样条曲线、部分复合字形路径的包围盒计算最终都会落到这里。因此即使一次回归只让单次计算多出常数级开销在大量曲线图形同时渲染的场景下也会被放大成肉眼可见的卡顿——这正是 3.3.1 中该回归被标记为“性能回归”的原因。修复影响与验证思路修复本身是纯计算逻辑的恢复/优化不改变qbb/cbb的输入输出语义因此图形渲染结果位置、边界应与 3.3.0 保持一致曲线密集场景如大数据量折线图、平滑路径标注的交互帧率应得到恢复若你曾在 3.3.1 上观察到曲线图形拖拽/缩放时明显掉帧升级 3.3.2 后应显著改善。修复二回退 BoxAnnotation.{left,right,top,bottom} 默认值变更回归背景这是本次补丁中对用户 API 影响最直接的一项官方将 3.3.x 中变更过的BoxAnnotation的left、right、top、bottom四个坐标属性的默认值**回退Reverted**到之前的版本对应 PR 为#13468。默认值现状与源码一一对应当前仓库中Python 侧模型定义位于 src/bokeh/models/annotations/geometry.py第 152 行起bokehjs 侧位于 bokehjs/src/lib/models/annotations/box_annotation.ts第 926 行起。两侧定义完全一致属性Python 默认值geometry.pybokehjs 默认值box_annotation.ts含义leftNode.frame.leftnew Node({target: frame, symbol: left})框左边缘的 x 坐标rightNode.frame.rightnew Node({target: frame, symbol: right})框右边缘的 x 坐标topNode.frame.topnew Node({target: frame, symbol: top})框顶边缘的 y 坐标bottomNode.frame.bottomnew Node({target: frame, symbol: bottom})框底边缘的 y 坐标也就是说回退之后四个属性默认绑定到绘图区域frame的四条边并且left_units/right_units/top_units/bottom_units均默认为data数据单位。Python 侧还保留了显式的兼容转换left Coordinate(defaultlambda: Node.frame.left, help...).accepts(Null, lambda _: Node.frame.left)这意味着即使显式传入None也会被统一转换为Node.frame.left不会产生悬空的坐标值。对用户代码的实战影响理解这次回退的关键在于默认值决定了“不指定坐标时画出来的框有多大”。回退后默认的BoxAnnotation()只设置fill_color等视觉属性、不指定坐标会铺满整个绘图区域这与 Bokeh 3.2 及更早版本的既有行为一致若 3.3.0/3.3.1 中曾短暂引入不同的默认值例如默认不铺满、或使用空值会导致用户升级后看到框的位置/大小异常本次回退正是为了消除这种升级破坏实际使用中仍建议显式指定坐标例如BoxAnnotation(left2, right4, top8, bottom6)用于标记数据区间若只想框住整个画布做“背景遮罩”则可以完全不传坐标借助默认的Node.frame.*行为实现。相关交互属性实验性扩展一览由于本次回退与 BoxAnnotation 的交互能力同属一个演进方向这里结合 geometry.py 第 219–318 行源码把该模型当前提供的能力一并列出这些属性在源码中均明确标注为experimental可能随时变化生产使用需谨慎editable默认False是否允许交互式修改框的几何形状resizable默认all配合editable控制允许调整哪些边/角sides/cornersmovable默认both控制框可以被拖动的方向symmetric默认False是否围绕中心而非对角进行缩放min_width/min_height/max_width/max_height框尺寸的上下限约束left_limit/right_limit/top_limit/bottom_limit四个方向上的移动边界限制border_radius圆角支持use_handles默认False与handles是否显示交互手柄move/resize以及手柄的外观配置。其中handles的类型是BoxInteractionHandlesgeometry.py 第 113 行起默认值为DEFAULT_BOX_ANNOTATION_HANDLES第 140 行起其视觉规格为白色填充fill_colorwhite、fill_alpha1.0、黑色描边line_colorblack、line_alpha1.0、悬停时浅灰填充hover_fill_colorlightgray。handles的配置采用逐级细化的覆盖机制all→move/resize→sides/corners→ 具体边/角每一级若定义了都会覆盖更泛化的设置同时它也接受AreaVisuals会自动包装为BoxInteractionHandles(allobj)。bokehjs 侧的对应默认值同样可以从 box_annotation.ts 第 950–979 行确认如top: [CoordinateLike, () new Node({target: frame, symbol: top})]、editable: [Bool, false]、resizable: [Box.Resizable, all]等Python 与前端两侧保持严格同步。修复三升级 mypy 至 1.7 并修复类型问题变更内容第三项变更将项目 Python 侧使用的类型检查工具 mypy 从旧版本升级到1.7并顺带修复了升级后暴露出来的类型问题对应 PR 为#13534。发布说明中的表述是 Upgraded mypy to version 1.7 and fixed type issues。仓库中的证据当前仓库的依赖声明位于 pixi.toml其中第 86 行与第 156 行均声明mypy 1.20说明项目采用的 Pixi 环境锁定的 mypy 版本约束已经高于 1.7仓库会持续向前演进类型检查配置位于 pyproject.toml 的[tool.mypy]段第 138 行起其中设置了mypy_path src/typings/并包含多个[[tool.mypy.overrides]]第 209、234 行起用于对特定模块做细粒度的类型检查策略覆盖仓库还维护了与 mypy 强相关的类型存根文件目录 src/typings内含IPython、cartopy、playwright、selenium等第三方库的.pyi存根以及源码中的.pyi模型声明如 src/bokeh/models/annotations/geometry.pyi。对开发者的意义对最终用户这是纯开发工具链变更不改变运行时行为发布说明中同时修复的类型问题type issues属于源码内部质量改进不影响 Bokeh 的 API 与渲染结果对贡献者在本地开发时需保证 mypy 版本满足仓库要求参考 pixi.toml 的1.20约束并遵循 pyproject.toml 中[tool.mypy]的路径与覆盖配置仓库的 CI 类型检查任务与 tests/codebase 下的测试脚本共同保证类型卫生。如何在当前仓库中验证这些变更仓库是只读的你可以通过以下方式在本地观察本次补丁涉及的代码现状查看 BoxAnnotation 默认值直接阅读 src/bokeh/models/annotations/geometry.py 第 152–318 行逐一核对left/right/top/bottom及其交互属性的默认值与注释前端对照 bokehjs/src/lib/models/annotations/box_annotation.ts 第 950–979 行的this.define块。查看算法库实现阅读 bokehjs/src/lib/core/util/algorithms.ts 中的qbb与cbb函数理解包围盒计算逻辑含数值鲁棒性分支即可还原本次性能回归修复的代码上下文。查看类型检查配置阅读 pyproject.toml 的[tool.mypy]段与 pixi.toml 中的mypy版本约束了解项目当前的类型检查基线。一个简单的运行验证Python 侧from bokeh.models import BoxAnnotation # 不指定坐标时四个边默认绑定到绘图区域 frame box BoxAnnotation() print(box.left, box.right, box.top, box.bottom) # Node(frame.left) 等 # 显式指定数据区间坐标覆盖默认的 frame 绑定 box2 BoxAnnotation(left2, right4, top8, bottom6)升级到 3.3.2 后上述默认行为即与 3.2.x 系列一致不会再出现因 3.3.0/3.3.1 默认值变更导致的框位置漂移。升级建议与总结升级路径3.3.2 是纯补丁版本与 3.3.x 系列完全兼容建议直接升级跨大版本升级如 3.2 → 3.3.2也安全但需留意BoxAnnotation交互类属性均为实验性 API。重点关注回归风险如果项目中大量使用BoxAnnotation并依赖“不传坐标即铺满绘图区”的旧行为本次回退正是针对你的场景升级即修复如果曾针对 3.3.0/3.3.1 的异常默认值写过 workaround升级后请移除这些补丁代码。性能收益若在 3.3.1 上遇到曲线图形渲染/交互卡顿本次 bokehjs 算法库修复值得立即跟进。类型检查作为最终用户无需关注 mypy 变更作为贡献者请确保本地 mypy 满足 pixi.toml 中的版本要求并遵循 pyproject.toml 的类型检查配置。总体而言3.3.2 是一次“小而稳”的维护版本它没有新特性但通过回退破坏性默认值、修复渲染性能回归、升级类型检查工具链让 3.3 系列回归到稳定可靠的状态是 3.3 用户应当尽快采用的一个版本。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Bokeh 3.3.2 补丁版本深度解析：BoxAnnotation 默认值回退、bokehjs 算法库性能回归修复与 mypy 1.7 升级
Bokeh 3.3.2 补丁版本深度解析BoxAnnotation 默认值回退、bokehjs 算法库性能回归修复与 mypy 1.7 升级【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokehBokeh 3.3.22023 年 11 月发布是一个针对 3.3 系列的小型补丁版本patch release核心工作是修复少量 bug/回归regressions与文档问题未引入任何新特性。本文以官方发布说明 docs/bokeh/source/docs/releases/3.3.2.rst 为骨架逐一剖析三项变更的来龙去脉并结合当前仓库中的 Python 与 bokehjs TypeScript 源码、配置与测试文件深入讲解其底层实现与对日常开发的实际影响。读完本文你将清楚理解本次补丁版本动了哪些代码、为什么改、以及在使用 Bokeh 时如何规避相关坑点。版本概况与定位Bokeh3.3.2于 2023 年 11 月发布属于补丁版本patch release。根据官方发布说明本次发布的唯一目标就是修复 3.3 系列引入的少量 bug/回归以及文档问题因此不包含新功能API 层面与 3.3.1 完全兼容升级不会破坏既有代码修复集中在三个方向bokehjs 算法库的性能回归、BoxAnnotation交互相关属性默认值的回退、以及 Python 侧类型检查工具 mypy 的升级与类型问题修复升级建议凡是正在使用 3.3.x 系列的用户都建议升级到 3.3.2正在使用 3.3.0/3.3.1 且大量使用BoxAnnotation可编辑交互或依赖 bokehjs 图形边界计算的用户尤其值得关注。修复一bokehjs 算法库algorithms library的性能回归回归背景官方发布说明指出本次修复了 bokehjs 的algorithms库中的性能回归performance regression对应 PR 为#13543。这里的algorithms库在仓库中的实际位置是 bokehjs/src/lib/core/util/algorithms.ts。底层实现什么是“算法库”algorithms.ts并非一套复杂的通用算法框架而是专门服务于 bokehjs 渲染引擎的图形边界计算bounding box工具集其中最关键的两个导出函数是qbb(x0, y0, cx, cy, x1, y1)计算二次贝塞尔曲线quadratic Bézier的包围盒。核心思路是若控制点落在起点与终点之间则直接采用线性包围盒否则按公式bound u(1-t)^2 2v(1-t)t wt^2其中t (u - v) / (u - 2v w)计算极值点再对[起点, 终点, 极值]取最小/最大值。源码中还特别处理了v (u w)/2的退化情形此时直接返回[u, w]。cbb(x0, y0, cx0, cy0, cx1, cy1, x1, y1)计算三次贝塞尔曲线cubic Bézier的包围盒。实现上先构造关于参数t的一元二次方程并加入数值鲁棒性处理当系数a的绝对值小于1e-12时按线性方程退化处理随后用判别式b² - 4ac判断实根收集位于(0, 1)区间的t值再求极值点包围盒。// bokehjs/src/lib/core/util/algorithms.ts节选 export function qbb(x0, y0, cx, cy, x1, y1): Rect { function _qbb(u, v, w): [number, number] { if (v (u w)/2) { return [u, w] // 退化情形直接返回线性边界 } else { const t (u - v) / (u - 2*v w) // 极值参数 const bd u*(1 - t)**2 2*v*(1 - t)*t w*t**2 return [min(u, w, bd), max(u, w, bd)] } } // ... }这两个函数在 bokehjs 渲染管线中会被高频调用凡是涉及贝塞尔曲线图形例如样条曲线、部分复合字形路径的包围盒计算最终都会落到这里。因此即使一次回归只让单次计算多出常数级开销在大量曲线图形同时渲染的场景下也会被放大成肉眼可见的卡顿——这正是 3.3.1 中该回归被标记为“性能回归”的原因。修复影响与验证思路修复本身是纯计算逻辑的恢复/优化不改变qbb/cbb的输入输出语义因此图形渲染结果位置、边界应与 3.3.0 保持一致曲线密集场景如大数据量折线图、平滑路径标注的交互帧率应得到恢复若你曾在 3.3.1 上观察到曲线图形拖拽/缩放时明显掉帧升级 3.3.2 后应显著改善。修复二回退 BoxAnnotation.{left,right,top,bottom} 默认值变更回归背景这是本次补丁中对用户 API 影响最直接的一项官方将 3.3.x 中变更过的BoxAnnotation的left、right、top、bottom四个坐标属性的默认值**回退Reverted**到之前的版本对应 PR 为#13468。默认值现状与源码一一对应当前仓库中Python 侧模型定义位于 src/bokeh/models/annotations/geometry.py第 152 行起bokehjs 侧位于 bokehjs/src/lib/models/annotations/box_annotation.ts第 926 行起。两侧定义完全一致属性Python 默认值geometry.pybokehjs 默认值box_annotation.ts含义leftNode.frame.leftnew Node({target: frame, symbol: left})框左边缘的 x 坐标rightNode.frame.rightnew Node({target: frame, symbol: right})框右边缘的 x 坐标topNode.frame.topnew Node({target: frame, symbol: top})框顶边缘的 y 坐标bottomNode.frame.bottomnew Node({target: frame, symbol: bottom})框底边缘的 y 坐标也就是说回退之后四个属性默认绑定到绘图区域frame的四条边并且left_units/right_units/top_units/bottom_units均默认为data数据单位。Python 侧还保留了显式的兼容转换left Coordinate(defaultlambda: Node.frame.left, help...).accepts(Null, lambda _: Node.frame.left)这意味着即使显式传入None也会被统一转换为Node.frame.left不会产生悬空的坐标值。对用户代码的实战影响理解这次回退的关键在于默认值决定了“不指定坐标时画出来的框有多大”。回退后默认的BoxAnnotation()只设置fill_color等视觉属性、不指定坐标会铺满整个绘图区域这与 Bokeh 3.2 及更早版本的既有行为一致若 3.3.0/3.3.1 中曾短暂引入不同的默认值例如默认不铺满、或使用空值会导致用户升级后看到框的位置/大小异常本次回退正是为了消除这种升级破坏实际使用中仍建议显式指定坐标例如BoxAnnotation(left2, right4, top8, bottom6)用于标记数据区间若只想框住整个画布做“背景遮罩”则可以完全不传坐标借助默认的Node.frame.*行为实现。相关交互属性实验性扩展一览由于本次回退与 BoxAnnotation 的交互能力同属一个演进方向这里结合 geometry.py 第 219–318 行源码把该模型当前提供的能力一并列出这些属性在源码中均明确标注为experimental可能随时变化生产使用需谨慎editable默认False是否允许交互式修改框的几何形状resizable默认all配合editable控制允许调整哪些边/角sides/cornersmovable默认both控制框可以被拖动的方向symmetric默认False是否围绕中心而非对角进行缩放min_width/min_height/max_width/max_height框尺寸的上下限约束left_limit/right_limit/top_limit/bottom_limit四个方向上的移动边界限制border_radius圆角支持use_handles默认False与handles是否显示交互手柄move/resize以及手柄的外观配置。其中handles的类型是BoxInteractionHandlesgeometry.py 第 113 行起默认值为DEFAULT_BOX_ANNOTATION_HANDLES第 140 行起其视觉规格为白色填充fill_colorwhite、fill_alpha1.0、黑色描边line_colorblack、line_alpha1.0、悬停时浅灰填充hover_fill_colorlightgray。handles的配置采用逐级细化的覆盖机制all→move/resize→sides/corners→ 具体边/角每一级若定义了都会覆盖更泛化的设置同时它也接受AreaVisuals会自动包装为BoxInteractionHandles(allobj)。bokehjs 侧的对应默认值同样可以从 box_annotation.ts 第 950–979 行确认如top: [CoordinateLike, () new Node({target: frame, symbol: top})]、editable: [Bool, false]、resizable: [Box.Resizable, all]等Python 与前端两侧保持严格同步。修复三升级 mypy 至 1.7 并修复类型问题变更内容第三项变更将项目 Python 侧使用的类型检查工具 mypy 从旧版本升级到1.7并顺带修复了升级后暴露出来的类型问题对应 PR 为#13534。发布说明中的表述是 Upgraded mypy to version 1.7 and fixed type issues。仓库中的证据当前仓库的依赖声明位于 pixi.toml其中第 86 行与第 156 行均声明mypy 1.20说明项目采用的 Pixi 环境锁定的 mypy 版本约束已经高于 1.7仓库会持续向前演进类型检查配置位于 pyproject.toml 的[tool.mypy]段第 138 行起其中设置了mypy_path src/typings/并包含多个[[tool.mypy.overrides]]第 209、234 行起用于对特定模块做细粒度的类型检查策略覆盖仓库还维护了与 mypy 强相关的类型存根文件目录 src/typings内含IPython、cartopy、playwright、selenium等第三方库的.pyi存根以及源码中的.pyi模型声明如 src/bokeh/models/annotations/geometry.pyi。对开发者的意义对最终用户这是纯开发工具链变更不改变运行时行为发布说明中同时修复的类型问题type issues属于源码内部质量改进不影响 Bokeh 的 API 与渲染结果对贡献者在本地开发时需保证 mypy 版本满足仓库要求参考 pixi.toml 的1.20约束并遵循 pyproject.toml 中[tool.mypy]的路径与覆盖配置仓库的 CI 类型检查任务与 tests/codebase 下的测试脚本共同保证类型卫生。如何在当前仓库中验证这些变更仓库是只读的你可以通过以下方式在本地观察本次补丁涉及的代码现状查看 BoxAnnotation 默认值直接阅读 src/bokeh/models/annotations/geometry.py 第 152–318 行逐一核对left/right/top/bottom及其交互属性的默认值与注释前端对照 bokehjs/src/lib/models/annotations/box_annotation.ts 第 950–979 行的this.define块。查看算法库实现阅读 bokehjs/src/lib/core/util/algorithms.ts 中的qbb与cbb函数理解包围盒计算逻辑含数值鲁棒性分支即可还原本次性能回归修复的代码上下文。查看类型检查配置阅读 pyproject.toml 的[tool.mypy]段与 pixi.toml 中的mypy版本约束了解项目当前的类型检查基线。一个简单的运行验证Python 侧from bokeh.models import BoxAnnotation # 不指定坐标时四个边默认绑定到绘图区域 frame box BoxAnnotation() print(box.left, box.right, box.top, box.bottom) # Node(frame.left) 等 # 显式指定数据区间坐标覆盖默认的 frame 绑定 box2 BoxAnnotation(left2, right4, top8, bottom6)升级到 3.3.2 后上述默认行为即与 3.2.x 系列一致不会再出现因 3.3.0/3.3.1 默认值变更导致的框位置漂移。升级建议与总结升级路径3.3.2 是纯补丁版本与 3.3.x 系列完全兼容建议直接升级跨大版本升级如 3.2 → 3.3.2也安全但需留意BoxAnnotation交互类属性均为实验性 API。重点关注回归风险如果项目中大量使用BoxAnnotation并依赖“不传坐标即铺满绘图区”的旧行为本次回退正是针对你的场景升级即修复如果曾针对 3.3.0/3.3.1 的异常默认值写过 workaround升级后请移除这些补丁代码。性能收益若在 3.3.1 上遇到曲线图形渲染/交互卡顿本次 bokehjs 算法库修复值得立即跟进。类型检查作为最终用户无需关注 mypy 变更作为贡献者请确保本地 mypy 满足 pixi.toml 中的版本要求并遵循 pyproject.toml 的类型检查配置。总体而言3.3.2 是一次“小而稳”的维护版本它没有新特性但通过回退破坏性默认值、修复渲染性能回归、升级类型检查工具链让 3.3 系列回归到稳定可靠的状态是 3.3 用户应当尽快采用的一个版本。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考