解读 Bokeh 0.9.3 发布说明横竖 Span 标注、嵌入组件 API、命名重构与 pytest/Selenium 测试体系【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh本文基于 Bokeh 官方的 0.9.3 版本发布文档2015 年 8 月逐条解读该版本引入的十项变更水平/垂直 Span 标注支持、bokeh.embed组件级嵌入 API、滚轮事件修复、actions到callbacksCustomJS的命名重构以及从 nose 迁移到 pytest 并引入 Selenium 的测试基础设施建设并结合当前仓库源码说明这些变更在后续版本中的落地形态与实现位置。一、版本背景与总体定位0.9.3 发布于 2015 年 8 月官方发布文档 0.9.3.rst 将其概括为多项可用性增强、文档改进、新示例、大量缺陷修复以及基于 pytest 和 Selenium 的测试机制改进。该版本共列出十项变更可归为四类类别变更项绘图能力支持水平或垂直的 spanhspan/vspan嵌入 API提供bokeh.embed.components的raw_components版本行为修复滚轮工具wheel tool未激活时不再吞掉页面滚动事件模型 API 重构bokeh.models.actions更名为bokeh.models.callbacksCallback更名为CustomJS工程与质量新增校验警告、清理 gulp source mapping、构建机制修复、参考指南 models 章节整理测试体系使用 pytest 替代 nose开始引入 Selenium 测试下面逐条结合当前仓库中的实现进行剖析。二、支持水平或垂直的 Span从标注到源码这是 0.9.3 中最具代表性的功能增强允许在图上绘制横跨绘图区的一条水平线hspan或垂直线vspan常用于标出基准值、阈值、均值线等参考位置。2.1 用法示例仓库中的官方示例 spans.py 展示了最直接的调用方式from bokeh.io import show from bokeh.plotting import figure plot figure() plot.hspan( y[0, 5, 15, 33], line_width[1, 2, 3, 4], line_colorred, ) plot.vspan( x[0, 5, 15, 33], line_width[1, 2, 3, 4], line_colorblue, ) show(plot)两个要点hspan/vspan的坐标参数支持列表一次绘制多条 span线条样式属性支持逐条向量化的line_width。2.2 Span 模型的源码形态当前仓库中Span类的定义位于 geometry.py其核心属性包括locationspan 沿dimension方向的位置类型为Nullable(CoordinateLike)location_units位置坐标的单位默认data数据空间也可使用屏幕等其它坐标单位dimension决定 span 的方向枚举值为widthx 方向即水平 span或heighty 方向即垂直 span——这正对应 0.9.3 发布说明中“Support horizontal or vertical spans”一词line_props/hover_line_props正常与悬停状态下的线条外观颜色、宽度、线型等。从源码结构看hspan()/vspan()便捷方法本质上就是创建一个dimension为width或height的Span注解实例并添加到绘图对象后续版本还为其增加了editable可交互拖动修改位置等实验性属性可见这一标注能力是在 0.9.3 奠定的模型基础上持续演进的。三、嵌入 APIraw_components与今天的components(wrap_script...)0.9.3 引入的raw_components是bokeh.embed.components的“原始输出”变体将绘图对象渲染为 HTML 片段用于拼装到已有页面时有时不希望返回的script部分再被外层包装一层标签。在当前仓库中这一能力已演化进统一的components()接口其定义位于 standalone.pydef components( models: Model | Sequence[Model] | dict[str, Model], wrap_script: bool True, wrap_plot_info: bool True, ) - tuple[str, str]:wrap_script参数即当年的raw_components语义的现代形式默认True时返回的脚本会被script标签包裹设为False时返回“裸”脚本方便调用方自行控制脚本插入时机与位置例如合并多个组件的脚本块。models参数支持单个模型、模型序列或{名称: 模型}字典三种形态返回(rendered, script)二元组。这一签名从 bokeh.embed 导出是 0.9.3 时代组件级嵌入思路的直接延续。四、行为修复滚轮工具不再吞掉页面滚动事件发布说明中“Prevent Bokeh from eating scroll events if wheel tool is not active”指出的问题是早期版本中只要页面里存在 BokehJS 绘图对象浏览器滚轮事件就可能被工具层拦截导致页面无法正常滚动。修复后只有当滚轮缩放工具wheel zoom tool处于激活状态时BokehJS 才消费wheel事件工具未激活时事件放行给浏览器默认行为。这一改动属于前端事件处理层面的修复其后续实现位于 BokehJS 的交互工具模块bokehjs/src/lib/models/tools/下的 wheel zoom 相关实现。对用户的直接影响是同一页面中混合 Bokeh 图与长文档内容时滚动体验符合直觉不需要先“点进”图表才能滚动画布外区域。五、模型 API 重构actions→callbacksCallback→CustomJS0.9.3 将bokeh.models.actions模块更名为bokeh.models.callbacks并将其中的Callback类更名为CustomJS。这一命名沿用至今当前实现位于 callbacks.pyCustomJS继承自CustomCode用于在客户端执行用户提供的 JavaScript 函数其类型存根 callbacks.pyi 表明它提供args传入 JS 函数的参数映射、code函数源码与from_file从文件加载 JS 代码三种配置入口。重命名的意义在于CustomJS这一名称直观表达了“嵌入一段原始 JavaScript 代码”的本质与仓库中其它同族模型CustomJSTransform、CustomJSTickFormatter、CustomJSFilter等形成一致的命名体系。同时该系列模型在文档字符串中均带有安全警示如果 JS 代码内容来自不可信输入调用方必须先做净化处理。六、其他改进校验警告、构建与文档发布说明中还包含四项工程性改进逐一对照当前仓库可作如下说明新增校验警告Additional validation warningsBokeh 的属性与模型校验框架bokeh.core下的属性系统与校验机制在本版本增加了更多运行时警告帮助用户在文档构建/序列化阶段发现可疑配置而不是等到浏览器端才暴露问题清理 gulp source mapping 与构建机制修复早期 BokehJS 使用 gulp 组织前端构建。当前仓库中构建体系已演进为由 bokehjs/make/ 驱动的 Make 任务集编译、打包、样式、测试等任务位于 bokehjs/make/tasks/0.9.3 时期的 source map 与构建修复正是这条演进路线上的早期环节参考指南 models 章节整理对应今天仓库中的模型参考指南每个模型如Span、CustomJS都有对应的参考条目配套示例见 examples/reference/models/ 同级的模型用法示例。七、测试体系pytest 与 Selenium 的落地0.9.3 在测试基础设施上有两项里程碑式变更在当前仓库中都能找到直接证据7.1 使用 pytest 替代 nose当前 pyproject.toml 中保留了完整的[tool.pytest.ini_options]配置段含告警过滤、插件路径等测试入口与运行约定全部围绕 pytest 展开证实了 nose 到 pytest 的迁移自本版本完成并一直沿用至今。7.2 开始引入 Selenium 测试发布说明中“Beginning to add selenium tests”对应仓库中的 tests/support/plugins/selenium.py这是一个 pytest 插件负责管理 Selenium 浏览器驱动如 Chrome的生命周期在测试会话内提供 WebDriver fixture并支持配置“无控制台错误”断言。该插件在导入 Selenium 时使用pytest.importorskip(selenium)使浏览器测试在缺少依赖的环境中可被自动跳过。基于此插件仓库在 tests/unit/bokeh/io/test_webdriver.py 等处积累了截图导出等需要真实浏览器的集成测试形成了“单元测试pytest 浏览器级测试Selenium”的双层测试结构这也成为后续版本持续扩充浏览器基线对比测试的起点。八、小结0.9.3 是一个“功能、API、工程三线并进”的版本功能线Span标注hspan/vspan补齐了参考线类注解能力模型至今保留在 geometry.py 中并持续增强API 线raw_components与actions→callbacks/CustomJS的重命名奠定了组件级嵌入与客户端 JS 回调两套 API 的长期稳定形态见 standalone.py 与 callbacks.py工程线滚轮事件修复改善了页面内嵌体验pytest Selenium 的测试机制则让 Bokeh 从此具备系统化回归验证能力其插件化结构tests/support/plugins/selenium.py与 pytest 配置pyproject.toml均可在当前仓库中直接查证。对于阅读现代 Bokeh 代码库的开发者而言0.9.3 的这份发布说明相当于一份“考古地图”今天figure.hspan()、bokeh.embed.components()、CustomJS等常用 API 的设计决策大多可以追溯到本版本确立的模型与接口形态。【免费下载链接】bokehInteractive Data Visualization in the browser, from Python项目地址: https://gitcode.com/GitHub_Trending/bo/bokeh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考