3.10.0 版本 API 变更#

行为变更#

选择器组件的 onselect 参数变为可选#

EllipseSelector、LassoSelector、PolygonSelector 和 RectangleSelector 的 onselect 参数不再是必须的。

SVG 输出：提升了可重现性#

即使配置了静态的 svg.hashsalt 值，一些 SVG 格式的图表 在每次渲染时产生的输出也不同。

问题源于剪裁路径的非确定性 ID 生成方案；修复后引入了一种可重复的、单调递增的整数 ID 方案作为替代。

只要图表以确定性的顺序添加剪裁路径，这就能够实现可重复（即：可重现、确定性）的 SVG 输出。

ft2font 类现在为 final 类型#

ft2font 类 ft2font.FT2Font 和 ft2font.FT2Image 现在被定义为 final，不能再被继承。

InsetIndicator 艺术家对象（Artist）#

indicate_inset 和 indicate_inset_zoom 现在返回一个 InsetIndicator 实例。请使用该艺术家的 rectangle 和 connectors 属性来访问之前直接返回的对象。

imshow 的 interpolation_stage 默认值更改为 'auto'#

imshow 的 interpolation_stage 参数有了新的默认值 'auto'。对于上采样倍数小于三倍或下采样的图像，图像插值将在 'rgba' 空间进行；对于上采样三倍或以上的图像，图像插值则在 'data' 空间进行。

之前的默认值为 'data'，因此下采样图像在新的默认值下可能会有细微的变化。然而，新的默认值也避免了在下采样时彩色映射图中尖锐边界产生的浮点伪影。

可以通过将 interpolation_stage 参数或 rcParams["image.interpolation_stage"]（默认值：'auto'）设置为 'data' 来恢复之前的行为。

imshow 的 interpolation 默认值更改为 'auto'#

imshow 的 interpolation 参数有了新的默认值 'auto'（之前为 'antialiased'），以便与 interpolation_stage 保持一致，并且因为插值仅在下采样期间才会进行抗锯齿处理。传入 'antialiased' 仍然有效，其行为与 'auto' 完全相同，但不建议继续使用。

dark_background 和 fivethirtyeight 样式不再设置 savefig.facecolor 和 savefig.edgecolor#

使用这些样式时，rcParams["savefig.facecolor"]（默认值：'auto'）和 rcParams["savefig.edgecolor"]（默认值：'auto'）现在会继承 "auto" 的全局默认值，这意味着将使用实际的图形颜色。此前，这些 rcParams 被设置为与 rcParams["figure.facecolor"]（默认值：'white'）和 rcParams["figure.edgecolor"]（默认值：'white'）相同的值，即保存的图形总是使用主题颜色，即使由用户手动覆盖了设置；这种情况已不再发生。

此更改对于没有手动设置图形底色和边框颜色的用户应无影响。

为 QuiverKey 添加 zorder 选项#

zorder 现在可以用作 QuiverKey 的关键字参数。在此之前，该参数无效，因为 zorder 是硬编码的。

子图（Subfigures）#

Figure.subfigures 现在按行优先顺序添加，以与 Figure.subplots 保持一致。subfigures 的返回值未更改，但 fig.subfigs 的顺序已更改。

(Sub)Figure.get_figure#

...在未来将默认返回直接父级图形，这可能是一个 SubFigure。这将使默认行为与其他艺术家的 get_figure 方法保持一致。要控制此行为，请使用新引入的 root 参数。

transforms.AffineDeltaTransform 在轴限制更改时正确更新#

在此更改之前，包含 AffineDeltaTransform 的变换子图无法正确更新。此 PR 确保子变换的更改能够正确传递。

与 ConciseDateFormatter 关联的偏移字符串现在将在轴反转时随之反转#

此前，当轴被反转时，与 ConciseDateFormatter 关联的偏移字符串不会改变，导致偏移字符串指示的方向与实际轴方向相反。现在，当轴反转时，偏移字符串的方向也是正确的。

压缩布局（compressed layout）中的 suptitle#

压缩布局现在会自动将 suptitle 定位在顶部轴行的正上方。要保持标题在之前的位置，可以传入 in_layout=False，或者在 suptitle 调用中显式设置 y=0.98。

弃用#

绘图函数中的位置参数#

未来，许多绘图函数将仅限前几个参数使用位置参数。所有后续的配置参数必须作为关键字参数传递。这是为了加强代码质量，并允许在减少破坏现有代码风险的情况下进行未来更改。

更改 Figure.number#

