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 关键字参数设置为 True，则使用 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 现在尊重 rcParams["boxplot.boxprops.linewidth"] (默认: 1.0)，即使设置了 patch_artist。以前，当设置了 patch_artist 参数时，bxp 会忽略 rcParams["boxplot.boxprops.linewidth"] (默认: 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"] (默认: 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)#

以前，Sankey.add 只接受一个字符串作为 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 参数检查#

以前 Axes.tick_params 在提供无效的 axis 参数时会静默地不做任何事情。此行为已更改为改为引发 ValueError>。

Axes.hist 输出#

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

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)

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

ColorbarBase 继承#

matplotlib.colorbar.ColorbarBase 不再是 cm.ScalarMappable 的子类。这种继承导致了一种令人困惑的情况，即传递给 matplotlib.colorbar.Colorbar (colorbar) 的 cm.ScalarMappable 有一个 set_norm 方法，色条也有。色条现在纯粹是 ScalarMappable 范数和颜色映射的跟随者，旧的继承方法 matplotlib.colorbar.ColorbarBase.set_norm, matplotlib.colorbar.ColorbarBase.set_cmap, matplotlib.colorbar.ColorbarBase.set_clim 已被废弃，它们的 getter 版本也一样。要设置与色条关联的范数，请使用 colorbar.mappable.set_norm() 等。

FreeType 和 libpng 搜索路径#

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

详见 安装。

在同一次调用中设置 artist 属性两次或多次#

通过别名多次设置同一个 artist 属性已被废弃。以前，像下面这样的代码

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)#

MouseEvent 现在在它们的 str() 中包含事件名称。以前它们包含前缀“MPL MouseEvent”。

RGBA 缓冲区返回类型#

FigureCanvasAgg.buffer_rgba 和 RendererAgg.buffer_rgba 现在返回一个 memoryview。buffer_rgba 方法现在允许直接访问渲染器底层缓冲区（作为 (m, n, 4) 形状的 memoryview），而不是将数据复制到新的字节串。这与 Py2 中的行为一致，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 属性已被废弃。直接获取和设置底层 artist 的可见性，这些 artist 可通过 gridline、tick1line、tick2line、label1 和 label2 属性访问。

作为 label1 别名的 label 属性已被废弃。

依赖于设置上述可见性属性的子类需要更新；例如，请参见 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"] (默认: '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}。

异常变更#

移除#

以下已弃用的 API 已移除

类和方法#

  • Verbose (替换为 python logging 库)

  • 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"] (默认: '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.mlab 模块中在 Matplotlib 2.2 中已废弃的许多代码已被移除。请参阅以下列表

  • 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.mlab 模块中在 Matplotlib 2.2 中已废弃的许多代码已被移除。这意味着以下函数不再在 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年发布）。

Mathtext 更改#

  • 在 "$1~2$" 等构造中，mathtext 现在将波浪号解释为空格，与 TeX 保持一致（这之前是解析错误）。

弃用#

  • \stackrel mathtext 命令已弃用（它的行为与 LaTeX 的 \stackrel 不同）。要堆叠两个 mathtext 表达式，请使用 \genfrac{left-delim}{right-delim}{fraction-bar-thickness}{}{top}{bottom}。

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

  • 已弃用对将 rcParams["mathtext.default"]（默认值：'it'）设置为环绕式的支持。

签名弃用#

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

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

  • 向 Axes.errorbar() 传递 (n, 1) 形状的错误数组，这没有文档记录，并且对 n = 2 不起作用。请改为传递一维数组。

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

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

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

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

  • 向 axes.Axes.axis() 传递 'normal' 已弃用，请使用 ax.axis('auto') 代替。

  • 按位置传递 pyplot.show 的 block 参数已弃用；应按关键字传递。

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

  • 已弃用 Axes.imshow 中未使用的 shape 和 imlim 参数。为避免触发弃用警告，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 本身以外的位置参数无效，对它们的支持已弃用。

  • 向 plot_surface 传递 shade=None 已弃用。这曾是一个意料之外的实现细节，其语义与 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#

  • Quiver 对象的 .color 属性

请改用（与任何 Collection 相同）get_facecolor 方法。请注意，设置 .color 属性不会更新 quiver artist，而调用 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 模块

此模块是 PyPI 上提供的官方 formlayout 模块的修改版本。如果您需要它，请单独安装该模块。

  • 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 关键字参数。

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

新功能#

Text 现在拥有 color 属性的 c 别名#

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

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) 图像的支持#

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

无效输入#

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

offsetbox.AnchoredText 无法处理 horizontalalignment 或 verticalalignment 关键字参数，并曾带警告忽略它们。此行为已弃用，并将在未来版本中引发异常。

向 MaxNLocator 传递小于 1 或大于 10 的步长过去会导致未定义的行为。现在它会引发 ValueError。

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

在此页