3.5.0 的 API 变更#

行为变化#

subplot_mosaic 的第一个参数已重命名#

Figure.subplot_mosaic 和 pyplot.subplot_mosaic 已将第一个位置参数从 layout 重命名为 mosaic。由于我们在 pyplot 的 Figure 创建函数中将 constrained_layout 和 tight_layout 关键字参数合并为一个 layout 关键字参数，原始的 subplot_mosaic 参数名称会发生冲突。

由于此API是暂定的，我们正在更改此参数名称，且没有弃用期。

Axes 的子元素不再按类型分隔#

以前，axes.Axes 的子元素按 Artist 类型分开，分成子列表如 Axes.lines。对于生成多个元素的方法（如 Axes.errorbar），尽管各个部分可能有相似的 zorder，但这种分离可能导致它们在不同时间绘制，从而在与其他艺术家重叠时产生不一致的结果。

现在，子对象不再按类型分开，子列表属性在访问时动态生成。因此，艺术家现在将始终出现在正确的子列表中；例如，如果对 Patch 调用 axes.Axes.add_line，它将出现在 Axes.patches 子列表中，而不是 Axes.lines 中。如果传递了意外类型，Axes.add_* 方法现在将发出警告。

仍然接受以下子列表的修改，但已弃用：

  • Axes.artists

  • Axes.collections

  • Axes.images

  • Axes.lines

  • Axes.patches

  • Axes.tables

  • Axes.texts

要移除一个 Artist，使用其 Artist.remove 方法。要添加一个 Artist，使用相应的 Axes.add_* 方法。

MatplotlibDeprecationWarning 现在继承自 DeprecationWarning#

从历史上看，通过检查 DeprecationWarning 来过滤 MatplotlibDeprecationWarning 是不可能的，因为我们直接子类化了 UserWarning。

不继承 DeprecationWarning 的决定与 Python 核心在 2.x 时代的一个决定有关，即不向用户显示 DeprecationWarning。然而，现在有一个更复杂的过滤器（参见 https://www.python.org/dev/peps/pep-0565/）。

用户现在只会在交互式会话期间看到 MatplotlibDeprecationWarning，并且可以通过标准机制将其静音：

warnings.filterwarnings("ignore", category=DeprecationWarning)

库作者现在必须显式启用 DeprecationWarning ，以便（非交互式）CI/CD 管道能够报告这些警告，这是 Python 生态系统其余部分的标准做法：

warnings.filterwarnings("always", DeprecationWarning)

Artist.set 按照给定的顺序应用艺术家属性#

这一更改仅影响 color、edgecolor、facecolor 以及（对于 Collection）*alpha* 属性之间的交互：现在需要首先传递 color 属性，以避免覆盖其他属性。这与例如 Artist.update 一致，后者不会重新排序传递给它的属性。

pcolor(mesh) 阴影默认设置为自动#

Axes.pcolormesh 和 Axes.pcolor 的 shading 关键字参数的默认值已更改为 'auto'。

将 Z(M, N)、x(N)、y(M) 传递给 pcolormesh 并设置 shading='flat' 现在会引发 TypeError。使用 shading='auto' 或 shading='nearest' 使 x 和 y 被视为单元格中心，或者删除 Z 的最后一列和最后一行以在 shading='flat' 下获得旧的行为。

颜色条现在具有平移和缩放功能#

带有颜色条的交互式图表现在可以在颜色条轴上进行缩放和平移。这将调整与颜色条关联的 ScalarMappable 的 vmin 和 vmax。目前这仅对连续范数启用。与 contourf 和分类一起使用的范数，例如 BoundaryNorm 和 NoNorm，默认情况下禁用了交互功能。可以使用 cb.ax.set_navigate() 来设置颜色条轴是否为交互式。

颜色条线不再被裁剪#

如果颜色条上添加了线条（例如等高线），这些线条将不再被裁剪。这对于颜色条边缘的线条是一个改进，但如果颜色条的限制发生变化，可能会导致线条超出颜色条范围。

Figure.suppressComposite 现在也控制 Axes 图像的合成#

NonUniformImage 和 PcolorImage 的输出已更改#

在使用 NonUniformImage 或 PcolorImage 生成的图像中，可能会观察到像素级别的差异，通常出现在两个数据单元之间的边界像素上（目前没有面向用户的方法可以生成 NonUniformImage，只有 pcolorfast 可以生成 PcolorImage）。这些艺术家的渲染速度现在也更慢了，通常会慢约 1.5 倍，有时甚至更多（特别是对于 NonUniformImage(interpolation="bilinear")）。这种减速是由于修复了偶尔的浮点精度问题。

更改 Line2D 实例的（默认）图例处理程序#

对于 Line2D 实例的默认图例处理程序（HandlerLine2D）现在一致地暴露了与线条标记相关的所有属性和方法（#11358）。这使得在实例化图例后更改标记特征变得容易。

import matplotlib.pyplot as plt

fig, ax = plt.subplots()

ax.plot([1, 3, 2], marker="s", label="Line", color="pink", mec="red", ms=8)
leg = ax.legend()

