3.1.0 的 API 变更#

行为变化#

Matplotlib.use#

通过 matplotlib.use 切换后端现在默认允许，无论是否已导入 matplotlib.pyplot。如果用户尝试从已启动的交互式后端切换到不同的交互式后端，将引发 ImportError。

PathCollections 中的无效点#

使用 scatter 创建的 PathCollections 现在会跟踪无效点。以前，坐标为非有限值（无穷大或 NaN）的点不会包含在由 scatter 创建的 PathCollection 的偏移量（通过 PathCollection.get_offsets 返回）中，并且具有非有限值的点（由 c 关键字参数指定）不会包含在数组（通过 PathCollection.get_array 返回）中。

这些点现在已被包含，但通过返回一个掩码数组而被隐藏。

如果 scatter 的 plotnonfinite 关键字参数被设置，那么具有非有限值的点将使用 collections.PathCollection 的色图的坏颜色进行绘制（如通过 colors.Colormap.set_bad() 设置）。

RBGA 输入在 imshow 中的 Alpha 混合#

RBGA 图像的 alpha 通道现在独立于 RGB 通道进行重新采样。虽然这是一个错误修复，但它确实改变了输出，并可能导致一些下游图像比较测试失败。

自动扩展#

在单个值绘制在“完整”十进制（1, 10, 100 等）的对数轴上时，自动缩放现在会围绕该点对称地扩展轴，而不是仅向右添加一个十进制。

对数刻度轴#

当默认的 LogLocator 为某个轴生成无刻度（例如，一个范围从0.31到0.39的轴）或仅有一个刻度时，现在它会回退到线性的 AutoLocator 以选择合理的刻度位置。

Figure.add_subplot 不带参数#

调用 Figure.add_subplot() 时不带位置参数过去什么也不做；现在这相当于调用 add_subplot(111)。

bxp 和 rcparams#

bxp 现在即使设置了 patch_artist 也会尊重 rcParams["boxplot.boxprops.linewidth"] (default: 1.0)。以前，当设置了 patch_artist 参数时，bxp 会忽略 rcParams["boxplot.boxprops.linewidth"] (default: 1.0)。这是一个疏忽——特别是，boxplot 并没有忽略它。

主/次刻度冲突#

与主刻度重叠的次刻度现在默认隐藏。以前，某些定位器类（LogLocator，AutoMinorLocator）包含自定义逻辑，以在使用它们作为次定位器时避免发出与主刻度重叠的刻度位置。现在，此逻辑已移至 Axis 类，并且无论定位器类如何都使用。您可以通过 Axis 上的 remove_overlapping_locs 属性控制此行为。

如果你依赖于主刻度和次刻度标签同时出现在同一个刻度上，你可能需要更新你的代码。例如，以下代码片段

import numpy as np
import matplotlib.dates as mdates
import matplotlib.pyplot as plt

t = np.arange("2018-11-03", "2018-11-06", dtype="datetime64")
x = np.random.rand(len(t))

fig, ax = plt.subplots()
ax.plot(t, x)
ax.xaxis.set(
    major_locator=mdates.DayLocator(),
    major_formatter=mdates.DateFormatter("\n%a"),
    minor_locator=mdates.HourLocator((0, 6, 12, 18)),
    minor_formatter=mdates.DateFormatter("%H:%M"),
)
# disable removing overlapping locations
ax.xaxis.remove_overlapping_locs = False
plt.show()

使用主要刻度标记天数，使用次要刻度标记小时和分钟，并在主要刻度标签中添加了换行符，以避免它们与次要刻度标签重叠。设置 remove_overlapping_locs 属性（也可通过 set_remove_overlapping_locs / get_remove_overlapping_locs 和 setp 访问）可以禁用移除重叠的刻度位置。

主要刻度标签也可以调整，包括小时和分钟，因为次要刻度已经消失，所以 major_formatter 将会是:

mdates.DateFormatter("%H:%M\n%a")

usetex 支持#

之前，如果 rcParams["text.usetex"] (default: False) 为 True，那么在非 mathtext 字符串上使用 usetex=False 构建 TextPath 时，会依赖 mathtext 解析器（但不依赖 usetex 支持！）来解析字符串。现在不再调用 mathtext 解析器，这可能会导致字形位置的轻微变化。

get_window_extents#

matplotlib.axes.Axes.get_window_extent 过去返回的边界框比轴略大，大概是考虑到脊上的刻度。然而，它没有根据画布的 dpi 缩放刻度大小，也没有检查刻度是否可见，或者是否在脊上。

现在 matplotlib.axes.Axes.get_window_extent 仅返回无刻度填充的轴范围。

这会影响 matplotlib.axes.Axes.get_tightbbox 在有向外刻度但没有刻度标签的情况下，并且在这种情况下也会移除（小）轴周围的填充。

spines.Spine.get_window_extent 现在会考虑位于脊上的刻度。

