3.9.0 的 API 变更

行为变化

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

之前，plot(..., "-C11") 会被解释为请求使用线型“-”、颜色“C1”（颜色循环中的第1号颜色）和标记“1”（“向下三角形”）进行绘图。现在，它被解释为请求使用线型“-”和颜色“C11”（颜色循环中的第11号颜色）进行绘图。

建议使用 marker 关键字参数显式传递模糊标记（如“1”）。如果需要使用简写形式，也可以通过将这些标记放在颜色字符串 之前 来明确设置它们。

plot 的图例标签

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

箱线图现在忽略掩码数据点

boxplot 和 boxplot_stats 现在会忽略输入数据中的任何掩码点。

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

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

这一更改还影响通过 axhspan 和 axvspan 构建的其他元素，例如 Slider.poly。

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

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

• 带有可见补丁的轴会捕捉事件，并且不会将其传递给下方的轴。只有包含事件且 zorder 最高的轴会被触发（如果有多个轴具有相同的 zorder，则最后添加的轴有效）

• 带有不可见补丁的轴对事件也是不可见的，它们会被传递给下方的轴。

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

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

位置选择 legend 现在在 badness 计算中考虑了 Text 和 PolyCollections 的存在。

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

未传递 Bbox 给 BboxTransform* 类时抛出异常

当不传递 Bbox 给期望 Bbox 的 BboxTransform*-类时，例如 BboxTransform，异常已从 ValueError 更改为 TypeError。

loc 参数 Cell 不再接受 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 数据作为非序列传递现在会引发错误。

ScalarMappables 在设置数组时会自动调整其范数

集合之前在绘制时才推迟对范数的自动缩放。这一行为已更改为在设置第一个数组时即对范数进行缩放，以与文档字符串保持一致，并在绘制前访问范数时减少意外行为。

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 进行绘制。

• 如果你需要将纯数值数据绘制为 日期格式 或需要设置时区，请在 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 变换链接起来。

interval 参数 TimerBase.start

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

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

在 axisartist 中用于在直角坐标系上生成“固定”轴的辅助API（FixedAxisArtistHelperRectilinear）不再接受 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 中的顶级 cmap 注册和访问函数

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

• matplotlib.cm.get_cmap；如果你有一个 str，请使用 matplotlib.colormaps[name] 代替。

  如果你有一个 str、None 或一个 matplotlib.colors.Colormap 对象，并希望将其转换为 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 已被移除。请使用 Text(..., transform_rotates_text=True) 作为 contour.ClabelText(...) 的替代，并使用 text.set(text=text, color=color, fontproperties=labeler.labelFontProps, clip_box=labeler.axes.bbox) 作为 ContourLabeler.set_label_props(label, text, color) 的替代。

.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 已被移除，没有替代方案。

• 未使用的参数 x 对于 TextBox.begin_typing 是一个必需的参数，现在已被移除。

大多数小部件的参数已被设为仅关键字参数

在 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_triangle 方法实现 draw_gouraud_triangles 方法，如下所示:

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

杂项移除

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

• ticklabels 参数 matplotlib.axis.Axis.set_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

• raw 参数 GridSpecBase.get_grid_positions

• matplotlib.patches.ConnectionStyle._Base.SimpleEvent

• mpl_toolkits.axisartist.AxisArtistHelper 的 passthru_pt 属性

开发变更

构建系统移植到 Meson

Matplotlib 的构建系统已从 setuptools 迁移到 meson-python 和 Meson。因此，开发和打包方面有一些变化。

1. 通过 pip 安装带有 pyproject.toml 的包默认使用 构建隔离 ，这会干扰可编辑安装。因此，对于使用可编辑安装的开发者来说，现在需要向 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 检查类型存根在可编辑安装中不容易工作。目前，如果您希望运行 stubtest，我们建议使用正常（非可编辑）安装。

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

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

依赖	min in mpl3.8	min in 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。这可能会导致文本渲染的小变化，但应该与其他所有平台保持一致。