leg.legendHandles[0].set_color("lightgray")
leg.legendHandles[0].set_mec("black")  # marker edge color

用于 Line2D 对象的旧图例处理程序已重命名为 HandlerLine2DCompound。要恢复到之前的行为，可以使用

import matplotlib.legend as mlegend
from matplotlib.legend_handler import HandlerLine2DCompound
from matplotlib.lines import Line2D

mlegend.Legend.update_default_handler_map({Line2D: HandlerLine2DCompound()})

将 Line2D 标记的边缘/面颜色设置为 None 使用 rcParams#

Line2D.set_markeredgecolor(None) 和 Line2D.set_markerfacecolor(None) 现在使用相应的 rcParam（rcParams["lines.markeredgecolor"] (default: 'auto') 和 rcParams["lines.markerfacecolor"] (default: 'auto')）设置线条属性。这与其他的 Line2D 属性设置器一致。

楔形极坐标图的默认 theta 刻度位置已更改#

对于不覆盖整个圆的极坐标图，默认的 theta 刻度位置现在位于 10°、15°、30°、45°、90° 的倍数处，而不是使用主要适用于线性图的值（20°、25°等）。

axvspan 现在在极坐标图中绘制完整的楔形区域#

... 而不是三角形。

从 Scale 到 Normalize 的便捷转换器现已公开#

下游库可以利用 colors.make_norm_from_scale 直接从现有比例创建一个 Normalize 子类。通常，规范有一个比例，而将 ScaleBase 附加到规范的优势在于为颜色条提供比例以及相关的刻度定位器和格式化器。

ContourSet 总是使用 PathCollection#

为了修正闭环的渲染问题，ContourSet 现在创建一个 PathCollection 而不是 LineCollection 用于线条等高线。这种类型与用于填充等高线的艺术家相匹配。

这会影响 ContourSet 本身及其子类，QuadContourSet`（由 `.Axes.contour 返回），以及 TriContourSet`（由 `.Axes.tricontour 返回）。

hatch.SmallFilledCircles 继承自 hatch.Circles#

hatch.SmallFilledCircles 类现在继承自 hatch.Circles 而不是 hatch.SmallCircles。

带有对数归一化的 hexbin#

hexbin 不再（错误地）在使用对数规范时为每个箱值加1。

设置无效的 rcParams["date.converter"] 现在会引发 ValueError#

之前，传递给 rcParams["date.converter"] (default: 'auto') 的无效值会以 UserWarning 被忽略，但现在会引发 ValueError。

Text 和 TextBox 添加了 parse_math 选项#

Text 和 TextBox 对象现在允许一个仅关键字的参数 parse_math，它控制是否应从显示的字符串中解析数学内容。如果为 True，字符串将被解析为数学文本对象。如果为 False，字符串将被视为字面量，不会进行解析。

对于 Text，此参数默认为 True。对于 TextBox，此参数默认为 False。

Type1Font 对象现在解密加密部分#

Type 1 字体的大部分代码作为过时的复制保护措施被加密。这部分现在可以作为 matplotlib.type1font.Type1Font 的 decrypted 属性解密。这些解密的数据尚未被解析，但这是实现子集化的先决条件。

放置在层级之间的3D等高线填充多边形#

在 3D contourf 图中使用的多边形现在被放置在等高线层级之间的中间位置，因为每个多边形代表位于两个层级之间的数值位置。

AxesDivider 现在默认使用 rcParams 指定的填充#

AxesDivider.append_axes, AxesDivider.new_horizontal, 和 AxesDivider.new_vertical 现在默认使用由 rcParams["figure.subplot.wspace"] (default: 0.2) 和 rcParams["figure.subplot.hspace"] (default: 0.2) 指定的填充，而不是零。

弃用#

不推荐使用：Figure 参数 tight_layout 和 constrained_layout#

Figure 参数 tight_layout 和 constrained_layout 会触发竞争的布局机制，因此不应同时使用。

为了使API更清晰，我们将它们合并到新的参数 layout 下，其值为 'constrained'（等同于 constrained_layout=True），'tight'（等同于 tight_layout=True）。如果给出，layout 优先。

不鼓励使用 tight_layout 和 constrained_layout，而推荐使用 layout。然而，为了向后兼容，这些参数仍将保持可用。

修改 Axes 子列表#

更多信息请参见 行为API变更3.5 - 轴子组合；以下子列表的修改已被弃用：

  • Axes.artists

  • Axes.collections

  • Axes.images

  • Axes.lines

  • Axes.patches

  • Axes.tables

  • Axes.texts

要移除一个 Artist，使用其 Artist.remove 方法。要添加一个 Artist，使用相应的 Axes.add_* 方法。

向 Axes.add_* 方法传递不正确的类型#

以下 Axes.add_* 方法现在会在传递意外类型时发出警告。请参阅它们的文档以了解它们期望的类型。

不推荐使用：plot_date#

不鼓励使用 plot_date。此方法因历史原因而存在，未来可能会被弃用。

  • datetime 类型的数据应直接使用 plot 进行绘制。

  • 如果你需要将纯数值数据绘制为 日期格式 或需要设置时区，请在 plot 之前调用 ax.xaxis.axis_date / ax.yaxis.axis_date。参见 Axis.axis_date。

