3.5.0 版 API 变更#

行为变更#

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

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

由于此 API 为临时性 API，我们未设置弃用期即更改了此参数名称。

Axes 子对象不再按类型分离#

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

现在，子对象不再按类型分离，子列表属性在访问时动态生成。因此，Artist 现在将始终出现在正确的子列表中；例如，如果在 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://pythonlang.cn/dev/peps/pep-0565/）。

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

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

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

warnings.filterwarnings("always", DeprecationWarning)

Artist.set 按给定顺序应用 artist 属性#

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

pcolor(mesh) 的着色默认为自动#

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

将 Z(M, N)、x(N)、y(M) 以及 shading='flat' 传递给 pcolormesh 现在将引发 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 生成的图像可能会观察到像素级别的差异，通常是对于恰好位于两个数据单元格边界的像素（目前没有面向用户的 axes 方法生成 NonUniformImage，并且只有 pcolorfast 可以生成 PcolorImage）。这些 artists 现在也变慢了，通常慢约 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"] (默认值: 'auto') 和 rcParams["lines.markerfacecolor"] (默认值: '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。此类型与用于填充等高线的 artist 匹配。

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

hatch.SmallFilledCircles 继承自 hatch.Circles#

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

使用对数范数的 hexbin#

如果使用了对数范数，hexbin 不再（错误地）为每个 bin 值加 1。

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

以前，传递给 rcParams["date.converter"] 的无效值（默认值: '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 contourf 多边形放置在级别之间#

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

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

