3.0.0 版 API 变更#

停止支持 Python 2#

Matplotlib 3 仅支持 Python 3.5 及更高版本。

后端加载的变更#

加载后端模块失败（非框架构建上的 macosx 和无头运行时上的 gtk3）现在会引发 ImportError（而不是 RuntimeError 和 TypeError）。

现在鼓励与交互式框架集成的第三方后端将全局值 required_interactive_framework 定义为以下值之一："qt5"、"qt4"、"gtk3"、"wx"、"tk" 或 "macosx"。此信息将用于确定是否可以从一个后端切换到另一个后端（具体来说，它们是否使用相同的交互式框架）。

Axes.hist2d 现在使用 pcolormesh 而不是 pcolorfast#

Axes.hist2d 现在使用 pcolormesh 而不是 pcolorfast，这将改善对数轴的处理。请注意，返回的 image 现在是 QuadMesh 类型，而不是 AxesImage 类型。

matplotlib.axes.Axes.get_tightbbox 现在包含所有艺术家#

对于 Matplotlib 3.0，现在由 matplotlib.axes.Axes.get_tightbbox 返回的边界框包含 所有 艺术家。

matplotlib.axes.Axes.get_tightbbox 添加了一个新的 kwarg bbox_extra_artists，用于手动指定要包含在紧密边界框计算中的轴上艺术家列表。

Figure.tight_layout、constrained_layout 和 fig.savefig('fname.png', bbox_inches="tight") 等布局工具使用 matplotlib.axes.Axes.get_tightbbox 来确定图中每个轴的边界，并调整轴之间的间距。

在 Matplotlib 2.2 中，get_tightbbox 开始包含轴上制作的图例，但仍排除了其他一些艺术家，例如可能溢出轴的文本。现在已将其扩展为包含 所有 艺术家。

此新默认设置可通过以下三种方式之一覆盖：

  1. 使要排除的艺术家成为图的子级，而不是轴的子级。例如，调用 fig.legend() 而不是 ax.legend()（可能使用 get_legend_handles_labels 从父轴收集句柄和标签）。

  2. 如果艺术家是轴的子级，请将艺术家属性 artist.set_in_layout(False) 设置为 False。

  3. 在新 kwarg bbox_extra_artists 中手动指定艺术家列表。

Text.set_text 使用字符串参数 None 将字符串设置为空#

当传递字符串值 None 时，Text.set_text 会将字符串设置为 "None"，因此后续调用 Text.get_text 将返回模糊的 "None" 字符串。

此更改将传递 None 的文本对象设置为空字符串，以便 Text.get_text 返回空字符串。

Axes3D.get_xlim、get_ylim 和 get_zlim 现在返回元组#

它们以前返回一个数组。返回元组与 2D 轴的行为一致。

font_manager.list_fonts 现在遵循平台的折叠大小写语义#

即，它仅在 Windows 上不区分大小写。

bar / barh 不再接受 left / bottom 作为第一个命名参数#

这些参数在 2.0 版中已重命名为 x / y，因为默认对齐方式从 edge 更改为 center。

未文档化选项的不同异常类型#

  • 向 ticklabel_format() 传递 style='comma' 从未受支持。它现在像所有其他不受支持的样式一样引发 ValueError，而不是 NotImplementedError。

  • 向 set_xlim() 传递未文档化的 xmin 或 xmax 参数会悄悄覆盖 left 和 right 参数。set_ylim() 和 3D 等效项（例如 set_zlim）也有类似的问题。如果它们会覆盖较早的限制参数，则会引发 TypeError。在 3.0 中，这些 kwarg 已弃用，但在 3.1 中，弃用已撤销。

改进了 Axes.margins 的调用签名#

Axes.margins 和 Axes3D.margins 不再接受任意关键字。因此，如果传递了未知 kwarg，将引发 TypeError；以前它们会被悄悄忽略。

如果传递了过多的位置参数，将引发 TypeError 而不是 ValueError，以与其他调用签名冲突保持一致。

如果仅传递两个位置参数，Axes3D.margins 现在会引发 TypeError，而不是发出弃用警告。要仅提供 x 和 y 边距，请使用关键字参数。

显式参数而非 *args, **kwargs#

PEP 3102 描述了仅限关键字的参数，这允许 Matplotlib 提供显式调用签名 - 我们以前使用 *args, **kwargs 和 kwargs.pop，现在我们可以公开命名参数。在某些地方，以前会忽略未知 kwargs，但现在会引发 TypeError，因为 **kwargs 已被移除。