epoch2num 和 num2epoch 已被弃用#

这些方法将unix时间戳转换为matplotlib浮点数，但它们在matplotlib内部并不使用，终端用户也不需要使用。要将unix时间戳转换为datetime，只需使用`datetime.datetime.utcfromtimestamp`，或者使用NumPy datetime64 dt = np.datetime64(e*1e6, 'us')。

通过 pcolor 和 pcolormesh 自动移除网格#

pcolor 和 pcolormesh 目前会移除任何可见的轴主要网格。此行为已被弃用；请显式调用 ax.grid(False) 以移除网格。

Axes.grid 和 Axis.grid 的第一个参数已重命名为 visible#

该参数之前名为 b。此弃用仅在通过关键字参数传递该参数时才重要，例如 grid(b=False)。

统一和清理选择器小部件API#

选择器小部件的API已经统一使用：

  • props 表示代表选择的 Artist 的属性。

  • handle_props 用于表示修改选择的句柄的艺术家。

  • grab_range 用于设置鼠标抓取手柄的最大容差。

此外，几个内部参数和属性已被弃用，目的是将它们保持为私有。

RectangleSelector 和 EllipseSelector#

RectangleSelector 的 drawtype 关键字参数已被弃用。未来将只有 drawtype='box' 的默认行为。

由于不清楚哪些点在仅作为线条的选择器内部和外部，drawtype=line 的支持将被完全移除。因此，RectangleSelector 的 lineprops 关键字参数也被弃用。

要保留 drawtype='none' 的行为，请使用 rectprops={'visible': False} 使绘制的 Rectangle 不可见。

清理后的属性和参数是：

  • active_handle 属性已被私有化并弃用。

  • drawtype 属性已被私有化并弃用。

  • eventpress 属性已被私有化并弃用。

  • eventrelease 属性已被私有化并弃用。

  • interactive 属性已被私有化并弃用。

  • marker_props 参数已弃用，请改用 handle_props。

  • 参数 maxdist 已被弃用，请改用 grab_range。

  • rectprops 参数已弃用，请改用 props。

  • rectprops 属性已被私有化并弃用。

  • state 属性已被私有化并弃用。

  • to_draw 属性已被私有化并弃用。

PolygonSelector#

  • 属性 line 已被弃用。如果你想更改选择器艺术家属性，请使用 set_props 或 set_handle_props 方法。

  • lineprops 参数已弃用，请改用 props。

  • markerprops 参数已弃用，请改用 handle_props。

  • 参数和属性 maxdist 已被弃用，请改用 grab_range。

  • 参数和属性 vertex_select_radius 已被弃用，请改用 grab_range。

SpanSelector#

  • active_handle 属性已被私有化并弃用。

  • eventpress 属性已被私有化并弃用。

  • eventrelease 属性已被私有化并弃用。

  • 参数和属性 maxdist 已被弃用，请改用 grab_range。

  • pressv 属性已被私有化并弃用。

  • prev 属性已被私有化并弃用。

  • rect 属性已被私有化并弃用。

  • rectprops 参数已弃用，请改用 props。

  • rectprops 属性已被私有化并弃用。

  • span_stays 参数已被弃用，请改用 interactive 参数。

  • span_stays 属性已被私有化并弃用。

  • state 属性已被私有化并弃用。

LassoSelector#

  • lineprops 参数已弃用，请改用 props。

  • onpress 和 onrelease 方法已被弃用。它们是 press 和 release 的直接别名。

ConversionInterface.convert 不再需要接受无单位的值#

以前，units.ConversionInterface 的自定义子类需要实现一个 convert 方法，该方法不仅接受单位的实例，还接受无单位的值（这些值按原样传递）。现在不再是这种情况（convert 永远不会被调用无单位的值），StrCategoryConverter 中的这种支持已被弃用。同样，.ConversionInterface.is_numlike 助手也被弃用。

考虑改为调用 Axis.convert_units，它仍然支持无单位的值。

定位器和格式化器包装方法#

Locator 和 Formatter 的 set_view_interval、set_data_interval 和 set_bounds 方法（以及它们的公共基类 TickHelper）已被弃用。请直接操作底层轴的视图和数据间隔。

未使用的 print_<fmt> 方法的位置参数#

canvas 子类实现的 print_<fmt> 方法都没有使用除第一个参数（输出文件名或类文件对象）之外的位置参数，因此这些额外参数已被弃用。

QuadMesh 签名#

QuadMesh 签名

def __init__(meshWidth, meshHeight, coordinates,
             antialiased=True, shading='flat', **kwargs)

已被弃用，并被新的签名替代

def __init__(coordinates, *, antialiased=True, shading='flat', **kwargs)

特别是：

  • 现在，coordinates 参数必须是一个 (M, N, 2) 的类数组。以前，网格形状是单独指定的，即 (meshHeight + 1, meshWidth + 1)，而 coordinates 可以是任何形状的类数组，包含 M * N * 2 个元素。

  • 除了 coordinates 之外的所有参数现在都是仅关键字参数。