更改 Figure.number 已被弃用。该值由 pyplot 用于标识图形。它必须与 pyplot 的内部状态保持同步，不应由用户修改。

PdfFile.hatchPatterns#

... 已弃用。

(Sub)Figure.set_figure#

...已弃用，未来将始终引发异常。(Sub)Figure 的父级和根级图形在实例化时设置，无法更改。

Poly3DCollection.get_vector#

... 已弃用，无替代品。

弃用了 matplotlib.patches._Styles 及其子类上的 register#

此方法在内部从未使用过。由于该方法中的内部检查，它仅接受嵌入在宿主类中的私有基类的子类，这使得它不太可能被外部使用。

matplotlib.validate_backend#

...已弃用。请改用 matplotlib.rcsetup.validate_backend。

matplotlib.sanitize_sequence#

...已弃用。请改用 matplotlib.cbook.sanitize_sequence。

ft2font 模块级常量被枚举类（enums）替换#

ft2font 级别的常量已转换为 enum 类，所有使用它们的 API 现在都接受/返回新类型。

以下常量现在是 ft2font.Kerning 的一部分（不带 KERNING_ 前缀）

  • KERNING_DEFAULT

  • KERNING_UNFITTED

  • KERNING_UNSCALED

以下常量现在是 ft2font.LoadFlags 的一部分（不带 LOAD_ 前缀）

  • LOAD_DEFAULT

  • LOAD_NO_SCALE

  • LOAD_NO_HINTING

  • LOAD_RENDER

  • LOAD_NO_BITMAP

  • LOAD_VERTICAL_LAYOUT

  • LOAD_FORCE_AUTOHINT

  • LOAD_CROP_BITMAP

  • LOAD_PEDANTIC

  • LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH

  • LOAD_NO_RECURSE

  • LOAD_IGNORE_TRANSFORM

  • LOAD_MONOCHROME

  • LOAD_LINEAR_DESIGN

  • LOAD_NO_AUTOHINT

  • LOAD_TARGET_NORMAL

  • LOAD_TARGET_LIGHT

  • LOAD_TARGET_MONO

  • LOAD_TARGET_LCD

  • LOAD_TARGET_LCD_V

以下常量现在是 ft2font.FaceFlags 的一部分

  • EXTERNAL_STREAM

  • FAST_GLYPHS

  • FIXED_SIZES

  • FIXED_WIDTH

  • GLYPH_NAMES

  • HORIZONTAL

  • KERNING

  • MULTIPLE_MASTERS

  • SCALABLE

  • SFNT

  • VERTICAL

以下常量现在是 ft2font.StyleFlags 的一部分

  • ITALIC

  • BOLD

FontProperties 初始化#

FontProperties 的初始化仅限于两种调用模式：

  • 单一位置参数，解释为 fontconfig 模式

  • 仅使用关键字参数来设置各个属性

所有其他先前支持的调用模式均已弃用。

AxLine 的 xy1 和 xy2 设置器#

这些设置器现在各接受一个单一参数，即作为元组的 xy1 或 xy2。旧形式（将 x 和 y 作为单独参数传递）已弃用。

在现有的非极坐标轴上调用 pyplot.polar()#

这目前会将数据绘制到非极坐标轴中，忽略“极坐标”意图。此使用场景已弃用，未来将引发错误。

将浮点值传递给 RendererAgg.draw_text_image#

传递给 x 和 y 参数的任何浮点值此前会被静默截断为整数。此行为现已弃用，应仅使用 int 值。

将浮点值传递给 FT2Image#

传递给 FT2Image 构造函数，或 FT2Image.draw_rect_filled 的 x0、y0、x1 和 y1 参数的任何浮点值此前会被静默截断为整数。此行为现已弃用，应仅使用 int 值。

boxplot 和 bxp 的 vert 参数，以及 rcParams["boxplot.vertical"]#

boxplot 和 bxp 上的 vert: bool 参数已被弃用。为了 API 一致性，已替换为 orientation: {"vertical", "horizontal"}。

用于控制 boxplot 方向的 rcParams["boxplot.vertical"] 已弃用，且无替代项。

此弃用目前标记为挂起状态，并将在 Matplotlib 3.11 中完全弃用。

violinplot 和 violin 的 vert 参数#

violinplot 和 violin 上的 vert: bool 参数已被弃用。为了 API 一致性，它将被替换为 orientation: {"vertical", "horizontal"}。

此弃用目前标记为挂起状态，并将在 Matplotlib 3.11 中完全弃用。

proj3d.proj_transform_clip#

... 已弃用，无替代品。

移除#

移除 ttconv#