清理装饰器和测试类在退出时不再销毁警告过滤器#

matplotlib.testing.decorators 中的装饰器和类在退出时不再销毁警告过滤器。相反，它们使用 warnings.catch_warnings 恢复测试开始前存在的警告过滤器。

非交互式 FigureManager 类现在是 FigureManagerBase 的别名#

FigureManagerPdf、FigureManagerPS 和 FigureManagerSVG 类以前是 FigureManagerBase 的空子类（即，不添加或覆盖任何属性或方法），现在是 FigureManagerBase 的直接别名。

image.thumbnail 输出的变更#

当调用 image.thumbnail 时，如果 preview=False，它以前返回一个画布类根据输出文件扩展名设置的图。它现在返回一个画布类为基本 FigureCanvasBase 的图（并依赖于 FigureCanvasBase.print_figure 来正确处理画布切换）。

作为此更改的副作用，image.thumbnail 现在也支持 .ps、.eps 和 .svgz 输出。

FuncAnimation 现在在闪烁时根据其 zorder 绘制艺术家#

FuncAnimation 现在在使用 blitting 时根据用户函数返回的艺术家的 zorder 绘制它们，而不是使用它们传递的顺序。但是，请注意，只尊重传递的艺术家的 zorder，因为它们绘制在任何现有艺术家之上（参见 #11369）。

等高线颜色自动缩放改进#

等高线级别选择现在对于 contour 和 contourf 相同；以前，对于 contour，数据范围之外的级别会被删除。（例外：如果在数据范围内没有找到等高线级别，则 levels 属性将替换为仅包含数据范围最小值的列表。）

当调用 contour 时，如果级别指定为目标数量而不是列表，并且使用 'extend' kwarg，则现在选择级别的方式使得一些数据通常会落在扩展范围内。

当调用 contour 时，如果使用 LogNorm 或 LogLocator，它现在将使用等高线级别的几何平均值而不是算术平均值来选择颜色。

Streamplot 最后一行和列修复#

修复了 streamplot 中最后一列和最后一行的缺失数据的错误。

将默认 AutoDateLocator kwarg interval_multiples 更改为 True#

日期刻度定位器 dates.AutoDateLocator kwarg interval_multiples 的默认值设置为 False，这在许多情况下会导致自动刻度不美观。现在更美观的 interval_multiples=True 是新默认值。请参阅下文以恢复旧行为。

(源代码、2x.png、png)

Axes.get_position 如果纵横比更改，现在返回实际位置#

Axes.get_position 以前返回原始位置，除非触发了绘制或调用了 Axes.apply_aspect，即使 kwarg original 设置为 False。现在调用 Axes.apply_aspect，因此 ax.get_position() 将返回新的修改后的位置。要恢复旧行为，请使用 ax.get_position(original=True)。

颜色条的刻度现在根据颜色条的大小进行调整#

如果颜色条是由非等高线或没有 BoundaryNorm 的可映射对象制成，或者未指定边界，则颜色条刻度现在会根据颜色条的大小进行调整。如果指定了边界等，颜色条会保持原始行为。

对数刻度六边形图的颜色条#

当使用 hexbin 并使用对数颜色刻度绘图时，颜色条刻度现在正确地进行对数缩放。以前，刻度值是线性缩放的 log(计数)。

PGF 后端现在明确将黑色文本设为黑色#

PGF 后端以前的行为是，指定为黑色的文本实际上是渲染 PGF 文件的默认颜色（当然通常是黑色）。新行为是黑色文本就是黑色，无论默认颜色如何。然而，这意味着无法回退到渲染器的默认颜色。

黑名单中的 rcparams 不再由 rcdefaults、rc_file_defaults、rc_file 更新#

rc 修饰函数 rcdefaults、rc_file_defaults 和 rc_file 现在会忽略 matplotlib.style.core.STYLE_BLACKLIST 集合中的 rcParams。特别是，这可以防止 backend 和 interactive rcParams 被这些函数错误地修改。

CallbackRegistry 现在使用标准库的 weakref.WeakMethod 存储回调#

具体而言，这意味着 CallbackRegistry.callbacks[signal] 现在是回调 ID 到 weakref.WeakMethod 的映射（即，它们需要首先不带参数调用以检索方法本身）。

关于 text.latex.unicode rcParam 的变更#

此 rcParam 现在默认为 True 并已弃用（即，在未来的 Matplotlib 版本中，将始终支持 unicode 输入）。