桑基图#

之前，Sankey.add 如果 labels 参数的长度等于流的数量，则只接受一个字符串作为 labels 参数，在这种情况下，它将为每个流使用字符串中的一个字符。

行为已更改为与文档中描述的一致：当传递单个字符串时，它用于标记所有流程。

FontManager 评分#

font_manager.FontManager.score_weight 现在对其输入更加严格。以前，当一个权重字符串传递给 font_manager.FontManager.score_weight 时，

  • 如果权重是整数的字符串表示形式，它将被转换为该整数。

  • 否则，如果权重不是标准权重名称，它将被静默替换为值500（“正常”权重）。

font_manager.FontManager.score_weight 现在在遇到此类输入时会引发异常。

文本对齐#

文本对齐之前是不正确的，特别是对于带有大降部（即下标）的多行文本对象和旋转文本。这些问题已经修复并变得更加一致，但这可能会使已经补偿了这些问题的旧代码不再具有正确的对齐。

大写颜色字符串#

支持将单字母颜色（"rgbcmykw" 中的一个）作为大写字符传递的功能已被弃用；在弃用期过后，这些颜色将变为区分大小写（小写）。

目标是减少在使用``data``关键字调用绘图方法时的歧义情况；例如，``plot("X", "Y", data={"X": ..., "Y": ...})``在弃用期过后将不再警告“Y”可能是一个颜色。

简并极限#

当传递给 set_xlim 的边界是退化的（即下限和上限值相等），用于“扩展”边界的方法现在与包含单个 x 值的图表自动缩放时的扩展行为相匹配，并且尤其应为非线性比例生成更美观的限制。

plot 格式字符串解析#

在某些情况下，plot 以前可以接受指定多个线型的格式字符串（例如 "---." 指定了 "--" 和 "-."）；但只会使用其中一种。现在这将引发一个 ValueError。

HTMLWriter#

HTMLWriter 构造函数更加严格：它不再将 default_mode 的未知值归一化为 'loop'，而是直接报错。

AFM 解析#

根据 AFM 规范，AFM 解析器不再将 UnderlinePosition 和 UnderlineThickness 字段截断为整数。

Notice 字段（只能通过已弃用的 afm.parse_afm API 公开访问）不再解码为 str，而是保持为 bytes，以支持在该字段中使用非 ASCII 字符的非标准 AFM 文件。

Artist.set 关键字规范化#

Artist.set 现在在排序之前对关键字进行规范化。之前它在应用之前按字母顺序反向排序其关键字参数（有一个特殊情况是将 color 放在最后）。

现在在执行排序之前会规范化别名（并且如上所述，在遇到重复属性时会发出警告）（因此 c 也会被移到最后）。

Axes.tick_params 参数检查#

之前，当提供无效的 axis 参数时，Axes.tick_params 会静默地不执行任何操作。此行为已更改为引发 ValueError。

Axes.hist 输出#

包含多个空列表的输入现在将为每个列表返回一个直方图值列表。例如，输入 [[],[]] 将返回两个直方图值列表。以前，只返回一个列表。

backend_bases.TimerBase.remove_callback 未来签名更改#

目前，backend_bases.TimerBase.remove_callback(func, *args, **kwargs) 移除了之前通过 backend_bases.Timer.add_callback(func, *args, **kwargs) 添加的回调，但如果未传递 *args, **kwargs``（即 ``TimerBase.remove_callback(func)），则移除第一个匹配 func 的回调，无论其是否通过 *args, **kwargs 添加。

在未来的版本中，TimerBase.remove_callback 将始终使用后一种行为（不考虑 *args, **kwargs）；要特别考虑它们，请将回调添加为 functools.partial 对象

cb = timer.add_callback(functools.partial(func, *args, **kwargs))
# ...
# later
timer.remove_callback(cb)

TimerBase.add_callback 被修改为返回 func 以简化上述用法（之前它返回 None）；这也允许将其用作装饰器。

新的 API 是基于 atexit.register / atexit.unregister 设计的。

StemContainer 性能提升#

StemContainer 对象现在可以存储一个 LineCollection 对象，而不是使用 stem 绘制的茎线列表的 Line2D 对象。这大大提高了显示和移动 stem 图形的性能。

这将成为 Matplotlib 3.3 中的默认行为。要立即使用它，可以将 stem 的 use_line_collection 关键字参数设置为 True

ax.stem(..., use_line_collection=True)

可以从 LineCollection 中提取单个线段，使用 get_segments()。有关检索集合属性的其他方法，请参阅 LineCollection 文档。

ColorbarBase 继承#

