Plotly.py 版本迁移指南：从2.x到3.x的重要变化解析

Plotly.py 版本迁移指南：从2.x到3.x的重要变化解析

plotly.py The interactive graphing library for Python :sparkles: This project now includes Plotly Express! 项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py

前言

Plotly.py作为Python生态中强大的可视化库，在3.0版本中带来了多项重大改进。本文将详细解析从2.x迁移到3.x版本时需要注意的关键变化，帮助开发者顺利完成升级。

核心新特性概述

1. Jupyter Widget深度集成

3.0版本引入了go.FigureWidget对象，它继承了常规go.Figure的所有功能，同时可以直接在Jupyter notebook中显示：

import plotly.graph_objs as go

f = go.FigureWidget()  # 创建FigureWidget对象
f  # 直接显示图形

这意味着不再需要plotly.offline.iplot和plotly.offline.init_notebook_mode()等辅助函数（虽然它们仍然可用）。

2. 智能代码补全

在Jupyter环境中，FigureWidget提供了强大的代码补全功能：

• 输入f.add_后按Tab键，会显示所有支持的图表类型添加方法
• 输入f.add_scatter()后按Tab键，会显示scatter图表的所有顶级属性
• 按Shift+Tab组合键会显示方法签名和文档字符串

3. 改进的对象表示

图形对象现在具有更友好的__repr__方法，输出格式可以直接复制粘贴并重新执行：

print(f)
# 输出示例：
FigureWidget({
    'data': [{'type': 'scatter', 'x': [1, 2, 3], 'y': [4, 3, 2]}],
    'layout': {}
})

子图处理的新方法

3.0版本改进了子图处理方式，废弃了旧的append_trace方法，引入了更直观的add_trace、add_traces等方法：

from plotly.subplots import make_subplots

# 创建2x2子图
fig = make_subplots(rows=2, cols=2)

# 三种添加轨迹的方式
fig.add_trace(go.Scatter(x=[1,2], y=[3,4]), row=1, col=1)
fig.add_traces([go.Bar(x=[1], y=[1])], rows=[2], cols=[1])
fig.add_scatter(x=[1,2], y=[2,1], row=2, col=2)

重要变更点解析

1. 图形对象体系重构

所有图形对象现在都有明确的包层次结构，与其在对象层次结构中的位置相匹配：

旧方式（已废弃）：

go.Scatter(
    marker=go.Marker(color='red')  # 通用Marker对象
)

新方式：

go.Scatter(
    marker=go.scatter.Marker(color='red')  # 特定于Scatter的Marker对象
)

这种改变提供了更好的属性验证，因为不同图表类型的标记对象可能有不同的属性。

2. 属性不可变性

为了支持FigureWidget与前端视图的自动同步，属性现在表现为不可变对象：

fig.layout.xaxis.range = [0, 10]  # 赋值时使用列表
print(fig.layout.xaxis.range)     # 返回的是元组：(0, 10)

3. 数据数组属性规范

数据数组属性不能再指定为标量值：

无效写法：

go.Bar(x=1)  # 错误！

正确写法：

go.Bar(x=[1])  # 必须使用列表形式

4. 对象数组类变更

以下对象数组类已废弃：go.Data、go.Annotations和go.Frames。现在直接使用列表即可：

旧方式：

go.Layout(annotations=go.Annotations([...]))

新方式：

go.Layout(annotations=[...])

5. 图形数据分配限制

对figure.data属性的赋值有了新的限制：

# 有效的重新排序
fig.data = [fig.data[1], fig.data[0]]  # 交换轨迹顺序

# 无效的添加新轨迹
fig.data = [fig.data[0], go.Scatter(y=[1,2,3])]  # 错误！

要添加新轨迹，必须使用add_trace或相关方法。

迁移建议

1. 逐步替换：先替换append_trace为新的添加方法
2. 验证属性：检查所有标记对象是否使用了正确的命名空间
3. 数组处理：确保所有数据数组属性都使用列表形式
4. 不可变性适应：注意属性赋值后的类型变化

结语

Plotly.py 3.0版本的这些改进虽然带来了一些迁移成本，但显著提升了开发体验和性能。通过理解这些变化背后的设计理念，开发者可以更高效地利用新版本提供的强大功能。

plotly.py The interactive graphing library for Python :sparkles: This project now includes Plotly Express! 项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py