此外，底层实现现在使用 \usepackage[utf8]{inputenc} 而不是 \usepackage{ucs}\usepackage[utf8x]{inputenc}。

ArtistInspector.get_aliases 的返回类型已更改#

ArtistInspector.get_aliases 以前将别名集返回为 {fullname: {alias1: None, alias2: None, ...}}。在早期版本的 Python 中，dict-to-None 映射用于模拟集合。现在已将其替换为集合，即 {fullname: {alias1, alias2, ...}}。

此值也存储在 ArtistInspector.aliasd 中，该值也已更改。

移除 pytz 依赖#

由于 dateutil 和 pytz 都提供时区，并且 matplotlib 已经依赖于 dateutil，因此 matplotlib 现在将在内部使用 dateutil 时区并移除对 pytz 的冗余依赖。虽然首选 dateutil 时区（目前在 Python 文档中也推荐），但仍支持显式使用 pytz 时区。

弃用#

模块#

以下模块已弃用：

  • matplotlib.compat.subprocess。这是 Python 2 的变通方法，但所有功能现在都可以在 Python 3 标准库 subprocess 中找到。

  • matplotlib.backends.wx_compat。Python 3 仅与 wxPython 4 兼容，因此可以取消对 wxPython 3 或更早版本的支持。

类、方法、函数和属性#

以下类、方法、函数和属性已弃用：

  • RcParams.msg_depr, RcParams.msg_depr_ignore, RcParams.msg_depr_set, RcParams.msg_obsolete, RcParams.msg_backend_obsolete

  • afm.parse_afm

  • backend_pdf.PdfFile.texFontMap

  • backend_pgf.get_texcommand

  • backend_ps.get_bbox

  • backend_qt5.FigureCanvasQT.keyAutoRepeat（直接在事件处理程序中检查 event.guiEvent.isAutoRepeat() 以决定是否处理自动重复的按键）

  • backend_qt5.error_msg_qt, backend_qt5.exception_handler

  • backend_wx.FigureCanvasWx.macros

  • backends.pylab_setup

  • cbook.GetRealpathAndStat, cbook.Locked

  • cbook.is_numlike（请改用 isinstance(..., numbers.Number)），cbook.listFiles，cbook.unicode_safe

  • container.Container.set_remove_method,

  • contour.ContourLabeler.cl、.cl_xy 和 .cl_cvalues

  • dates.DateFormatter.strftime_pre_1900, dates.DateFormatter.strftime

  • font_manager.TempCache

  • image._ImageBase.iterpnames，请改用 interpolation_names 属性。（这会影响继承自 _ImageBase 的类，包括 FigureImage、BboxImage 和 AxesImage）

  • mathtext.unichr_safe（请改用 chr）

  • patches.Polygon.xy

  • table.Table.get_child_artists（请改用 get_children）

  • testing.compare.ImageComparisonTest, testing.compare.compare_float

  • testing.decorators.CleanupTest, testing.decorators.skip_if_command_unavailable

  • FigureCanvasQT.keyAutoRepeat（直接在事件处理程序中检查 event.guiEvent.isAutoRepeat() 以决定是否处理自动重复的按键）

  • FigureCanvasWx.macros

  • _ImageBase.iterpnames，请改用 interpolation_names 属性。（这会影响继承自 _ImageBase 的类，包括 FigureImage、BboxImage 和 AxesImage）

  • patches.Polygon.xy

  • texmanager.dvipng_hack_alpha

  • text.Annotation.arrow

  • Legend.draggable()，推荐使用 Legend.set_draggable()

    （Legend.draggable 可能会在未来版本中重新引入为属性）

  • textpath.TextToPath.tex_font_map

  • matplotlib.cbook.deprecation.mplDeprecation 将在未来版本中移除。它只是 matplotlib.cbook.deprecation.MatplotlibDeprecationWarning 的别名。如有必要，请直接使用 matplotlib.cbook.MatplotlibDeprecationWarning。

  • matplotlib.cbook.Bunch 类已弃用。请改用标准库中的 types.SimpleNamespace，它提供相同的功能。

  • Axes.mouseover_set 现在是一个 frozenset，并且已弃用。直接操作艺术家的 .mouseover 属性以更改其鼠标悬停状态。

以下关键字参数已弃用：

  • 向 Axes.scatter 传递 verts（请改用 marker）

  • 向 cbook.deprecated 传递 obj_type