matplotlib.colorbar.ColorbarBase 不再是 cm.ScalarMappable 的子类。这种继承导致了一个混乱的情况，即传递给 matplotlib.colorbar.Colorbar (colorbar) 的 cm.ScalarMappable 和 colorbar 都有 set_norm 方法。现在，colorbar 纯粹是 ScalarMappable 的 norm 和 colormap 的跟随者，旧的继承方法 matplotlib.colorbar.ColorbarBase.set_norm、matplotlib.colorbar.ColorbarBase.set_cmap、matplotlib.colorbar.ColorbarBase.set_clim 以及这些调用的 getter 版本都已弃用。要设置与 colorbar 关联的 norm，请使用 colorbar.mappable.set_norm() 等。

FreeType 和 libpng 搜索路径#

MPLBASEDIRLIST 环境变量和 setup.cfg 中的 basedirlist 条目不再起作用。相反，如果在 FreeType 或 libpng 不在编译器或链接器的默认路径中的情况下进行构建，请在 Linux 或 OSX 上设置标准环境变量 CFLAGS/LDFLAGS，或在 Windows 上设置 CL/LINK，以指示相关路径。

详情请参见 安装。

在同一调用中设置艺术家属性两次或更多次#

通过别名多次设置相同的艺术家属性已被弃用。以前，代码如

plt.plot([0, 1], c="red", color="blue")

会发出一个警告，指出 c 和 color 是彼此的别名，并且只会保留 color 关键字参数。这种行为已被弃用；在未来的版本中，这将引发一个 TypeError，类似于当一个关键字参数被传递两次时 Python 的行为

plt.plot([0, 1], c="red", c="blue")

此警告由 normalize_kwargs 引发。

路径代码类型#

路径代码类型如 Path.MOVETO 现在是 np.uint8 而不是 int。 Path.STOP, Path.MOVETO, Path.LINETO, Path.CURVE3, Path.CURVE4 和 Path.CLOSEPOLY 现在是 Path.code_type 类型（默认是 np.uint8），而不是普通的 int。这使得它们的类型与 Path.codes 数组的数组值类型相匹配。

matplotlibrc 文件中的 LaTeX 代码#

之前，rc 文件键 pgf.preamble 和 text.latex.preamble 使用逗号作为分隔符进行解析。这将破坏有效的 LaTeX 代码，例如:

\usepackage[protrusion=true, expansion=false]{microtype}

解析过程已修改，将完整行传递给 LaTeX 系统，保留所有逗号。从 Python 脚本中传递字符串列表的功能仍如以往一样工作。传递包含非字符串的列表现在会失败，而不是将结果强制转换为字符串。

Axes.spy#

方法 Axes.spy 现在对关键字参数 interpolation 和 linestyle 会引发 TypeError ，而不是默默忽略它们。

此外，Axes.spy 现在允许使用 extent 参数（之前被静默忽略）。

修复了 Axes.spy(..., origin='lower') 的一个错误。之前这会翻转数据但不会翻转y轴，导致轴标签与实际数据索引不匹配。现在，origin='lower' 会同时翻转数据和y轴标签。

箱线图刻度方法#

boxplot 和 bxp 的 manage_xticks 参数已被重命名为 manage_ticks*（经过一个弃用期），以考虑到它根据 *vert 参数管理 x 或 y 刻度的事实。

当 ``manage_ticks=True``（默认）时，这些方法现在在设置轴限制、刻度和刻度标签时会尝试考虑之前绘制的箱线图。

鼠标事件#

MouseEvents 现在在其 str() 中包含事件名称。以前它们包含前缀 "MPL MouseEvent"。

RGBA 缓冲区返回类型#

FigureCanvasAgg.buffer_rgba 和 RendererAgg.buffer_rgba 现在返回一个 memoryview buffer_rgba 方法现在允许直接访问渲染器的底层缓冲区（作为一个 (m, n, 4)-形状的 memoryview），而不是将数据复制到一个新的字节字符串中。这与在 Py2 上的行为一致，其中返回了一个缓冲区对象。

matplotlib.font_manager.win32InstalledFonts 返回类型#

matplotlib.font_manager.win32InstalledFonts 如果没有找到字体，则返回空列表而不是 None。

Axes.fmt_xdata 和 Axes.fmt_ydata 错误处理#

之前，如果用户提供了一个会引发 TypeError 的 Axes.fmt_xdata 或 Axes.fmt_ydata 函数（或者将它们设置为不可调用的对象），异常会被静默忽略，并使用默认的格式化器。现在不再是这种情况；异常现在会被传播出去。

弃用冗余的 Tick 属性#

gridOn、tick1On、tick2On、label1On 和 label2On Tick 属性已被弃用。请直接获取和设置底层艺术家的可见性，这些艺术家可通过 gridline、tick1line、tick2line、label1 和 label2 属性访问。

label 属性，曾是 label1 的别名，现已弃用。

依赖于设置上述可见性属性的子类需要更新；例如，参见 examples/api/skewt.py。

将 Line2D 的 drawstyle 与 linestyle 一起传递已被弃用#

使用 plt.plot(..., linestyle="--", drawstyle="steps") 代替 plt.plot(..., linestyle="steps--")。ds 现在是 drawstyle 的别名。