matplotlib._ttconv 扩展已被移除。其大部分功能已被其他代码取代，唯一剩下的功能是在 PostScript 中以 Type 42 格式嵌入 TTF 字体。这现在使用 FontTools 库在 PS 后端完成。

移除 LocationEvent 中对 lastevent 的硬引用#

此引用此前用于检测是否离开轴，但硬引用会导致已关闭的 Figure 对象及其子级比预期存活更久。

ft2font.FT2Image.draw_rect 和 ft2font.FT2Font.get_xys#

... 已移除，因为它们未使用。

Tick.set_label、Tick.set_label1 和 Tick.set_label2#

... 已移除。从第三方代码调用这些方法通常没有效果，因为标签在绘图时会被刻度格式化程序覆盖。

mpl_toolkits.mplot3d.proj3d 中的函数#

transform 函数只是 proj_transform 的别名，请改用后者。

以下函数要么未使用（因此 Matplotlib 中不再需要），要么被视为私有。

  • ortho_transformation

  • persp_transformation

  • proj_points

  • proj_trans_points

  • rot_x

  • rotation_about_vector

  • view_transformation

get_tightbbox 中除 renderer 以外的参数#

... 现在为仅限关键字参数。这是为了保持一致性，且不同类具有不同的附加参数。

重命名方法参数以匹配基类#

Transform 子类中 transform_affine 和 transform_non_affine 的唯一参数已重命名为 values。

transforms.IdentityTransform.transform 的 points 参数已重命名为 values。

table.Cell.set_transform 的 trans 参数已重命名为 t，与 Artist.set_transform 保持一致。

axis.Axis.set_clip_path 和 axis.Tick.set_clip_path 的 clippath 参数已重命名为 path，与 Artist.set_clip_path 保持一致。

images.NonUniformImage.set_filternorm 的 s 参数已重命名为 filternorm，与 _ImageBase.set_filternorm 保持一致。

images.NonUniformImage.set_filterrad 的 s 参数已重命名为 filterrad，与 _ImageBase.set_filterrad 保持一致。

Annotation.contains 和 Legend.contains 的唯一参数已重命名为 mouseevent，与 Artist.contains 保持一致。

方法参数重命名#

BboxBase.padded 的 p 参数已重命名为 w_pad，与其他参数 h_pad 保持一致

LogLocator 的 numdecs 参数和属性#

... 已被移除且无替代项，因为它们无效。PolyQuadMesh 类需要完整的二维数组值 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

此前，如果输入了掩码数组（masked array），集合中的多边形列表会缩小到有效多边形的大小，用户需要跟踪哪些多边形被绘制，并用较小的“压缩”数组大小调用 set_array()。传递“压缩”后的扁平化数组值将不再有效，应将包含掩码在内的完整二维数组值传递给 PolyQuadMesh.set_array。ContourSet.collections ~~~~~~~~~~~~~~~~~~~~~~~~~~

... 已被移除。ContourSet 现在实现为单个路径 Collection，每个路径对应一个等值线级别，可能包括多个不相连的组件。

ContourSet.antialiased#

... 已被移除。请改用 get_antialiased 或 set_antialiased。注意 get_antialiased 返回一个数组。

ContourSet 的 tcolors 和 tlinewidths 属性#

... 已被移除。请改用 get_facecolor、get_edgecolor 或 get_linewidths。

ContourLabeler 的 calc_label_rot_and_inline 方法#

... 已被移除，无替代项。

ContourLabeler 的 add_label_clabeltext 方法#

... 已被移除。请改用 add_label。向 Figure.add_axes 传递额外的额外位置参数 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

此前传递给 Figure.add_axes 的除 rect 或现有 Axes 以外的位置参数会被忽略，现在这会被视为错误。

显式传递的艺术家对象将不再由 legend() 根据标签进行过滤#

此前，显式传递给 legend(handles=[...]) 的艺术家对象如果标签以底线开头会被过滤掉。此过滤器不再被应用；如果需要，请显式过滤掉此类艺术家（[art for art in artists if not art.get_label().startswith('_')]）。

注意，如果完全没有指定句柄，则默认设置仍然会过滤掉以底线开头的标签。

Annotation.contains 和 Legend.contains 的参数已重命名为 mouseevent#

... 与 Artist.contains 保持一致。

支持在 annotate(..., arrowprops={"frac": ...}) 中传递 "frac" 键#

... 已被移除。此键自 Matplotlib 1.5 起已无效。

将非 int 或非 int 序列传递给 Table.auto_set_column_width#

列号必须是整数，过去传递任何其他类型都会被有效地忽略。现在这已成为错误。