rcParams 将不再将输入转换为字符串#

在弃用期之后，期望（非路径类）字符串的 rcParams 将不再使用 str 强制转换非字符串输入。这将避免在后续代码中出现混淆的错误，例如，如果列表输入被隐式转换为字符串。

不区分大小写的比例#

之前，刻度可以不区分大小写地设置（例如，set_xscale("LoG")）。这已被弃用；所有内置刻度使用小写名称。

交互式光标详情#

在窗口上设置鼠标光标的功能已从工具栏移至画布。因此，工具栏和后端中的几个实现细节已被弃用。

backend_tools.SetCursorBase 及其子类#

backend_tools.SetCursorBase 被继承以提供特定于后端的 set_cursor 实现。由于该功能现已弃用，因此不再需要继承。因此，以下子类也被弃用：

  • matplotlib.backends.backend_gtk3.SetCursorGTK3

  • matplotlib.backends.backend_qt5.SetCursorQt

  • matplotlib.backends._backend_tk.SetCursorTk

  • matplotlib.backends.backend_wx.SetCursorWx

相反，使用 backend_tools.ToolSetCursor 类。

cursord 在 GTK、Qt 和 wx 后端中#

backend_gtk3.cursord、backend_qt.cursord 和 backend_wx.cursord 字典已被弃用。这使得 GTK 模块可以在无头环境中导入。

杂项弃用#

  • is_url 和 URL_REGEX 已被弃用。（它们之前在顶层 matplotlib 模块中定义。）

  • ArrowStyle.beginarrow 和 ArrowStyle.endarrow 属性已弃用；使用 arrow 属性来定义箭头的所需头尾。

  • backend_pgf.LatexManager.str_cache 已被弃用。

  • backends.qt_compat.ETS 和 backends.qt_compat.QT_RC_MAJOR_VERSION 已被弃用，没有替代品。

  • blocking_input 模块已被弃用。取而代之的是，使用 canvas.start_event_loop() 和 canvas.stop_event_loop()，并在需要时连接事件回调。

  • cbook.report_memory 已被弃用；请改用 psutil.virtual_memory。

  • cm.LUTSIZE 已被弃用。请改用 rcParams["image.lut"] (default: 256)。此值仅影响模块导入时生成的默认颜色图的量化级别。

  • Collection.__init__ 之前在未指定 offsets 的情况下忽略了 transOffset。未来，无论是否指定 offsets，transOffset 都将开始生效。在此期间，如果您希望设置 transOffset，请显式调用 Collection.set_offset_transform。

  • Colorbar.patch 已被弃用；此属性不再正确更新。

  • ContourLabeler.get_label_width 已被弃用。

  • dviread.PsfontsMap 现在对于缺失的字体会引发 LookupError 而不是 KeyError。

  • Dvi.baseline 已被弃用（没有替代品）。

  • dviread.find_tex_file 的 format 参数已被弃用（没有替代品）。

  • FancyArrowPatch.get_path_in_displaycoord 和 ConnectionPath.get_path_in_displaycoord 已被弃用。显示坐标中的路径仍然可以通过 patch.get_transform().transform_path(patch.get_path()) 获得，就像其他补丁一样。

  • font_manager.win32InstalledFonts 和 font_manager.get_fontconfig_fonts 辅助函数已被弃用。

  • 从 aspect 开始的 imshow 的所有参数将变为仅关键字参数。

  • QuadMesh.convert_mesh_to_paths 和 QuadMesh.convert_mesh_to_triangles 已被弃用。QuadMesh.get_paths() 可以作为前者的替代；后者没有替代方案。

  • ScalarMappable.callbacksSM 已被弃用。请改用 ScalarMappable.callbacks。

  • streamplot.get_integrator 已被弃用。

  • style.core.STYLE_FILE_PATTERN、style.core.load_base_library 和 style.core.iter_user_libraries 已被弃用。

  • SubplotParams.validate 已弃用。使用 SubplotParams.update 来更改 SubplotParams ，同时始终保持其处于有效状态。

  • .TexManager 的 grey_arrayd、font_family、font_families 和 font_info 属性已被弃用。

  • Text.get_prop_tup 已被弃用，没有替代方案（因为 Text 类无法知道后端是否需要更新缓存，例如当文本颜色改变时）。

  • Tick.apply_tickdir 实际上并没有更新用于绘制刻度的现有 Line2D 对象上的刻度标记，并且已被弃用；请改用 Axis.set_tick_params。

  • tight_layout.auto_adjust_subplotpars 已被弃用。

  • axisartist 类的 grid_info 属性已被弃用。

  • axisartist.clip_path 已被弃用，没有替代品。

  • axes_grid1.axes_grid.CbarAxes 和 axes_grid1.axisartist.CbarAxes 已被弃用（它们现在基于所属的轴类动态生成）。

  • axes_grid1.Divider.get_vsize_hsize 和 axes_grid1.Grid.get_vsize_hsize 方法已被弃用。如有需要，请复制其实现。

  • AxesDivider.append_axes(..., add_to_figure=False) 已被弃用。如果需要，请使用 ax.remove() 从图形中移除 Axes。

  • FixedAxisArtistHelper.change_tick_coord 已被弃用，没有替代方案。

  • floating_axes.GridHelperCurveLinear.get_boundary 已被弃用，没有替代方案。

  • ParasiteAxesBase.get_images_artists 已被弃用。

  • “units finalize” 信号（之前由 Axis 实例发出）已被弃用。请改为连接到“units”。

  • 将格式化参数按位置传递给 stem() 已被弃用

