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，这将改善对对数轴的处理。请注意，返回的 图像 现在是 QuadMesh 类型，而不是 AxesImage 类型。

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

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

matplotlib.axes.Axes.get_tightbbox 添加了一个新的关键字参数 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)。

  3. 在新关键字参数 bbox_extra_artists 中手动指定艺术家列表。

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

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

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

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

它们之前返回的是一个数组。返回一个元组与二维轴的行为一致。

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

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

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

这些参数在2.0版本中被重命名为 x / y ，以适应默认对齐方式从 edge 到 center 的改变。

未记录选项的不同异常类型#

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

  • 将未记录的 xmin 或 xmax 参数传递给 set_xlim() 会静默地覆盖 left 和 right 参数。set_ylim() 及其 3D 等效项（例如 set_zlim）也有相应的问题。如果它们会覆盖先前的限制参数，将引发 TypeError。在 3.0 版本中，这些 kwargs 已被弃用，但在 3.1 版本中，弃用被撤销。

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

Axes.margins 和 Axes3D.margins 不再接受任意关键字。因此，如果传递了未知的 kwargs，将会引发 TypeError；之前这些未知的 kwargs 会被静默忽略。

如果传递了过多的位置参数，将会引发 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 的输出#

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

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

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

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

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

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

当使用指定为目标数量的级别而不是列表调用轮廓线，并且使用 'extend' 关键字参数时，现在选择的级别使得一些数据通常会落在扩展范围内。

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

流线图最后一行和最后一列固定#

修复了一个错误，该错误导致在 streamplot 中数据的最后一行和最后一列被丢弃。

将默认的 AutoDateLocator 关键字参数 interval_multiples 更改为 True#

日期刻度定位器的默认值，dates.AutoDateLocator 关键字参数 interval_multiples 被设置为 False，这导致在许多情况下自动刻度看起来不太美观。现在，更美观的 interval_multiples=True 是新的默认值。请参见下方以恢复旧的行为：

(Source code, 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)。

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

如果颜色条是由一个不是等高线或没有边界范数的可映射对象创建的，或者没有指定边界，颜色条的刻度现在会根据颜色条的大小进行调整。如果指定了边界等，颜色条将保持原始行为。

对数缩放的六边形图的颜色条#

在使用 hexbin 并使用对数颜色标度绘图时，颜色条的刻度现在已正确对数缩放。以前，刻度值是线性缩放的对数（计数数量）。

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中，字典到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 属性来改变它们的鼠标悬停状态。

以下关键字参数已被弃用：

  • 将 verts 传递给 Axes.scatter (使用 marker 代替)

  • 将 obj_type 传递给 cbook.deprecated

以下调用签名已被弃用：

  • 将 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元素已被移除：

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

  • 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

  • 将 frac 传递给 PolarAxes.set_theta_grids

  • 任何提及的空闲事件

以下API元素已被移除：

  • backend_cairo.HAS_CAIRO_CFFI

  • sphinxext.sphinx_version

专有 Sphinx 指令#

matplotlib 文档使用了专有的 sphinx 指令 .. htmlonly:: 和 .. latexonly::。这些已经被标准的 sphinx 指令 .. only:: html 和 .. only:: latex 所取代。这一更改不会影响任何用户。只有那些在其文档中使用了专有指令的下游包维护者需要切换到 sphinx 指令。

On this page