AxesDivider.append_axes、AxesDivider.new_horizontal 和 AxesDivider.new_vertical 现在默认使用 rcParams["figure.subplot.wspace"] (默认值: 0.2) 和 rcParams["figure.subplot.hspace"] (默认值: 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 子对象子列表的修改#

更多信息请参见 Axes 子对象不再按类型分离；以下子列表的修改已弃用

  • 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 绘制。

  • 如果您需要将纯数值数据绘制为 Matplotlib 日期格式 或需要设置时区，请在 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 当前会移除任何可见的 axes 主网格线。此行为已弃用；请显式调用 ax.grid(False) 来移除网格线。

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

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

Selector 控件 API 的统一和清理#

Selector 控件的 API 已统一为使用

  • 用于表示选择的 Artist 属性的 *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* 已弃用。如果您想更改选择器 artist 属性，请使用 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（以及它们的共同基类 TickHelper）的 set_view_interval、set_data_interval 和 set_bounds 方法已弃用。请直接操作底层轴的视图和数据间隔。

print_ 方法中未使用的位置参数#

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

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 不再将输入强制转换为 str 类型#

在弃用期过后，预期为（非路径类）str 类型的 rcParams 将不再使用 str 强制转换非 str 类型的输入。这将避免后续代码中出现令人困惑的错误，例如列表输入被隐式转换为 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 类。

GTK、Qt 和 wx 后端中的 cursord#

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"] (默认值: 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 已弃用。显示坐标中的路径仍然可以获得，与其他 patches 一样，使用 patch.get_transform().transform_path(patch.get_path())。

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

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

  • 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 类动态生成）。

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

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

  • FixedAxisArtistHelper.change_tick_coord 已弃用，没有替代品。

  • floating_axes.GridHelperCurveLinear.get_boundary 已弃用，没有替代品。

  • ParasiteAxesBase.get_images_artists 已弃用。

  • “单位终结”信号（以前由 Axis 实例发出）已弃用。请改连接到“单位”信号。

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

plot_directive 弃用#

.. plot 指令的 :encoding: 选项自 Matplotlib 1.3.1 以来已无任何效果，现已弃用。

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，这是为了未来可能允许分割器索引和切片（可能是 divider[a:b] == divider.new_locator(a, b)，但也可能是 divider[a:] == divider.new_locator(a, <end>)）的 API 做准备。面向用户的 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"）现在区分大小写。

  • 不再支持同时将参数 *norm* 和 *vmin*/*vmax* 传递给使用颜色映射的函数，例如 scatter() 和 imshow()。请改用 norm=LogNorm(min_val, max_val)，而不是 norm=LogNorm(), vmin=min_val, vmax=max_val。*vmin* 和 *vmax* 仅应在未设置 *norm* 的情况下使用。

  • 不再接受将 *None* 作为 Axes.pie 的 *radius* 或 *startangle* 参数；请改用显式默认值 1 和 0。

  • 不再接受将 *None* 作为 Axes.pie 的 *normalize* 参数（以前的默认值），并且饼图将始终默认归一化。如果您希望绘制不完整的饼图，请显式传递 normalize=False。

  • 已移除对将 *None* 传递给 subplot_class_factory 的支持。请改显式传递基础 Axes 类。

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

  • 不再接受将虚线偏移量作为 *None* 传递，因为这从未普遍实现，例如对于矢量输出。请改将偏移量设置为 0。

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

  • semilogx、semilogy、loglog、LogScale 和 SymmetricalLogScale 以前接受取决于轴方向的关键字参数（"basex" vs "basey"，"subsx" vs "subsy"，"nonposx" vs "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

  • 移除了 matplotlib.backends.backend_qt5agg 和 matplotlib.backends.backend_qt5cairo 的 MODIFIER_KEYS、SUPER、ALT、CTRL 和 SHIFT。

  • 移除了 backend_wx.DEBUG_MSG

  • 移除了 dviread.Encoding

  • 移除了 mathtext 中的 Fil、Fill、Filll、NegFil、NegFill、NegFilll 和 SsGlue；请直接使用 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 版本。通过使用基于 FFmpeg 的写入器，并将 rcParams["animation.ffmpeg_path"]（默认值：'ffmpeg'）设置为 "avconv"，仍然可以强制使用 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()。

  • 移除了 NavigationToolbar2Wx 的 prevZoomRect、retinaFix、savedRetinaImage、wxoverlay、zoomAxes、zoomStartX 和 zoomStartY 属性。

  • 移除了 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 属性。

  • 移除了 widgets.SubplotTool 的 axleft、axright、axbottom、axtop、axwspace 和 axhspace 属性；请访问相应滑块的 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 现在是 "screen"。

  • 移除了 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。

  • 由于 PyQt6 的发布，qt_compat.is_pyqt5 已移除。可以使用 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 的 required、forbidden 和 allowed 参数。

  • 移除了所有渲染器类中 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 现在是 "screen"。

  • 传递给 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)。

  • 不再支持向 RendererAgg.get_text_width_height_descent 传递 ismath="TeX!"；请改传递 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"]（默认值：'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 验证变得更加严格

    • rcParams["axes.axisbelow"]（默认值：'line'）不再接受以 "line"（不区分大小写）开头的字符串作为 "line"；请改用 "line"（区分大小写）。

    • rcParams["text.latex.preamble"]（默认值：''）和 pdf.preamble 不再接受非字符串值。

    • 所有 *.linestyle rcParams 不再接受 offset = None；请改将偏移量设置为 0。

开发变更#

依赖项的最低支持版本提升#

对于 Matplotlib 3.5，最低支持版本 和一些 可选依赖项 正在升级

依赖项

mpl3.4 中的最低版本

mpl3.5 中的最低版本

NumPy

1.16

1.17

Tk (可选)

8.3

8.4

这与我们的 依赖版本策略 和 NEP29 一致。

新的 Wheel 架构#

已添加以下 Wheel：

  • Python 3.10

  • PyPy 3.7

  • Apple Silicon 上的 macOS（arm64 和 universal2）

新的构建依赖项#

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

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

数据目录不再是可选的#

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

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

新的运行时依赖项#

用于 Type 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 环境变量设置，这允许在此更改前后继续使用相同的文件。

在此页