API 变更 3.10.0#

行为变更#

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

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

SVG 输出：改进了可复现性#

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

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

只要绘图以确定性顺序添加剪切路径，这将实现可重复（又称可再现、确定性）的 SVG 输出。

ft2font 类现在是最终的#

ft2font 类 ft2font.FT2Font 和 ft2font.FT2Image 现在是最终的，不能再被子类化。

InsetIndicator 艺术家#

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 是硬编码的。

子图#

Figure.subfigures 现在按行主序添加，以与 Figure.subplots 保持一致。subfigures 的返回值没有改变，但 fig.subfigs 的顺序改变了。

(子)图的 get_figure 方法#

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

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

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

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

以前，当坐标轴反转时，与 ConciseDateFormatter 关联的偏移字符串不会改变，因此偏移字符串指示的坐标轴方向是错误的。现在，当坐标轴反转时，偏移字符串的方向是正确的。

压缩布局中的 suptitle#

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

弃用#

绘图函数中的位置参数#

许多绘图函数将来会将位置参数限制在前几个参数。所有进一步的配置参数都必须作为关键字参数传递。这是为了强制执行更好的代码，并允许未来更改时降低破坏现有代码的风险。

更改 Figure.number#

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

PdfFile.hatchPatterns#

... 已弃用。

(子)图的 set_figure 方法#

...已弃用，将来将始终引发异常。(子)图的父图和根图在实例化时设置，不能更改。

Poly3DCollection.get_vector#

... 已弃用，无替代。

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

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

matplotlib.validate_backend#

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

matplotlib.sanitize_sequence#

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

ft2font 模块级常量被枚举替代#

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

移除 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 类需要完整的二维值数组 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

以前，如果输入一个掩码数组，集合中的多边形列表会缩小到有效多边形的大小，用户需要跟踪哪些多边形被绘制，并使用较小的“压缩”数组大小调用 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 以来，此键已无任何效果。

向 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 类已移除。现在，divider 实例的 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 变更#

axisartist.axes_grid 和 axisartist.axes_rgb 模块（它们提供了结合 axes_grid1 和 axisartist 功能的封装器）已移除；请直接使用例如 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 保持一致

在此页