plot_directive 弃用#

:encoding: 选项在 Matplotlib 1.3.1 之后对 .. plot 指令已无效果，现已被弃用。

matplotlib.sphinxext.plot_directive 中的以下辅助函数已被弃用：

测试支持#

matplotlib.test() 已被弃用#

使用命令行中的 pytest 运行测试。变量 matplotlib.default_test_modules 仅用于 matplotlib.test()，因此也被弃用。

要测试已安装的副本，请确保使用 --pyargs 指定 matplotlib 和 mpl_toolkits:

pytest --pyargs matplotlib.tests mpl_toolkits.tests

更多详情请参见 测试。

未使用的 pytest 装置和标记#

固定装置 matplotlib.testing.conftest.mpl_image_comparison_parameters 在 Matplotlib 内部未被使用。如果您使用此功能，请将其复制到您的代码库中。

@pytest.mark.style 标记已弃用；请使用 @mpl.style.context，它具有相同的效果。

在 AxesLocator 和 Divider.locate 中支持 nx1 = None 或 ny1 = None#

在 axes_grid1.axes_divider 中，各种内部API将停止支持传递 nx1 = None 或 ny1 = None 来表示 nx + 1 或 ny + 1，这是为了准备可能的未来API，该API允许对分隔符进行索引和切片（可能是 divider[a:b] == divider.new_locator(a, b)，但也可能是 divider[a:] == divider.new_locator(a, <end>)）。面向用户的 Divider.new_locator API 不受影响——它根据需要正确地规范化 nx1 = None 和 ny1 = None。

移除#

以下已弃用的API已被移除：

移除的行为#

更严格的函数参数验证#

  • 调用 Figure.add_axes 时不带参数将引发错误。添加一个自由浮动的轴需要一个位置矩形。如果你想让一个轴填充整个图形，请改用 Figure.add_subplot。

  • Figure.add_subplot 验证其输入；特别是对于 add_subplot(rows, cols, index)，所有参数必须是整数。以前字符串和浮点数被接受并转换为整数。

  • 将 None 作为 which 参数传递给 autofmt_xdate 不再支持；请改用其更明确的同义词 which="major"。

  • 设置 eventplot() 或 EventCollection 的 orientation 为 "none" 或 None 不再被支持；请改为设置为 "horizontal"。此外，两种方向（"horizontal" 和 "vertical"）现在区分大小写。

  • 同时向使用颜色映射的函数（如 scatter() 和 imshow()）传递参数 norm 和 vmin/vmax 已不再支持。应使用 norm=LogNorm(min_val, max_val) 代替 norm=LogNorm(), vmin=min_val, vmax=max_val。vmin 和 vmax 应仅在不设置 norm 的情况下使用。

  • 在 Axes.pie 中，将 None 作为 radius 或 startangle 参数传递不再被接受；请分别使用显式的默认值 1 和 0 代替。

  • 将 None 作为 Axes.pie 的 normalize 参数传递（以前的默认值）不再被接受，饼图现在默认总是被归一化。如果你希望绘制一个不完整的饼图，请显式传递 normalize=False。

  • 不再支持向 subplot_class_factory 传递 None 。请显式传递基类 Axes 。

  • 不再支持将多个键作为单个逗号分隔的字符串或多个参数传递给 ToolManager.update_keymap；请改为将键作为字符串列表传递。

  • 传递 None 作为破折号偏移量不再被接受，因为这在所有情况下从未被统一实现，例如在矢量输出中。请将偏移量设置为 0。

  • 使用 Artist.set_contains 设置自定义方法覆盖 Artist.contains 已被移除，同样被移除的还有 Artist.get_contains。没有替代方法，但您仍然可以使用 Artist.set_picker 自定义拾取事件。

  • semilogx, semilogy, loglog, LogScale, 和 SymmetricalLogScale 过去接受依赖于轴方向的关键字参数（如 "basex" 对 "basey"，"subsx" 对 "subsy"，"nonposx" 对 "nonposy"）；这些参数名称已被移除，取而代之的是 "base", "subs", "nonpositive"。这一改动也影响了例如 ax.set_yscale("log", basey=...)，现在必须写作 ax.set_yscale("log", base=...)。

    从“nonpos”到“nonpositive”的改变也影响了 LogTransform、InvertedLogTransform、SymmetricalLogTransform 等。

    要在 loglog 图的 x 轴和 y 轴上使用 不同 的基数，例如使用 ax.set_xscale("log", base=10); ax.set_yscale("log", base=2)。

  • 向 parasite_axes_class_factory、parasite_axes_auxtrans_class_factory、host_axes_class_factory 传递 None 或不传递参数不再被接受；请传递一个明确的基类。