以下调用签名已弃用：

  • 将 wx.EvtHandler 作为第一个参数传递给 backend_wx.TimerWx

rcParams#

以下 rcParams 已弃用：

  • examples.directory（请改用 datapath）

  • pgf.debug（pgf 后端依赖于日志记录）

  • text.latex.unicode（现在始终为 True）

标记样式#

  • 使用 (n, 3) 作为标记样式来指定圆形标记已弃用。请改用 "o"。

  • 使用 ([(x0, y0), (x1, y1), ...], 0) 作为标记样式来指定自定义标记路径已弃用。请改用 [(x0, y0), (x1, y1), ...]。

工具包中 LocatableAxes 的弃用#

工具包中的 LocatableAxes 类已弃用。基类 Axes 为所有子类提供了相同的功能，因此这些混合类不再需要。相关函数也已弃用。具体如下：

移除项#

保持机制#

设置或取消设置 hold（在 2.0 版本中已弃用）现在已完全移除。Matplotlib 现在始终表现为 hold=True。要清除轴，可以手动使用 cla()，或者要清除整个图，请使用 clear()。

移除已弃用的后端#

已弃用的后端已移除：

  • GTKAgg

  • GTKCairo

  • GTK

  • GDK

已弃用的 API#

以下已弃用的 API 元素已移除：

  • 已从 matplotlib.testing.decorators 中移除已弃用的方法 knownfailureif 和 remove_text。

  • testing.noseclasses 的全部内容也已移除。

  • matplotlib.checkdep_tex, matplotlib.checkdep_xmllint

  • backend_bases.IdleEvent

  • cbook.converter, cbook.tostr, cbook.todatetime, cbook.todate, cbook.tofloat, cbook.toint, cbook.unique, cbook.is_string_like, cbook.is_sequence_of_strings, cbook.is_scalar, cbook.soundex, cbook.dict_delall, cbook.get_split_ind, cbook.wrap, cbook.get_recursive_filelist, cbook.pieces, cbook.exception_to_str, cbook.allequal, cbook.alltrue, cbook.onetrue, cbook.allpairs, cbook.finddir, cbook.reverse_dict, cbook.restrict_dict, cbook.issubclass_safe, cbook.recursive_remove, cbook.unmasked_index_ranges, cbook.Null, cbook.RingBuffer, cbook.Sorter, cbook.Xlator

  • font_manager.weight_as_number, font_manager.ttfdict_to_fnames

  • pyplot.colors, pyplot.spectral

  • rcsetup.validate_negative_linestyle, rcsetup.validate_negative_linestyle_legacy

  • testing.compare.verifiers, testing.compare.verify

  • testing.decorators.knownfailureif, testing.decorators.ImageComparisonTest.remove_text

  • tests.assert_str_equal, tests.test_tinypages.file_same

  • texmanager.dvipng_hack_alpha,

  • _AxesBase.axesPatch, _AxesBase.set_color_cycle, _AxesBase.get_cursor_props, _AxesBase.set_cursor_props

  • _ImageBase.iterpnames

  • FigureCanvasBase.start_event_loop_default;

  • FigureCanvasBase.stop_event_loop_default;

  • Figure.figurePatch,

  • FigureCanvasBase.dynamic_update, FigureCanvasBase.idle_event, FigureCanvasBase.get_linestyle, FigureCanvasBase.set_linestyle

  • FigureCanvasQTAggBase

  • FigureCanvasQTAgg.blitbox

  • FigureCanvasTk.show（替代方案：FigureCanvasTk.draw）

  • FigureManagerTkAgg（替代方案：FigureManagerTk）

  • NavigationToolbar2TkAgg（替代方案：NavigationToolbar2Tk）

  • backend_wxagg.Toolbar（替代方案：backend_wxagg.NavigationToolbar2WxAgg）

  • RendererAgg.debug()

  • 向 EngFormatter.format_eng 传递非数字

  • 向 PolarAxes.set_theta_grids 传递 frac

  • 任何提及闲置事件

以下 API 元素已移除：

  • backend_cairo.HAS_CAIRO_CFFI

  • sphinxext.sphinx_version

专有 Sphinx 指令#

Matplotlib 文档使用了专有的 Sphinx 指令 .. htmlonly:: 和 .. latexonly::。这些已替换为标准 Sphinx 指令 .. only:: html 和 .. only:: latex。此更改不会影响任何用户。只有在文档中使用了专有指令的下游包维护者需要切换到 Sphinx 指令。

在此页