小部件#

*Selector 组件的 visible 属性获取器已被移除；请使用 get_visible 代替。

切换后端时图形自动关闭#

允许的后端切换（即那些不将一个 GUI 事件循环与另一个互换的切换）将不会关闭现有图形。如果需要，请在切换前调用 plt.close("all")。

FigureCanvasBase.switch_backends#

... 已移除，无替代项。

事件处理程序返回后访问 event.guiEvent#

... 不再受支持，事件处理程序返回后 event.guiEvent 将被设置为 None。对于某些 GUI 工具包，使用该事件是不安全的，尽管您可以自行承担风险分别暂存该对象。

PdfPages(keep_empty=True)#

零页 PDF 是无效的，因此向 backend_pdf.PdfPages 和 backend_pgf.PdfPages 传递 keep_empty=True，以及这些类的 keep_empty 属性，不再被允许，且不会创建空的 PDF 文件。

此外，backend_pdf.PdfPages 不再在实例化时立即创建目标文件，而是在保存第一个图形时才创建。要完全控制文件创建，请直接传递一个打开的文件对象作为参数（例如 with open(path, "wb") as file, PdfPages(file) as pdf: ...）。

backend_ps.psDefs#

backend_ps 中的 psDefs 模块级变量已被移除，无替代项。

PostScript 中的自动纸张尺寸选择#

不再支持将 rcParams["ps.papersize"]（默认值：'letter'）设置为 'auto'，或向 Figure.savefig 传递 papersize='auto'。要么传递显式的纸张类型名称，要么省略此参数以使用 rcParam 中的默认值。

RendererAgg.tostring_rgb 和 FigureCanvasAgg.tostring_rgb#

... 已被移除且无直接替代项。考虑改用 buffer_rgba，它应该能涵盖大多数用例。

TexManager.texcache#

... 被视为私有并已被移除。缓存目录的位置在文档字符串中已澄清。

cbook API 变更#

cbook.Stack 已被移除，无替代项。

Grouper.clean() 已被移除，无替代项。Grouper 类现在会自动清理自身。

cbook.get_sample_data 的 np_load 参数已被移除；get_sample_data 现在会自动加载 numpy 数组。如果需要，请改用 get_sample_data(..., asfileobj=False) 来获取数据文件的名称，然后将其传递给 open。

使用空 offsets 调用 paths.get_path_collection_extents#

使用空的 offsets 参数调用 get_path_collection_extents 存在歧义，不再允许。

bbox.anchored() 不带显式容器#

不再支持不向 BboxBase.anchored 传递 container 参数。

TransformNode 的 INVALID_NON_AFFINE、INVALID_AFFINE、INVALID 属性#

这些属性已被移除。

axes_grid1 API 变更#

anchored_artists.AnchoredEllipse 已被移除。请直接构造一个 AnchoredOffsetbox、一个 AuxTransformBox 和一个 Ellipse，如 Anchored Artists 所示。

axes_divider.AxesLocator 类已被移除。分割器实例的 new_locator 方法现在返回一个不透明的可调用对象（仍然可以传递给 ax.set_axes_locator）。

axes_divider.Divider.locate 已被移除；请使用 Divider.new_locator(...)(ax, renderer) 代替。

axes_grid.CbarAxesBase.toggle_label 已被移除。请改用操作颜色条标签（Colorbar.set_label）和刻度标签（Axes.tick_params）的标准方法。

inset_location.InsetPosition 已被移除；请改用 inset_axes。

axisartist API 变更#

提供结合了 axes_grid1 和 axisartist 功能的封装器的 axisartist.axes_grid 和 axisartist.axes_rgb 模块已被移除；请直接使用，例如 AxesGrid(..., axes_class=axislines.Axes)。

调用 axisartist Axes 来表示 axis 的用法已被移除；请显式调用该方法。

floating_axes.GridHelperCurveLinear.get_data_boundary 已被移除。使用 grid_finder.extreme_finder(*[None] * 5) 获取网格极值。

开发变更#

文档特定的自定义 Sphinx 角色现在是半公开的#

对于派生自 Matplotlib 的第三方包，我们使用的自定义角色可能会阻止 Sphinx 构建其文档。这些自定义 Sphinx 角色现已公开，仅供派生自 Matplotlib 类型的项目使用。详情请参阅 matplotlib.sphinxext.roles。

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

对于 Matplotlib 3.10，最低支持版本已提高

依赖项

mpl3.9 中的最低版本

mpl3.10 中的最低版本

Python

3.9

3.10

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

在此页