API 变更 3.9.0

行为变更

plot() 简写格式将 "Cn" (n>9) 解释为颜色循环颜色

以前，plot(..., "-C11") 会被解释为请求使用线型 "-"、颜色 "C1"（颜色循环中的颜色 #1）和标记 "1"（"tri-down"）的绘图。现在，它被解释为请求使用线型 "-" 和颜色 "C11"（颜色循环中的颜色 #11）。

建议通过 marker 关键字参数明确传递有歧义的标记（例如 "1"）。如果需要简写形式，这些标记也可以通过将其放在颜色字符串之前来明确设置。

plot 的图例标签

以前，当绘制单个数据集时，如果将序列传递给 plot 的 label 参数，该序列会自动转换为字符串作为图例标签。现在，如果序列只有一个元素，该元素将成为图例标签。要保留旧行为，请在传递前将序列转换为字符串。

箱线图现在忽略被遮罩的数据点

boxplot 和 boxplot_stats 现在忽略输入数据中任何被遮罩的点。

axhspan 和 axvspan 现在返回 Rectangle 对象，而不是 Polygon 对象

此变更允许使用 axhspan 在极坐标轴上绘制环形图。

此变更也影响通过 axhspan 和 axvspan 构建的其他元素，例如 Slider.poly。

改进重叠 Axes 的平移/缩放事件处理

平移/缩放事件的转发现在由背景补丁的可见性（例如 ax.patch.get_visible()）和 axes 的 zorder 决定。

• 带有可见补丁的 Axes 会捕获事件，并且不会将其传递给下面的 Axes。只有包含事件且 zorder 最高（如果存在多个 zorder 相同的 Axes，则最后添加的 Axes 计数）的 Axes 会被触发。

• 带有不可见补丁的 Axes 对于事件也同样不可见，并且事件会传递给下面的 Axes。

要覆盖默认行为并显式设置 Axes 是否应转发导航事件，请使用 Axes.set_forward_navigation_events。

legend 的 loc='best' 现在考虑 Text 和 PolyCollections

legend 的位置选择现在在计算“不理想程度”（badness）时考虑 Text 和 PolyCollections 的存在。

注意：对于包含大量数据的图，best 选项可能已经相当慢。对于 PolyCollections，它在检查重叠时仅考虑 PolyCollections 的 Path 而非封闭区域，以减少额外延迟。然而，当图中存在大量 PolyCollections 需要检查时，它仍然可能非常慢。

未向 BboxTransform*-类传递 Bbox 时的异常

未向需要 Bbox 的 BboxTransform*-类（例如 BboxTransform）传递 Bbox 时引发的异常已从 ValueError 更改为 TypeError。

Cell 的 loc 参数不再接受 None

loc 参数的默认值已从 None 更改为 right，后者已经是默认位置。Cell 在调用时不带显式 loc 参数时的行为没有改变。

ContourLabeler.add_label 现在遵循 use_clabeltext

... 并相应地设置 Text.set_transform_rotates_text。

Line2D

在创建 Line2D 或使用 Line2D.set_xdata 和 Line2D.set_ydata 时，传递非序列的 x/y 数据现在会引发错误。

ScalarMappable 在设置数组时自动缩放其范数

以前，Collections 会将范数的自动缩放推迟到绘制时。现在已将其更改为在设置第一个数组时缩放范数，以与文档字符串保持一致并减少在绘制前访问范数时的意外行为。

SubplotParams 已从 matplotlib.figure 移至 matplotlib.gridspec

它仍然可以从 matplotlib.figure 导入，因此不需要更改现有代码。

PowerNorm 不再裁剪小于 vmin 的值

当 PowerNorm 上设置 clip=False（默认值）时，小于 vmin 的值现在会进行线性归一化。以前它们会被裁剪为零。这修复了与幂范数关联的颜色条显示问题。

基于 toolmanager 的工具的图像路径语义