pgi 支持已移除#

GTK3 后端中对 pgi 的支持已被移除。pgi 是 PyGObject 的替代实现。应改用 PyGObject。

rcParam 更改#

移除#

以下已弃用的 rcParams 已被移除：

  • text.dvipnghack

  • nbagg.transparent (请改用 rcParams["figure.facecolor"] (default: 'white'))

  • plugins.directory

  • axes.hold

  • backend.qt4 和 backend.qt5 （请设置 QT_API 环境变量）

已弃用#

相关的验证函数 rcsetup.validate_qt4 和 validate_qt5 已被弃用。

verbose.fileo 和 verbose.level rcParams 已被弃用。自从从 Matplotlib 的旧自定义 Verbose 日志切换到标准库的 logging 模块以来，这些参数就没有任何效果了。此外，rcsetup.validate_verbose 函数也被弃用。

text.latex.unicode rcParam 现在默认值为 True 并且已被弃用（即，在未来的 Matplotlib 版本中，将始终支持 Unicode 输入）。此外，底层实现现在使用 \usepackage[utf8]{inputenc} 而不是 \usepackage{ucs}\usepackage[utf8x]{inputenc}。

异常更改#

  • mpl_toolkits.axes_grid1.axes_size.GetExtentHelper 现在对于无效的方向会引发 ValueError 而不是 KeyError。

  • 之前，动画框架中的子进程失败会根据错误发生的时间引发 RuntimeError 或 ValueError。现在它们会引发 subprocess.CalledProcessError，其属性按照异常类文档中的说明设置。

  • 在某些情况下，如果使用 data kwarg 调用 Axes 方法（和 pyplot 函数），并且参数不匹配，它们过去会引发 RuntimeError。现在它们会引发 TypeError 。

  • Axes.streamplot 不支持不规则网格的 x 和 y 值。到目前为止，它曾经会静默地绘制一个错误的结果。这一行为已被改为引发 ValueError。

  • streamplot.Grid 类，该类在内部由 streamplot 代码使用，当传入不规则网格的值时，也会抛出 ValueError。

移除#

以下已弃用的API已被移除：

类和方法#

  • Verbose (被Python日志库替代)

  • artist.Artist.hitlist (无替换)

  • artist.Artist.is_figure_set (请使用 artist.figure is not None 代替)

  • axis.Axis.unit_data (请使用 axis.Axis.units 代替)

  • backend_bases.FigureCanvasBase.onRemove (无替代) backend_bases.FigureManagerBase.show_popup (此方法从未执行任何操作)

  • backend_wx.SubplotToolWx (无替代品)

  • backend_wx.Toolbar (请使用 backend_wx.NavigationToolbar2Wx 代替)

  • cbook.align_iterators (无替换)

  • contour.ContourLabeler.get_real_label_width (无替换)

  • legend.Legend.draggable (请使用 legend.Legend.set_draggable() 代替)

  • texmanager.TexManager.postscriptd, texmanager.TexManager.pscnt, texmanager.TexManager.make_ps, texmanager.TexManager.get_ps_bbox (无替换)

参数#

其他#

以下杂项API元素已被移除

  • svgfont 支持（在 rcParams["svg.fonttype"] (default: 'path') 中）

  • 现在使用标准的 Python logging 库进行日志记录。matplotlib.verbose 和命令行开关 --verbose-LEVEL 已被移除。

    要控制日志输出，请使用:

    import logging
logger = logging.getLogger('matplotlib')
logger.setLevel(logging.INFO)
# configure log handling: Either include it into your ``logging`` hierarchy,
# e.g. by configuring a root looger using ``logging.basicConfig()``,
# or add a standalone handler to the matplotlib logger:
logger.addHandler(logging.StreamHandler())

  • __version__numpy__

  • collections.CIRCLE_AREA_FACTOR

  • font_manager.USE_FONTCONFIG

  • font_manager.cachedir

matplotlib.mlab 移除#