现在对大小写敏感性有更严格的执行#

  • 在 Artist.set 和 Artist.update 中，大写或混合大小写的属性名不再被规范化为小写。这允许传递诸如 patchA 或 UVC 的名称。

  • 不区分大小写的 capstyles 和 joinstyles 不再转换为小写；请将 capstyles（“miter”、“round”、“bevel”）和 joinstyles（“butt”、“round”、“projecting”）作为小写传递。

  • 使用 PGF 后端在 PDF 中保存元数据时，不再将键转换为小写。只有 PDF 规范中列出的（以及 PdfPages 文档中列出的）规范大小写的键才会被接受。

Tick 属性的隐式初始化#

Tick 构造函数不再通过 _get_tick1line、_get_tick2line、_get_gridline、_get_text1 和 _get_text2 初始化属性 tick1line、tick2line、gridline、label1 和 label2。请直接在子类的 __init__ 中设置属性。

移除旧文件模式标志#

传递给 cbook.to_filehandle 和 cbook.open_file_cm 的包含 "U" 的标志不再被接受。这与它们在 Python 3.9 中从 open 中移除的情况一致。

切换 Axes.get_navigate 的键盘映射已被移除#

这包括数字按键事件和 rcParams。

TTFPATH 和 AFMPATH 环境变量#

对（未记录的）``TTFPATH`` 和 AFMPATH 环境变量的支持已被移除。请使用 matplotlib.font_manager.fontManager.addfont() 注册额外的字体。

模块#

  • matplotlib.backends.qt_editor.formsubplottool；请改用 matplotlib.backends.backend_qt.SubplotToolQt。

  • matplotlib.compat

  • matplotlib.ttconv

  • 基于 Qt4 的后端，qt4agg 和 qt4cairo，已被移除。Qt4 在2015年已达到其生命周期终点，并且对于较新版本的 Python，没有发布 PyQt4 或 PySide。请使用 Qt5 或 Qt6 后端之一。

类、方法和属性#

以下模块级别的类/变量已被移除：

  • backend_bases.StatusbarBase 及其所有子类，以及 StatusBarWx；消息显示在工具栏中

  • backend_pgf.GraphicsContextPgf

  • MODIFIER_KEYS、SUPER、ALT、CTRL 和 SHIFT 是 matplotlib.backends.backend_qt5agg 和 matplotlib.backends.backend_qt5cairo 中的内容

  • backend_wx.DEBUG_MSG

  • dviread.Encoding

  • Fil, Fill, Filll, NegFil, NegFill, NegFilll, 以及 SsGlue 来自 mathtext；直接使用 Glue("fil") 等构造粘连实例。

  • mathtext.GlueSpec

  • OldScalarFormatter、IndexFormatter 和 IndexDateFormatter；请改用 FuncFormatter

  • OldAutoLocator

  • AVConvBase, AVConvWriter 和 AVConvFileWriter。Debian 8 (2015, EOL 06/2020) 和 Ubuntu 14.04 (EOL 04/2019) 是最后一批搭载 avconv 的 Debian 和 Ubuntu 版本。通过将 rcParams["animation.ffmpeg_path"] (default: 'ffmpeg') 设置为 "avconv"，仍然可以使用基于 FFmpeg 的写入器强制使用 avconv。

  • matplotlib.axes._subplots._subplot_classes

  • axes_grid1.axes_rgb.RGBAxesBase；请使用 RGBAxes 代替

以下类属性已被移除：

  • backend_pgf.LatexManager.latex_stdin_utf8

  • backend_pgf.PdfPages.metadata

  • ContourSet.ax 和 Quiver.ax；使用 ContourSet.axes 或 Quiver.axes 与其他艺术家一样

  • DateFormatter.illegal_s

  • dates.YearLocator.replaced; YearLocator 现在是 RRuleLocator 的子类，并且属性 YearLocator.replaced 已被移除。对于需要修改此属性的刻度位置，可以使用自定义的 rrule 和 RRuleLocator 代替。

  • FigureManagerBase.statusbar；消息显示在工具栏中

  • FileMovieWriter.clear_temp

  • mathtext.Glue.glue_subtype

  • MovieWriter.args_key、MovieWriter.exec_key 和 HTMLWriter.args_key

  • NavigationToolbar2QT.basedir；图标的基目录是 os.path.join(mpl.get_data_path(), "images")

  • NavigationToolbar2QT.ctx

  • NavigationToolbar2QT.parent；要访问父窗口，请使用 toolbar.canvas.parent() 或 toolbar.parent()

  • prevZoomRect、retinaFix、savedRetinaImage、wxoverlay、zoomAxes、zoomStartX 和 zoomStartY 是 NavigationToolbar2Wx 的属性。

  • NonUniformImage.is_grayscale, PcolorImage.is_grayscale，与 AxesImage.is_grayscale 保持一致。（注意，以前这些属性只能在 渲染图像后 才能使用）。

  • RendererCairo.fontweights, RendererCairo.fontangles

  • .RendererPdf、.PdfFile 和 .RendererPS 的 used_characters

  • LogScale.LogTransform、LogScale.InvertedLogTransform、SymmetricalScale.SymmetricalTransform 和 SymmetricalScale.InvertedSymmetricalTransform；直接从 matplotlib.scale 访问变换类

  • .TexManager 的 cachedir、rgba_arrayd、serif、sans_serif、cursive 和 monospace 属性

  • axleft、axright、axbottom、axtop、axwspace 和 axhspace 是 widgets.SubplotTool 的属性；访问相应滑块的 ax 属性

  • widgets.TextBox.params_to_disable

  • angle_helper.LocatorBase.den；它已被重命名为 nbins

  • axes_grid.CbarAxesBase.cbid 和 axes_grid.CbarAxesBase.locator；请改用 mappable.colorbar_cid 或 colorbar.locator。