以前，MEP22（"基于 toolmanager"）的工具会尝试相对于当前工作目录加载其图标（tool.image），或者作为备用方案，从 Matplotlib 自己的图像目录加载。由于这两种方法对于第三方工具来说都存在问题（最终用户可以随时更改当前工作目录，并且第三方无法在 Matplotlib 的图像目录中添加新图标），因此此行为已被弃用；现在，tool.image 被解释为相对于定义 Tool.image 类属性的源文件所在的目录。（将 tool.image 定义为绝对路径也有效，并且与新旧语义兼容。）

废弃

plot_date

自 Matplotlib 3.5 以来，plot_date 的使用已不再推荐，现在该函数已被正式废弃。

• datetime 类数据应直接使用 plot 绘制。

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

plot 的图例标签

以前，当绘制单个数据集时，如果将序列传递给 plot 的 label 参数，该序列会自动转换为字符串作为图例标签。此行为现已废弃，将来如果序列长度不为一（与多数据集行为一致，其中元素数量必须与数据集数量匹配），则会报错。要保留旧行为，请在传递前将序列转换为字符串。

boxplot 刻度标签

参数 labels 已重命名为 tick_labels，以提高清晰度并与 bar 保持一致。

混合使用位置参数和关键字参数来处理 legend 句柄和标签

以前这只会发出警告，但现在已被正式废弃。如果传递 handles 和 labels，它们必须要么都作为位置参数传递，要么都作为关键字参数传递。

在 PolarTransform 中应用 theta 变换

在 PolarTransform 和 InvertedPolarTransform 中应用 theta 变换已被废弃，并将在未来版本的 Matplotlib 中移除。当这些变换在外部使用时，目前这是默认行为，但仅在以下情况下生效：

• 一个轴与变换相关联。

• 该轴具有非零的 theta 偏移或 theta 值按顺时针方向增加。

要消除此警告并采用未来的行为，请设置 apply_theta_transforms=False。如果您需要保留 theta 值被变换的行为，请将 PolarTransform 与执行 theta 偏移和/或符号偏移的 Affine2D 变换链接起来。

TimerBase.start 的 interval 参数

在启动计时器时设置 interval 已被废弃。间隔可以在计时器构造函数中指定，或者通过设置 timer.interval 属性来指定。

axisartist 辅助函数的 nth_coord 参数用于固定轴

axisartist 中用于在直角坐标轴上生成“固定”轴（FixedAxisArtistHelperRectilinear）的辅助 API 不再接受 nth_coord 参数，因为该参数完全从（必需的）loc 参数推断，并且 nth_coord 和 loc 不一致是错误。

对于曲线坐标轴，nth_coord 参数仍然受支持（它影响刻度，而不是轴本身的位置），但为了与直角坐标轴情况一致，该参数将仅接受关键字参数。

rcsetup.interactive_bk、rcsetup.non_interactive_bk 和 rcsetup.all_backends

... 已被废弃，并替换为 matplotlib.backends.backend_registry.list_builtin，带以下参数：

• matplotlib.backends.BackendFilter.INTERACTIVE

• matplotlib.backends.BackendFilter.NON_INTERACTIVE

• None

分别。

杂项废弃

• backend_ps.get_bbox_header 被视为内部辅助函数

• BboxTransformToMaxOnly；如果您依赖此功能，请复制其代码

• ContourLabeler.add_label_clabeltext

• TransformNode.is_bbox；请改用 isinstance(..., BboxBase) 检查对象

• GridHelperCurveLinear.get_tick_iterator

移除

mpl.cm 中的顶级颜色映射注册和访问函数

作为颜色映射注册多步重构的一部分，以下函数已被移除：

• matplotlib.cm.get_cmap；如果您有一个 str，请改用 matplotlib.colormaps[name]。

  如果您有一个 str、None 或想要转换为 Colormap 对象的 matplotlib.colors.Colormap 对象，请使用 matplotlib.cm.ColormapRegistry.get_cmap。

• matplotlib.cm.register_cmap；请改用 matplotlib.colormaps.register。

• matplotlib.cm.unregister_cmap；请改用 matplotlib.colormaps.unregister。

• matplotlib.pyplot.register_cmap；请改用 matplotlib.colormaps.register。

matplotlib.pyplot.get_cmap 函数将保留以实现向后兼容性。

等高线标签