在 Matplotlib 2.2 中被弃用的 matplotlib.mlab 模块中的大量代码已被移除。请参见下表：

  • mlab.exp_safe (请改用 numpy.exp)

  • mlab.amap

  • mlab.logspace (请改用 numpy.logspace)

  • mlab.rms_flat

  • mlab.l1norm (请改用 numpy.linalg.norm(a, ord=1))

  • mlab.l2norm (请使用 numpy.linalg.norm(a, ord=2) 代替)

  • mlab.norm_flat (请使用 numpy.linalg.norm(a.flat, ord=2) 代替)

  • mlab.frange (请使用 numpy.arange 代替)

  • mlab.identity (请改用 numpy.identity)

  • mlab.base_repr

  • mlab.binary_repr

  • mlab.ispower2

  • mlab.log2 (请改用 numpy.log2)

  • mlab.isvector

  • mlab.movavg

  • mlab.safe_isinf (请改用 numpy.isinf)

  • mlab.safe_isnan (请使用 numpy.isnan 代替)

  • mlab.cohere_pairs (请改用 scipy.signal.coherence)

  • mlab.entropy (请改用 scipy.stats.entropy)

  • mlab.normpdf (请改用 scipy.stats.norm.pdf)

  • mlab.find (请使用 np.nonzero(np.ravel(condition)) 代替)

  • mlab.longest_contiguous_ones

  • mlab.longest_ones

  • mlab.PCA

  • mlab.prctile (请改用 numpy.percentile)

  • mlab.prctile_rank

  • mlab.center_matrix

  • mlab.rk4 (请改用 scipy.integrate.ode)

  • mlab.bivariate_normal

  • mlab.get_xyz_where

  • mlab.get_sparse_matrix

  • mlab.dist (请使用 numpy.hypot 代替)

  • mlab.dist_point_to_segment

  • mlab.griddata (使用 scipy.interpolate.griddata)

  • mlab.less_simple_linear_interpolation (使用 numpy.interp)

  • mlab.slopes

  • mlab.stineman_interp

  • mlab.segments_intersect

  • mlab.fftsurr

  • mlab.offset_line

  • mlab.quad2cubic

  • mlab.vector_lengths

  • mlab.distances_along_curve

  • mlab.path_length

  • mlab.cross_from_above

  • mlab.cross_from_below

  • mlab.contiguous_regions (请改用 cbook.contiguous_regions)

  • mlab.is_closed_polygon

  • mlab.poly_between

  • mlab.poly_below

  • mlab.inside_poly

  • mlab.csv2rec

  • mlab.rec2csv (请改用 numpy.recarray.tofile)

  • mlab.rec2text (请改用 numpy.recarray.tofile)

  • mlab.rec_summarize

  • mlab.rec_join

  • mlab.recs_join

  • mlab.rec_groupby

  • mlab.rec_keep_fields

  • mlab.rec_drop_fields

  • mlab.rec_append_fields

  • mlab.csvformat_factory

  • mlab.get_formatd

  • mlab.FormatDatetime (请使用 datetime.datetime.strftime 代替)

  • mlab.FormatDate (请使用 datetime.date.strftime 代替)

  • mlab.FormatMillions, mlab.FormatThousands, mlab.FormatPercent, mlab.FormatBool, mlab.FormatInt, mlab.FormatFloat, mlab.FormatFormatStr, mlab.FormatString, mlab.FormatObj

  • mlab.donothing_callback

pylab 移除#

在 Matplotlib 2.2 中被弃用的 matplotlib.mlab 模块中的大量代码已被移除。这意味着以下函数在 pylab 模块中不再可用：

  • amap

  • base_repr

  • binary_repr

  • bivariate_normal

  • center_matrix

  • csv2rec (请改用 numpy.recarray.tofile)

  • dist (使用 numpy.hypot 替代)

  • dist_point_to_segment

  • distances_along_curve

  • entropy (使用 scipy.stats.entropy 代替)

  • exp_safe (使用 numpy.exp 代替)

  • fftsurr

  • find (使用 np.nonzero(np.ravel(condition)) 替代)

  • frange (请使用 numpy.arange 代替)

  • get_sparse_matrix

  • get_xyz_where

  • griddata （请使用 scipy.interpolate.griddata 代替）

  • identity （请使用 numpy.identity 代替）

  • inside_poly

  • is_closed_polygon

  • ispower2

  • isvector

  • l1norm (请使用 numpy.linalg.norm(a, ord=1) 代替)

  • l2norm (请使用 numpy.linalg.norm(a, ord=2) 代替)

  • log2 (请使用 numpy.log2 代替)

  • longest_contiguous_ones

  • longest_ones

  • movavg

  • norm_flat (请改用 numpy.linalg.norm(a.flat, ord=2))

  • normpdf (请使用 scipy.stats.norm.pdf 代替)

  • path_length

  • poly_below

  • poly_between

  • prctile (请改用 numpy.percentile)

  • prctile_rank

  • rec2csv (使用 numpy.recarray.tofile 代替)

  • rec_append_fields

  • rec_drop_fields

  • rec_join

  • rk4 (请使用 scipy.integrate.ode 代替)

  • rms_flat

  • segments_intersect

  • slopes

  • stineman_interp

  • vector_lengths

mplot3d 变化#

体素着色#

Axes3D.voxels 现在为生成的体素添加了阴影；更多详情请参见“新特性”。可以通过传递以下内容来实现之前的行为：

ax.voxels(.., shade=False)

禁用等比例轴#

在3D轴上设置纵横比之前会返回无意义的结果（例如，参见 #1077）。现在在3D轴上调用 ax.set_aspect('equal') 或 ax.set_aspect(num) 会引发一个 NotImplementedError。

Poly3DCollection.set_zsort#