以下类方法已被移除：

  • Axes.update_datalim_bounds；使用 ax.dataLim.set(Bbox.union([ax.dataLim, bounds]))

  • Axis 和 Locator 的 pan 和 zoom 方法已被移除；平移和缩放现在通过 Axes 的 start_pan、drag_pan 和 end_pan 方法实现。

  • .BboxBase.inverse_transformed；在 inverted() 变换上调用 BboxBase.transformed

  • Collection.set_offset_position 和 Collection.get_offset_position 已被移除；Collection 类的 offset_position 现在为“屏幕”

  • Colorbar.on_mappable_changed 和 Colorbar.update_bruteforce；请改用 Colorbar.update_normal()

  • docstring.Substitution.from_params 已被移除；请直接赋值给 docstring.Substitution 的 params。

  • DraggableBase.artist_picker; 设置艺术家的选择器

  • DraggableBase.on_motion_blit；请改用 DraggableBase.on_motion

  • FigureCanvasGTK3._renderer_init

  • Locator.refresh() 及其相关辅助方法 NavigationToolbar2.draw() 和 ToolViewsPositions.refresh_locators()

  • .RendererPdf、.PdfFile 和 .RendererPS 的 track_characters 和 merge_used_characters

  • RendererWx.get_gc

  • SubplotSpec.get_rows_columns；请改用 GridSpec.nrows、GridSpec.ncols、SubplotSpec.rowspan 和 SubplotSpec.colspan 属性。

  • ScalarMappable.update_dict、ScalarMappable.add_checker() 和 ScalarMappable.check_update()；在 ScalarMappable.callbacks 中注册一个回调以接收更新通知

  • TexManager.make_tex_preview 和 TexManager.make_dvi_preview

  • .widgets.SubplotTool 的 funcleft、funcright、funcbottom、functop、funcwspace 和 funchspace 方法

  • axes_grid1.axes_rgb.RGBAxes.add_RGB_to_figure

  • axisartist.axis_artist.AxisArtist.dpi_transform

  • axisartist.grid_finder.MaxNLocator.set_factor 和 axisartist.grid_finder.FixedLocator.set_factor；现在因子总是1

函数#

  • bezier.make_path_regular 已被移除；请改用 Path.cleaned() （或 Path.cleaned(curves=True) 等），但请注意这些方法会在路径末尾添加一个 STOP 代码。

  • bezier.concatenate_paths 已被移除；请改用 Path.make_compound_path()。

  • cbook.local_over_kwdict 已被移除；请改用 cbook.normalize_kwargs。

  • qt_compat.is_pyqt5 由于 PyQt6 的发布已被移除。可以使用 QtCore.qVersion() 检查 Qt 版本。

  • testing.compare.make_external_conversion_command 已被移除。

  • axes_grid1.axes_rgb.imshow_rgb 已被移除；请改用 imshow(np.dstack([r, g, b]))。