contour.ClabelText 和 ContourLabeler.set_label_props 已被移除。对于 contour.ClabelText(...) 的替代，请使用 Text(..., transform_rotates_text=True)；对于 ContourLabeler.set_label_props(label, text, color) 的替代，请使用 text.set(text=text, color=color, fontproperties=labeler.labelFontProps, clip_box=labeler.axes.bbox)。

ContourLabeler 的 labelFontProps、labelFontSizeList 和 labelTextsList 属性已被移除。请改用 labelTexts 属性和相应文本对象的字体属性。

num2julian、julian2num 和 JULIAN_OFFSET

... dates 模块的这些函数已被移除，无替代。它们是未文档化的且未导出。

Matplotlib 中的儒略日期是根据儒略日期纪元计算的：jdate = (date - np.datetime64(EPOCH)) / np.timedelta64(1, 'D')。反之，儒略日期转换为日期时间为 date = np.timedelta64(int(jdate * 24 * 3600), 's') + np.datetime64(EPOCH)。Matplotlib 使用 EPOCH='-4713-11-24T12:00'，因此 2000-01-01 12:00 是 2_451_545.0（参见 https://en.wikipedia.org/wiki/Julian_day）。

offsetbox 方法

offsetbox.bbox_artist 已被移除。这只是一个包装器，用于在文件中设置标志时调用 patches.bbox_artist，因此如果需要该行为，请直接使用它。

OffsetBox.get_extent_offsets 和 OffsetBox.get_extent 已被移除；OffsetBox 的所有子类中的这些方法也已被移除。要获取 offsetbox 范围，请改用 OffsetBox.get_bbox 而不是 get_extent，它直接返回 Bbox 实例。要同时获取子偏移量，请在触发绘制后对每个子项单独调用 get_offset，而不是使用 get_extent_offsets。

parse_fontconfig_pattern 在未知常量名时引发错误

以前，在像 DejaVu Sans:foo 这样的 fontconfig 模式中，未知的 foo 常量名会被默默忽略。现在这会引发错误。

tri 子模块

matplotlib.tri.* 子模块已被移除。所有功能都直接在 matplotlib.tri 中可用，应从那里导入。

Widget API

• CheckButtons.rectangles 和 CheckButtons.lines 已被移除；CheckButtons 现在使用 scatter 绘制自身。

• RadioButtons.circles 已被移除；RadioButtons 现在使用 scatter 绘制自身。

• MultiCursor.needclear 已被移除，无替代。

• 不再需要 TextBox.begin_typing 的未使用参数 x，现在已将其移除。

大多数 widget 参数已改为仅限关键字

在 Widgets 构造函数中，除了最前面的几个参数外，所有参数现在都必须作为关键字参数传递。通常，所有可选参数都是仅限关键字的。

Axes3D API

• Axes3D.unit_cube、Axes3D.tunit_cube 和 Axes3D.tunit_edges 已被移除，无替代。

• axes3d.vvec、axes3d.eye、axes3d.sx 和 axes3d.sy 已被移除，无替代。

传递给 _FixedAxisArtistHelperBase 的 nth_coord 和 loc 不一致

_FixedAxisArtistHelperBase 及其子类的 nth_coord 参数值现在从 loc 的值推断；传递不一致的值（例如，请求“顶部 Y 轴”或“左侧 X 轴”）不再有任何效果。

不再允许将未定义的 label_mode 传递给 Grid

... 这包括 mpl_toolkits.axes_grid1.axes_grid.Grid、mpl_toolkits.axes_grid1.axes_grid.AxesGrid 和 mpl_toolkits.axes_grid1.axes_grid.ImageGrid，以及从 mpl_toolkits.axisartist.axes_grid 导入的相应类。

请改用 label_mode='keep' 以获得之前不修改标签的行为。

draw_gouraud_triangle

... 已被移除。请改用 draw_gouraud_triangles。

自定义 Artist 中的 draw_gouraud_triangle 调用可以轻松替换为

self.draw_gouraud_triangles(gc, points.reshape((1, 3, 2)),
                            colors.reshape((1, 3, 4)), trans)

一个 draw_gouraud_triangles 方法可以从现有的 draw_gouraud_triangle 方法实现为