Poly3DCollection.set_zsort 不再默默忽略无效输入，或 False`（这总是有问题的）。传递 `True 以表示 "average" 已被弃用。

测试#

tests.py 的 --no-network 标志已被移除（不再有测试需要互联网访问）。如果希望同时为旧版本和新版本的 Matplotlib 禁用互联网访问，请使用 ``tests.py -m 'not network'``（现在这是一个无操作）。

图像比较测试装饰器现在会跳过（而不是xfail）无法比较格式的测试。受影响的装饰器是 image_comparison 和 check_figures_equal。已弃用的 ImageComparisonTest 类也相应更改。

依赖项更改#

NumPy#

Matplotlib 3.1 现在需要 NumPy>=1.11。

ghostscript#

对 ghostscript 8.60（2007年发布）的支持已被移除。现在支持的最旧版本是 ghostscript 9.0（2010年发布）。

数学文本更改#

  • 在诸如 "$1~2$" 的结构中，mathtext 现在将波浪号解释为空格，与 TeX 一致（这在之前是一个解析错误）。

弃用#

  • \stackrel 数学文本命令已被弃用（它的行为与 LaTeX 的 \stackrel 不同）。要堆叠两个数学文本表达式，请使用 \genfrac{左分隔符}{右分隔符}{分数条厚度}{}{顶部}{底部}。

  • \mathcircled mathtext 命令（这不是一个真正的 TeX 命令）已被弃用。请直接使用 Unicode 字符（例如 "\N{CIRCLED LATIN CAPITAL LETTER A}" 或 "\u24b6"）代替。

  • 设置 rcParams["mathtext.default"] (default: 'it') 为 circled 的支持已被弃用。

签名弃用#

以下与签名相关的行为已被弃用：

  • Axes.text() 的 withdash 关键字参数。建议使用 Axes.annotate() 代替。

  • 传递 (n, 1) 形状的误差数组给 Axes.errorbar()，这在文档中没有说明，并且对于 n = 2 不起作用。请改为传递一维数组。

  • savefig 的 frameon 关键字参数和 rcParams["savefig.frameon"] rcParam。要模拟 frameon = False，请将 facecolor 设置为完全透明（"none" 或 (0, 0, 0, 0)）。

  • 将非一维（通常是 (n, 1) 形状）的输入传递给 Axes.pie。请改为传递一维数组。

  • TextPath 构造函数过去会静默丢弃被忽略的参数；此行为已被弃用。

  • TextToPath.get_text_path 的 usetex 参数已被弃用，并合并到 ismath 参数中，该参数现在可以取值 False、True 和 "TeX"，与其他底层文本处理函数一致。

  • 传递 'normal' 给 axes.Axes.axis() 已被弃用，请改用 ax.axis('auto')。

  • 传递 pyplot.show 的 block 参数作为位置参数已被弃用；应通过关键字传递。

  • 在使用 nbagg 后端时，pyplot.show 过去会静默接受并忽略所有位置参数和关键字参数的组合。此行为已被弃用。

  • 未使用的 shape 和 imlim 参数在 Axes.imshow 中已被弃用。为了避免触发弃用警告，应通过关键字传递 filternorm、filterrad、resample 和 url 参数。

  • BboxImage 的 interp_at_native 参数自 Matplotlib 2.0 以来没有任何效果，现已被弃用。

  • matplotlib.cbook.deprecation.deprecated 装饰器和 matplotlib.cbook.deprecation.warn_deprecated 函数的所有参数，除了第一个（即发生弃用的版本），现在都是仅关键字参数。这样做的目的是为了避免在原本打算设置“name”（或“alternative”）参数时，意外地设置了“message”参数，因为这在过去已经多次发生。

  • matplotlib.testing.compare.calculate_rms 的参数已从 expectedImage, actualImage 重命名为 expected_image, actual_image。

  • 传递给 Axis.set_ticklabels 的位置参数，除了 ticklabels 本身之外，没有任何效果，并且对它们的支持已被弃用。

  • 将 shade=None 传递给 plot_surface 已被弃用。这是一个未经意的实现细节，具有与 shade=False 相同的语义。请改用后者的代码。

  • matplotlib.ticker.MaxNLocator 及其 set_params 方法在遇到未知的关键字参数时将发出警告，而不是默默忽略它们。未来的版本将引发错误。

参数名称的变更#

在每种情况下，旧的参数名称仍然支持（不能与新名称同时使用），但在 Matplotlib 3.3 中将不再支持它。

类/方法/属性弃用#

不提供 GraphicsContextBase.set_hatch_color 方法的自定义后端的支援已被弃用。我们建议自定义后端让它们的 GraphicsContext 类继承自 GraphicsContextBase，至少为所有必需的方法提供存根。

  • spine.Spine.is_frame_like