参数#

  • Axes.annotate 和 pyplot.annotate 的 s 参数不再支持；请使用新的名称 text。

  • matplotlib.axes.Axes.draw 的 inframe 参数已被移除；请改用 Axes.redraw_in_frame。

  • cbook.normalize_kwargs 的 必需、禁止 和 允许 参数已被移除。

  • 所有渲染器类的 draw_tex 方法中的 ismath 参数已被移除（因为调用 draw_tex — 不要与 draw_text 混淆！— 意味着整个字符串无论如何都应该传递给 usetex 机制）。同样，文本机制在调用 draw_tex 时将不再传递 ismath 参数（这应该只对后端实现者有影响）。

  • Figure.savefig 的 quality、optimize 和 progressive 参数（仅影响 JPEG 输出）已被移除，以及相应的 print_jpg 方法中的这些参数。JPEG 输出选项可以通过直接在 pil_kwargs 中传递相关参数来设置。

  • FileMovieWriter 的 clear_temp 参数已被移除；放置在临时目录中的文件（使用 frame_prefix=None，默认值）将被清除；放置在其他位置的文件则不会。

  • mathtext.Glue 的 copy 参数已被移除。

  • Path.cleaned() 的 quantize 参数已被移除。

  • RendererPgf 的 dummy 参数已被移除。

  • Shadow 的 props 参数已被移除；请改用关键字参数。

  • matplotlib.test 的 recursionlimit 参数已被移除。

  • Tick 的 label 参数没有效果，已被移除。

  • MaxNLocator 不再同时接受位置参数和关键字参数 nbins ，因为它们指定了相同的量。

  • axes_grid.Grid、axes_grid.ImageGrid、axes_rgb.make_rgb_axes 和 axes_rgb.RGBAxes 的 add_all 参数已被移除；API 的行为始终如同 add_all=True。

  • axisartist.angle_helper.LocatorBase 的 den 参数已被移除；请改用 nbins。

  • AnnotationBbox.get_fontsize 的 s 关键字参数没有效果，已被移除。

  • Collection 类的 offset_position 关键字参数已被移除；现在 offset_position 是“屏幕”。

  • StreamplotSet 的任意关键字参数已无效并已被移除。

  • Axes.set_xticklabels / Axes.set_yticklabels 的 fontdict 和 minor 参数现在仅支持关键字形式。

  • 除了 nrows 和 ncols 之外，Figure.subplots 的所有参数现在都是仅关键字参数；这避免了在表示 subplot(1, 1, 1) 时误写为 subplots(1, 1, 1)，但实际上得到的是 subplots(1, 1, sharex=1)。

  • pyplot.tight_layout 的所有参数现在都是仅关键字参数，以与 Figure.tight_layout 保持一致。

  • ColorbarBase 现在只接受一个位置参数，即创建它的 Axes ，所有其他选项都必须作为关键字参数提供。现在已移除因可映射对象而覆盖关键字参数的警告。

  • 不再支持省略 matplotlib.axes.Axes.draw 的 renderer 参数；请改用 axes.draw_artist(axes)。

  • 传递 ismath="TeX!" 给 RendererAgg.get_text_width_height_descent 不再被支持；请改为传递 ismath="TeX"。

  • 对 matplotlib.axes.Axes.draw 方法签名的更改使其与其他所有艺术家一致；因此，Artist.draw 的额外参数也已被移除。

rcParams#

  • animation.avconv_path 和 animation.avconv_args rcParams 已被移除。

  • animation.html_args rcParam 已被移除。

  • keymap.all_axes rcParam 已被移除。

  • mathtext.fallback_to_cm rcParam 已被移除。请改用 rcParams["mathtext.fallback"] (default: 'cm')。

  • savefig.jpeg_quality rcParam 已被移除。

  • text.latex.preview rcParam 已被移除。

  • 以下在 rcsetup 中定义的已弃用的 rcParams 验证器已被移除：

    • validate_alignment

    • validate_axes_titlelocation

    • validate_axis_locator

    • validate_bool_maybe_none

    • validate_fontset

    • validate_grid_axis

    • validate_hinting

    • validate_legend_loc

    • validate_mathtext_default

    • validate_movie_frame_fmt

    • validate_movie_html_fmt

    • validate_movie_writer

    • validate_nseq_float

    • validate_nseq_int

    • validate_orientation

    • validate_pgf_texsystem

    • validate_ps_papersize

    • validate_svg_fonttype

    • validate_toolbar

    • validate_webagg_address

  • 一些 rcParam 验证变得更加严格：

开发变化#

增加到依赖项的最低支持版本#

对于 Matplotlib 3.5，最低支持版本 和一些 可选依赖 正在更新：

依赖

min in mpl3.4

min in mpl3.5

NumPy

1.16

1.17

Tk (可选)

8.3

8.4

这与我们的 最小依赖政策 和 NEP29 一致。

新的轮子架构#

已添加以下轮子：

  • Python 3.10

  • PyPy 3.7

  • Apple Silicon 上的 macOS（包括 arm64 和 universal2）

新的构建依赖项#

版本控制已从捆绑的 versioneer 切换到使用 release-branch-semver 版本方案的 setuptools-scm。后者维护良好，但可能需要对打包脚本进行轻微修改。

setuptools-scm-git-archive 插件也用于一致的版本导出。

数据目录不再是可选的#

从历史上看，mpl-data 目录一直是可选的（示例文件是不必要的，如果提供了对系统字体的适当依赖，字体可以被删除）。尽管示例文件仍然是可选的，但它们已经大大减少，我们现在认为该目录是必需的。

具体来说，那里的 matplotlibrc 文件用于运行时验证，必须存在。如果需要，打包者仍可以将字体链接到系统版本。

新的运行时依赖项#

用于类型 42 子集化的 fontTools#

一个新的依赖 fontTools 被集成到 Matplotlib 3.5 中。它旨在与 PS/EPS 和 PDF 文档一起使用；并处理 Type 42 字体子集化。

LaTeX 中的下划线支持#

underscore 包现在是 LaTeX 中支持下划线的要求。

这与我们的 最小依赖策略 是一致的。

Matplotlib 特定的构建选项已从 setup.cfg 移至 mplsetup.cfg#

为了避免与 setuptools 使用 setup.cfg 产生冲突，Matplotlib 特定的构建选项已从 setup.cfg 移至 mplsetup.cfg。相应地，setup.cfg.template 已被重命名为 mplsetup.cfg.template。

请注意，此配置文件的路径仍可以通过 MPLSETUPCFG 环境变量设置，这使得在此更改前后可以继续使用同一个文件。

On this page