transform = transform.frozen()
for tri, col in zip(triangles_array, colors_array):
    self.draw_gouraud_triangle(gc, tri, col, transform)

杂项移除

以下项目以前已被替换，现在已被移除：

• matplotlib.axis.Axis.set_ticklabels 的 ticklabels 参数已重命名为 labels。

• Barbs.barbs_doc 和 Quiver.quiver_doc 已被移除。这些是文档字符串，不应作为命名的类成员访问，而应作为常规文档字符串访问。

• collections.PolyCollection.span_where 和 collections.BrokenBarHCollection；请改用 fill_between。

• Legend.legendHandles 未被文档化，已重命名为 legend_handles。

以下项目已被移除，无替代：

• TimedAnimation 及其子类的 repeat 属性，以及 FuncAnimation 的 save_count 属性被认为是私有属性，现已移除。

• matplotlib.backend.backend_agg.BufferRegion.to_string

• matplotlib.backend.backend_agg.BufferRegion.to_string_argb

• matplotlib.backends.backend_ps.PsBackendHelper

• matplotlib.backends.backend_webagg.ServerThread

• GridSpecBase.get_grid_positions 的 raw 参数

• matplotlib.patches.ConnectionStyle._Base.SimpleEvent

• mpl_toolkits.axisartist.AxisArtistHelper 的 passthru_pt 属性

开发变更

构建系统已移植到 Meson

Matplotlib 的构建系统已从 setuptools 移植到 meson-python 和 Meson。因此，开发和打包目的出现了一些变化。

1. 使用 pyproject.toml 的包通过 pip 安装时，默认使用构建隔离，这会干扰可编辑安装。因此，对于使用可编辑安装的开发人员，现在需要向 pip install 传递 --no-build-isolation 标志。这意味着所有构建时依赖项都必须在环境中可用才能进行可编辑安装。

2. 构建配置已从自定义的 mplsetup.cfg（也可通过 MPLSETUP 环境变量配置）移至 Meson 选项。这些选项可以使用 meson-python 的构建配置设置为 setup-args 指定。有关所有选项，请参阅 meson_options.txt。例如，包含以下内容的 mplsetup.cfg：

   [rc_options]
   backend=Agg
   
   [libs]
   system_qhull = True
   

   可以通过向 pip 传递以下参数来替换：

   --config-settings=setup-args="-DrcParams-backend=Agg"
   --config-settings=setup-args="-Dsystem-qhull=true"
   

   请注意，您必须使用 pip >= 23.1 才能传递多个设置。

3. 相关地，现在使用 Meson 的内置选项而不是自定义选项，例如，LTO 选项现在是 b_lto。

4. 在 Windows 上，Meson 会自动激活 Visual Studio 环境。但是，如果存在其他编译器，它不会这样做。如果您希望更改所选编译器的优先级，请参阅Meson 的文档。

5. 测试数据的安装以前由 mplsetup.cfg 控制，但现在已移至 Meson 的安装标签。要安装测试数据，请将 tests 标签添加到请求的安装中（确保包含现有标签，如下所示）：

   --config-settings=install-args="--tags=data,python-runtime,runtime,tests"
   

6. 使用 stubtest 检查类型存根（typing stubs）在可编辑安装下不易进行。目前，如果您希望运行 stubtest，我们建议使用常规（非可编辑）安装。

提高依赖项的最低支持版本

对于 Matplotlib 3.9，最低支持版本正在提高：

依赖项	mpl3.8 中的最小值	mpl3.9 中的最小值
NumPy	1.21.0	1.23.0
setuptools	42	64

这与我们的依赖项版本策略和SPEC 0一致。

为符合 setuptools_scm 的要求，setuptools 的最低版本已从 42 增加到 64。

扩展需要 C++17

Matplotlib 现在需要支持 C++17 的编译器才能构建其扩展。根据SciPy 的分析，所有受支持的平台都应该提供此功能。

Windows on ARM64 支持

从源代码构建时，Windows on ARM64 现在捆绑 FreeType 2.6.1 而不是 2.11.1。这可能会导致文本渲染发生微小变化，但应与其他所有平台保持一致。