plotly.py v4 迁移指南：从 v3 到 v4 的完整升级路线与破坏性变更详解

plotly.py v4 迁移指南从 v3 到 v4 的完整升级路线与破坏性变更详解【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py本指南以 plotly.py 官方文档《Version 4 Migration Guide》见 doc/python/v4-migration.md为核心骨架系统梳理从 plotly.py 3.x 升级到 4.x 过程中所有需要关注的变更在线功能剥离、渲染框架重构、add_trace返回值变化、make_subplots参数体系调整等。读完本文你将能准确评估现有 v3 代码的迁移工作量掌握每一处破坏性变更的标准改写方式并理解 v4 架构设计背后的取舍与底层实现。升级总览升级到 plotly.py 版本 4本质上是按照 Getting Started 入门指南 中的说明重新安装包并注意下列几项变更通知。升级动作本身并不复杂真正的迁移工作量集中在代码层面因为 v4 把在线绘图功能剥离到了独立发行包chart-studio重构了离线渲染与 HTML 导出的 API同时调整了若干图对象方法的返回值约定。从当前仓库源码看v4 引入的架构调整在后来的版本中被延续了下来如今仓库的 plotly/io/_renderers.py 中仍然运行着 v4 建立的渲染器框架plotly/basedatatypes.py 中add_trace依旧返回调用它的 Figure 本身这些都是理解 v4 迁移文档时可以对照的活体源码。如果在升级过程中遇到问题可以前往官方社区论坛寻求帮助如果发现 v4 的 bug 或回归问题请提交 issue 反馈。若本文涉及的某项功能与你的实际版本行为不符请以你安装版本对应的官方文档与仓库源码为准。在线功能plotly.plotly迁移至chart-studio包早期版本的 plotly.py 同时包含在线online与离线offline两种模式在线模式下图形会被上传到 Chart Studio 云服务或企业私有化部署的 on-premise 服务上离线模式下图形在本地渲染。版本 4 的plotly是纯离线发行包所有在线功能已从主发行包中移除转移到了新的chart-studio发行包中。迁移 v3 在线功能的第一步是安装chart-studio包。使用 pip 安装$ pip install chart-studio或使用 conda 安装$ conda install -c plotly chart-studio第二步更新 Python 导入语句把原本从顶层plotly包导入的在线功能改为从顶层chart_studio包导入。例如把from plotly.plotly import plot, iplot替换为from chart_studio.plotly import plot, iplot类似地还有一批模块整体平移替换规则如下将plotly.api替换为chart_studio.api将plotly.dashboard_objs替换为chart_studio.dashboard_objs将plotly.grid_objs替换为chart_studio.grid_objs将plotly.presentation_objs替换为chart_studio.presentation_objs将plotly.widgets替换为chart_studio.widgets这意味着升级 v4 后主plotly包不再包含任何与云端上传相关的代码路径图表的创建、展示、导出全部在本地完成只有真正需要对接 Chart Studio 云服务的用户才需要额外安装chart-studio。从当前仓库的 plotly/init.py 可以确认主包只暴露离线相关的模块与图对象体系不再有plotly.plotly在线模块。离线功能plotly.offline被渲染器框架与 HTML 导出取代版本 4 引入了全新的渲染器renderers框架它是 v3 中plotly.offline.init_notebook_mode和plotly.offline.iplot两个函数在图形展示方面的泛化与统一。这是一项非破坏性变更plotly.offline.iplot函数在 v4 中仍然可用并且已经被基于渲染器框架重新实现因此迁移到 v4 时无需修改任何相关代码。但官方建议今后直接使用渲染器框架详见 Displaying plotly figures渲染器文档。在 v3 中plotly.offline.plot函数用于把图形导出为 HTML 文件。v4 中这个函数被重新实现为基于plotly.io模块中新增的to_html与write_html两个函数import plotly.io as pio # 将图形导出为 HTML 字符串 html_str pio.to_html(fig, full_htmlTrue, include_plotlyjscdn) # 将图形写入 HTML 文件 pio.write_html(fig, filefigure.html, include_plotlyjscdn)这两个函数的 API 比 v3 的offline.plot更一致具体参数差异见各自 docstring官方建议今后做 HTML 导出时直接使用它们。当操作的是 graph object 图形对象时这两个函数也以.to_html(...)和.write_html(...)的图对象方法形式直接可用例如fig.write_html(figure.html)从源码层面看v4 的渲染器框架对展示路径做了统一抽象plotly.io.show会根据环境自动选择合适的渲染器组合而 plotly/io/_renderers.py 中的RenderersConfig负责维护默认渲染器列表show()函数在 plotly/io/_renderers.py 中通过renderers._build_mime_bundle构建 MIME bundle、再调用_perform_external_rendering完成外部渲染。这意味着 v4 之后Notebook、VSCode、Kaggle、Colab 等环境的差异化展示需求都由同一套框架统一调度而不需要像 v3 那样手工区分init_notebook_mode等初始化调用。新默认主题Themev4 默认启用了一套更新过的plotly主题图表的默认外观相较 v3 有可见变化。下面是一个使用新默认主题绘制双子图柱状图 曲面图的完整示例import plotly.graph_objects as go from plotly.subplots import make_subplots import pandas as pd # 创建双子图 fig make_subplots(rows1, cols2, specs[[{type: bar}, {type: surface}]]) # 向子图 (1, 1) 添加柱状 trace fig.add_trace(go.Bar(y[2, 1, 3]), row1, col1) fig.add_trace(go.Bar(y[3, 2, 1]), row1, col1) fig.add_trace(go.Bar(y[2.5, 2.5, 3.5]), row1, col1) # 向子图 (1, 2) 添加曲面 trace数据从 csv 读取 z_data pd.read_csv(https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv) fig.add_surface(zz_data) # 隐藏图例 fig.update_layout( showlegendFalse, title_textDefault Theme, height500, width800, ) fig.show()如果希望恢复到 v3 的图形外观可以通过禁用默认主题来实现。禁用方式是直接把pio.templates.default设置为noneimport plotly.io as pio pio.templates.default none import plotly.graph_objects as go from plotly.subplots import make_subplots import pandas as pd # 创建双子图 fig make_subplots(rows1, cols2, specs[[{type: bar}, {type: surface}]]) # 向子图 (1, 1) 添加柱状 trace fig.add_trace(go.Bar(y[2, 1, 3]), row1, col1) fig.add_trace(go.Bar(y[3, 2, 1]), row1, col1) fig.add_trace(go.Bar(y[2.5, 2.5, 3.5]), row1, col1) # 向子图 (1, 2) 添加曲面 trace z_data pd.read_csv(https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv) fig.add_surface(zz_data) # 隐藏图例 fig.update_layout( showlegendFalse, title_textDefault Theme Disabled, height500, width800, ) fig.show()恢复默认主题只需再次把templates.default设回plotly# 恢复默认主题 pio.templates.default plotly关于 v4 主题theming机制的更多细节参见 Theming and templates主题与模板文档。从仓库来看pio.templates.default的取值会直接影响 plotly/io/_templates.py 中模板解析与合并的逻辑模板实际定义则存放在 plotly/package_data/templates 目录下的 JSON 文件中如plotly.json、plotly_white.json、plotly_dark.json等自定义主题本质上就是向该注册表注入模板并切换默认值。add_trace返回值变更从返回 trace 到返回 figurev3 中图对象的add_trace方法返回的是新建的 trace 引用add_{trace_type}系列方法如add_scatter、add_bar等行为相同。v4 中这些方法统一返回调用它们的 figure 本身。这一改动是为了支持图操作的方法链式调用。例如from plotly.subplots import make_subplots (make_subplots(rows1, cols2) .add_scatter(y[2, 1, 3], row1, col1) .add_bar(y[3, 2, 1], row1, col2) .update_layout( title_textFigure title, showlegendFalse, width800, height500, ) .show())从源码可以印证这一设计在 plotly/basedatatypes.py 的add_trace实现中无论走多子图分发路径还是单 trace 路径最终都执行return self或return self.add_traces(...)而add_traces同样在 plotly/basedatatypes.py 处返回 figure 自身plotly/basedatatypes.py。依赖旧行为的代码必须改写。原本依赖add_*方法返回新建 trace 的代码需要改为从返回的 figure 上取 trace方法是在 add trace 表达式末尾追加.data[-1]。下面是 v3 代码片段添加一个 scatter trace把结果赋给变量scatter然后修改该 trace 的 marker 大小。import plotly.graph_objs as go fig go.Figure() scatter fig.add_trace(go.Scatter(y[2, 3, 1])) scatter.marker.size 20v4 中改写为import plotly.graph_objects as go fig go.Figure() scatter fig.add_trace(go.Scatter(y[2, 3, 1])).data[-1] scatter.marker.size 20注意新旧代码中 import 路径也从plotly.graph_objs变更为plotly.graph_objects详见下文推荐样式更新一节。scatter.marker.size 20这样的属性赋值之所以能生效是因为 v4以及后续版本的 trace 对象支持属性直接赋值并自动完成校验这是 plotly/basedatatypes.py 中图对象属性描述符体系提供的能力。make_subplots更新make_subplots函数在 v4 中被彻底重构目标是支持全部 trace 类型并集成 Plotly Express。移植使用make_subplots的代码到 v4 时需要注意以下几处变化。新的推荐导入位置make_subplots的推荐导入位置现在是plotly.subplots.make_subplots。为兼容旧代码该函数仍可从plotly.tools.make_subplots导入。当前仓库中make_subplots的完整实现位于 plotly/subplots.py其函数签名plotly/subplots.py默认参数为start_celltop-left、print_gridFalse、row_heightsNone与 v4 文档描述一致。网格不再默认打印当make_subplots的print_grid参数为True时函数会打印子图网格的文本表示。v3 中print_grid默认值为Truev4 中默认值改为False。这意味着升级后调用make_subplots不再自动向控制台输出一大段网格 ASCII 文本需要查看网格结构时需显式设置print_gridTrue或调用图对象的print_grid()方法。新row_heights参数替代row_width用于指定子图行相对高度的旧参数名为row_width。v4 引入了新的row_heights参数承担该职责。注意虽然plotly.subplots.make_subplots的 docstring 中未提及但旧版row_width参数保持旧行为在 v4 中仍然可用。除了命名更一致之外新row_heights参数的值能正确遵循start_cell参数的方向约定使用旧版row_width时高度列表始终按从底行到顶行解释即使start_celltop-left也是如此使用新row_heights参数时如果start_celltop-left高度列表按从顶到底解释如果start_cellbottom-left则按从底到顶解释。因此把row_width移植为row_heights时如果start_celltop-left或未指定start_cell必须反转高度列表的顺序。下面是一个兼容 v3 的示例用row_width参数创建双子图要求顶行高度是底行的两倍即顶行占 2/3、底行占 1/3from plotly.subplots import make_subplots fig make_subplots( rows2, cols1, row_width[0.33, 0.67], start_celltop-left) fig.add_scatter(y[2, 1, 3], row1, col1) fig.add_bar(y[2, 3, 1], row2, col1) fig.show()下面是等价的 v4 示例。注意与上面的例子相比高度列表的顺序发生了反转from plotly.subplots import make_subplots fig make_subplots( rows2, cols1, row_heights[0.67, 0.33], start_celltop-left) fig.add_scatter(y[2, 1, 3], row1, col1) fig.add_bar(y[2, 3, 1], row2, col1) fig.show()从源码看这一语义在 plotly/subplots.py 的 docstring 中有明确说明row_heights在start_celltop-left时从顶到底应用、在start_cellbottom-left时从底到顶应用而若指定为旧版row_width则无论start_cell取值如何宽度/高度值一律从底到顶应用——这正是迁移时需要反转列表顺序的根本原因。共享轴的实现方式简化make_subplots的共享轴shared axes支持实现被简化了。v4 之前共享 y 轴是通过让多个 xaxis 对象关联同一个 yaxis 对象反之亦然来实现的。v4 中每个二维笛卡尔子图都有自己专属的 x 轴和 y 轴。轴之间通过matches轴属性链接来实现共享。对于使用make_subplots和 add trace API 的旧代码这一变化无需用户做任何改动。但是如果旧代码使用make_subplots创建带共享轴的图形后直接操作轴对象则可能需要更新。可以通过对make_subplots创建的图形调用.print_grid()方法来识别每个子图关联的是哪些轴对象from plotly.subplots import make_subplots fig make_subplots(rows1, cols2, shared_yaxesTrue) fig.print_grid() print(fig)上述代码会在控制台输出类似yaxis/yaxis2、xaxis/xaxis2的轴分配关系以及matches链接情况从而帮助确认直接操作轴对象时应该修改哪一个。这正是 v4 之后shared_yaxes的底层表现所有轴对象都被保留fig.layout.yaxis2.matches y这类matches属性承担了真正的联动职责而不是像 v3 那样在对象引用层面共享同一个轴实例。Trace UID 的生成时机v3 中所有 trace 图对象在加入Figure时都会被复制并被赋予一个新的uid属性。v4 中uid属性只在 trace 被加入FigureWidget时才自动生成。当 trace 被加入标准Figure图对象时如果输入中提供了uid则按原样接受。也就是说在 v4 中创建普通Figure时如果你不关心uid可以完全忽略它如果需要稳定复现、序列化或与其他系统对接时自定义标识传入的uid会被保留而不会像 v3 那样被强制替换。对于需要依赖 trace 身份做消息同步的场景如 FigureWidget 的交互回放则仍由框架自动生成uid保证一致性。时区Timezone处理变化v4 之前当 plotly.py 收到一个带时区信息的datetime时会自动将其转换为 UTC。v4 起不再执行这一转换datetime对象按本地时间被接受和显示。这对迁移的影响是如果你的 v3 代码依赖输入带时区的datetime会被自动转为 UTC 显示这一行为升级到 v4 后图形的横轴刻度/悬停文本会以原始时区展示。迁移时需要核对数据管道中datetime的时区一致性必要时在传给 plotly 之前显式做dt.astimezone(timezone.utc)之类的转换以保证新旧图形时间语义一致。Linux 无头环境Headless静态图像导出与 Xvfbv4 的静态图像导出逻辑会尝试自动检测是否需要用 Xvfb 调用 orca 图像导出工具。在 Linux 环境中如果系统没有可用的 X11 显示服务器orca 必须借助 Xvfb 才能工作。默认行为是如果 plotly.py 运行在 Linux 上、未检测到 X11 显示服务器、且系统PATH中存在Xvfb则默认使用 Xvfb。这一新行为可以通过把 orca 配置项use_xvfb设置为False来禁用import plotly.io as pio pio.orca.config.use_xvfb False对于 CI 流水线、Docker 容器等无显示环境的服务器场景该自动检测大幅简化了静态图像导出的配置成本——无需手工启动Xvfb :99再设置DISPLAY环境变量。若你的环境中 orca 已通过其他方式获得了 X 服务例如显式启动的 Xvfb 或真实 X11则可以关闭此选项避免重复启动。当前仓库中 orca 相关配置与导出路径由 plotly/io/_kaleido.py以及历史版本中的 orca 支持模块承载pio.orca.config对象上保存了use_xvfb等运行时开关。已移除的功能fileopt参数移除chart_studio.plotly.plot的fileopt参数已被移除因此不再支持对已发布图形进行原地in-place修改。如果旧代码通过fileopt实现更新已上传的图形例如fileoptoverwrite需要改为重新上传新图形或改用 Chart Studio 侧提供的更新机制。旧版在线GraphWidget移除旧版仅在线可用的GraphWidget类已被移除。请改用plotly.graph_objects.FigureWidget类相关介绍见 Figure Widget OverviewFigureWidget 文档。FigureWidget是 v4 体系内基于 graph objects 的交互式组件与 Jupyter 生态集成更紧密具体用法和回调机制可参考 FigureWidget 应用文档。推荐样式更新从graph_objs改为导入graph_objects旧版包名plotly.graph_objs被别名为plotly.graph_objects因为后者在口头沟通中更易表达graph objects vs graph obs。plotly.graph_objs包仍然可用以保持向后兼容但官方推荐新代码统一使用import plotly.graph_objects as go当前仓库中plotly/graph_objs.py 与 plotly/graph_objects/init.py 并存前者即向后兼容别名层的体现而graph_objects下的_figure.py、_layout.py及各_*.pytrace 类文件构成了 v4 之后正式的对象体系。迁移 v3 代码时把import plotly.graph_objs as go全局替换为import plotly.graph_objects as go即可绝大多数场景下对象 API 行为一致。迁移检查清单把 v3 代码库升级到 v4 时可对照以下清单逐项排查在线功能是否使用plotly.plotly、plotly.api、plotly.dashboard_objs、plotly.grid_objs、plotly.presentation_objs、plotly.widgets若是安装chart-studio并把导入路径前缀改为chart_studio.*。离线展示是否依赖plotly.offline.iplot/init_notebook_mode它们仍可用但建议逐步迁移到渲染器框架是否依赖plotly.offline.plot做 HTML 导出建议改用pio.to_html/pio.write_html或fig.write_html。主题图形外观是否因新默认plotly主题而变化需要 v3 外观时设置pio.templates.default none。add_trace 返回值是否把fig.add_trace(...)/fig.add_scatter(...)的返回值当作新 trace 使用若是改为追加.data[-1]。make_subplots导入是否已切换为plotly.subplots.make_subplots是否依赖print_grid默认打印行为是否使用row_width若是注意row_heights的顺序语义是否直接操作共享轴对象建议用print_grid()核对轴分配。UID 与时区是否依赖 traceuid自动生成是否依赖 datetime 自动转 UTC静态导出Linux 无显示环境是否依赖自动 Xvfb 检测需要时用pio.orca.config.use_xvfb False关闭。已移除项是否使用fileopt或旧版在线GraphWidget分别改用重新上传与plotly.graph_objects.FigureWidget。导入路径是否把plotly.graph_objs迁移为plotly.graph_objects。按此清单逐项处理即可把 v3 代码平滑迁移到 v4 的离线优先 渲染器统一 方法链式调用新架构之上。深入理解本指南涉及的渲染器、主题与子图机制可进一步阅读仓库中的 doc/python/renderers.md、doc/python/templates.md 与 doc/python/subplots.md 相关文档。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考