自2009年添加以来，此功能在代码库中未曾使用过。

  • axis3d.Axis.get_tick_positions

    这从未在内部使用过，2D Axis 类中不存在等效方法，尽管名称相似，但其行为与 2D Axis 的 axis.Axis.get_ticks_position 方法完全不同。

  • .backend_pgf.LatexManagerFactory

  • mpl_toolkits.axisartist.axislines.SimpleChainedObjects

  • mpl_toolkits.Axes.AxisDict

内部辅助函数#

  • checkdep_dvipng

  • checkdep_ghostscript

  • checkdep_pdftops

  • checkdep_inkscape

  • ticker.decade_up

  • ticker.decade_down

  • cbook.dedent

  • docstring.Appender

  • docstring.dedent

  • docstring.copy_dedent

使用标准库中的文档字符串操作工具，例如 inspect.cleandoc 和 inspect.getdoc。

  • matplotlib.scale.get_scale_docs()

  • matplotlib.pyplot.get_scale_docs()

这些被视为内部使用，将在未来的版本中从公共API中移除。

  • projections.process_projection_requirements

  • backend_ps.PsBackendHelper

  • backend_ps.ps_backend_helper,

  • cbook.iterable

  • cbook.get_label

  • cbook.safezip 手动检查输入的长度，或者依赖 NumPy 来完成。

  • cbook.is_hashable 请使用 isinstance(..., collections.abc.Hashable) 代替。

  • .backend_bases.RendererBase.strip_math。请改用 cbook.strip_math。

作为 mpl_toolkits.mplot3d 公共API一部分的多个内部函数已被弃用，

mpl_toolkits.mplot3d.art3d

  • mpl_toolkits.mplot3d.art3d.norm_angle

  • mpl_toolkits.mplot3d.art3d.norm_text_angle

  • mpl_toolkits.mplot3d.art3d.path_to_3d_segment

  • mpl_toolkits.mplot3d.art3d.paths_to_3d_segments

  • mpl_toolkits.mplot3d.art3d.path_to_3d_segment_with_codes

  • mpl_toolkits.mplot3d.art3d.paths_to_3d_segments_with_codes

  • mpl_toolkits.mplot3d.art3d.get_patch_verts

  • mpl_toolkits.mplot3d.art3d.get_colors

  • mpl_toolkits.mplot3d.art3d.zalpha

mpl_toolkits.mplot3d.proj3d

  • mpl_toolkits.mplot3d.proj3d.line2d

  • mpl_toolkits.mplot3d.proj3d.line2d_dist

  • mpl_toolkits.mplot3d.proj3d.line2d_seg_dist

  • mpl_toolkits.mplot3d.proj3d.mod

  • mpl_toolkits.mplot3d.proj3d.proj_transform_vec

  • mpl_toolkits.mplot3d.proj3d.proj_transform_vec_clip

  • mpl_toolkits.mplot3d.proj3d.vec_pad_ones

  • mpl_toolkits.mplot3d.proj3d.proj_trans_clip_points

如果你的项目依赖这些功能，考虑将它们作为供应商包。

字体处理#

  • backend_pdf.RendererPdf.afm_font_cache

  • backend_ps.RendererPS.afmfontd

  • font_manager.OSXInstalledFonts

  • .TextToPath.glyph_to_path (应改为调用 font.get_path() 并手动转换路径。)

Axes3D#

  • .axes3d.Axes3D.w_xaxis

  • .axes3d.Axes3D.w_yaxis

  • .axes3d.Axes3D.w_zaxis

请使用 axes3d.Axes3D.xaxis 、 axes3d.Axes3D.yaxis 和 axes3d.Axes3D.zaxis 代替。

测试#

  • matplotlib.testing.decorators.switch_backend 装饰器

测试函数应使用 pytest.mark.backend，该标记将被 matplotlib.testing.conftest.mpl_test_settings 固定装置捕获。

箭筒#

  • Quiver 对象的 .color 属性

相反，使用（对于任何 Collection）``get_facecolor`` 方法。请注意，设置 .color 属性不会更新箭头艺术家，而调用 set_facecolor 则会更新。

GUI / 后端细节#

  • .get_py2exe_datafiles

  • .tk_window_focus

  • .backend_gtk3.FileChooserDialog

  • .backend_gtk3.NavigationToolbar2GTK3.get_filechooser

  • .backend_gtk3.SaveFigureGTK3.get_filechooser

  • .NavigationToolbar2QT.adj_window 属性。这个属性未被使用，且总是 None。

  • .backend_wx.IDLE_DELAY 全局变量 这个变量未被使用，仅与现已移除的 wx "空闲" 代码相关（注意，由于它是一个模块级别的全局变量，访问它时不会发出弃用警告）。

  • mlab.demean

  • backend_gtk3cairo.FigureCanvasGTK3Cairo,

  • backend_wx.debug_on_error, backend_wx.fake_stderr, backend_wx.raise_msg_to_str, backend_wx.MenuButtonWx, backend_wx.PrintoutWx,

  • matplotlib.backends.qt_editor.formlayout 模块

此模块是官方 formlayout 模块的一个供应商修改版本，该模块可在 PyPI 上获得。如果需要，请单独安装该模块。

  • GraphicsContextPS.shouldstroke

变换 / 缩放#

  • LogTransformBase

  • Log10Transform

  • Log2Transform,

  • NaturalLogTransformLog

  • InvertedLogTransformBase

  • InvertedLog10Transform

  • InvertedLog2Transform

  • InvertedNaturalLogTransform

在 matplotlib.scale 中定义的这些类已被弃用。作为替代，请使用通用的 LogTransform 和 InvertedLogTransform 类，它们的构造函数接受一个 base 参数。

定位器 / 格式化器#

  • OldScalarFormatter.pprint_val

  • ScalarFormatter.pprint_val

  • LogFormatter.pprint_val

这些是辅助方法，它们在不同的格式化类中没有一致的签名。

路径工具#

  • path.get_paths_extents

使用 get_path_collection_extents 代替。

  • .Path.has_nonfinite 属性

使用 not np.isfinite(path.vertices).all() 代替。

  • .bezier.find_r_to_boundary_of_closedpath 函数已被弃用

这总是返回 None 而不是请求的半径。

文本#

  • text.TextWithDash

  • Text.is_math_text

  • TextPath.is_math_text

  • TextPath.text_get_vertices_codes (或者，构造一个新的 TextPath 对象。)

未使用的属性#

  • NavigationToolbar2QT.buttons

  • Line2D.verticalOffset

  • Quiver.keytext

  • Quiver.keyvec

  • SpanSelector.buttonDown

这些是未使用的且从未更新的。

Sphinx 扩展#

  • matplotlib.sphinxext.mathmpl.math_directive

  • matplotlib.sphinxext.plot_directive.plot_directive

这是因为 matplotlib.sphinxext.mathmpl 和 matplotlib.sphinxext.plot_directive 接口已经从（Sphinx-）弃用的基于函数的接口更改为基于类的接口；这不应影响最终用户。

  • mpl_toolkits.axisartist.axis_artist.UnimplementedException

环境变量#

  • MATPLOTLIBDATA 环境变量

轴#

  • Axis.iter_ticks

这仅作为私有 Axis._update_ticks 的帮助工具

取消弃用#

以下 API 元素已不再弃用：

  • matplotlib.cbook.deprecation.deprecated 装饰器的 obj_type 关键字参数。

  • xmin, xmax 是 Axes.set_xlim 的关键字参数，ymin, ymax 是 Axes.set_ylim 的关键字参数。

新功能#

Text 现在为 color 属性提供了一个 c 别名#

为了与 Line2D 保持一致，Text 类增加了 c 作为 color 属性的别名。例如，现在可以这样写

ax.text(.5, .5, "foo", c="red")

Cn 颜色现在支持 n>=10#

现在可以使用 Cn 语法在属性循环中超过第十种颜色，例如

plt.plot([1, 2], color="C11")

现在使用循环中的第12种颜色。

注意，以前有一个构造如下:

plt.plot([1, 2], "C11")

将被解释为请求使用颜色 C1 和标记 ``1``（一个“倒Y”）。要获得这样的图，现在应该使用

plt.plot([1, 2], "1C1")

(以便第一个“1”被正确解释为标记规范)，或者，更明确地:

plt.plot([1, 2], marker="1", color="C1")

新的 Formatter.format_ticks 方法#

Formatter 类新增了一个 format_ticks 方法，该方法接受所有刻度位置的列表作为单一参数，并返回所有格式化值的列表。它由轴刻度处理代码调用，默认情况下，首先使用所有位置调用 set_locs，然后为每个位置重复调用 Formatter.__call__。

代码库中处理刻度的代码之前执行此序列（set_locs 后跟重复的 Formatter.__call__），现已更新为使用 format_ticks。

format_ticks 旨在被 Formatter 子类重写，这些子类的刻度值格式化依赖于其他刻度值，例如 ConciseDateFormatter。

在 pcolorfast 中添加了对 RGB(A) 图像的支持#

pcolorfast 现在接受三维图像（RGB 或 RGBA）数组，如果 X 和 Y 的规格允许图像或 pcolorimage 渲染；它们在更通用的 quadmesh 渲染中仍然不受支持。

无效输入#

向 legend 和 table 传递无效的位置过去会回退到默认位置。此行为已被弃用，并在未来版本中将抛出异常。

offsetbox.AnchoredText 无法处理 horizontalalignment 或 verticalalignment 关键字参数，并且过去会通过警告忽略它们。此行为已被弃用，并在未来版本中将抛出异常。

将小于1或大于10的步数传递给 MaxNLocator 过去会导致未定义行为。现在它会抛出一个 ValueError。

（私有）``Axis._update_ticks`` 的签名已更改，不再将渲染器作为参数（该参数未使用）。

On this page