1
2API Changes in 2.2.0
3====================
4
5
6
7New dependency
8--------------
9
10`kiwisolver <https://github.com/nucleic/kiwi>`__ is now a required
11dependency to support the new constrained_layout,  see
12:doc:`/tutorials/intermediate/constrainedlayout_guide` for
13more details.
14
15
16Deprecations
17------------
18
19Classes, functions, and methods
20~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
21
22The unused and untested ``Artist.onRemove`` and ``Artist.hitlist`` methods have
23been deprecated.
24
25The now unused ``mlab.less_simple_linear_interpolation`` function is
26deprecated.
27
28The unused ``ContourLabeler.get_real_label_width`` method is deprecated.
29
30The unused ``FigureManagerBase.show_popup`` method is deprecated.  This
31introduced in e945059b327d42a99938b939a1be867fa023e7ba in 2005 but never built
32out into any of the backends.
33
34``backend_tkagg.AxisMenu`` is deprecated, as it has become unused since the
35removal of "classic" toolbars.
36
37
38Changed function signatures
39~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
41kwarg ``fig`` to `.GridSpec.get_subplot_params` is
42deprecated,  use ``figure`` instead.
43
44Using `.pyplot.axes` with an `~matplotlib.axes.Axes` as argument is deprecated. This sets
45the current axes, i.e. it has the same effect as `.pyplot.sca`. For clarity
46``plt.sca(ax)`` should be preferred over ``plt.axes(ax)``.
47
48
49Using strings instead of booleans to control grid and tick visibility
50is deprecated.  Using ``"on"``, ``"off"``, ``"true"``, or ``"false"``
51to control grid and tick visibility has been deprecated.  Instead, use
52normal booleans (``True``/``False``) or boolean-likes.  In the future,
53all non-empty strings may be interpreted as ``True``.
54
55When given 2D inputs with non-matching numbers of columns, `~.pyplot.plot`
56currently cycles through the columns of the narrower input, until all the
57columns of the wider input have been plotted.  This behavior is deprecated; in
58the future, only broadcasting (1 column to *n* columns) will be performed.
59
60
61rcparams
62~~~~~~~~
63
64The :rc:`backend.qt4` and :rc:`backend.qt5` rcParams were deprecated
65in version 2.2.  In order to force the use of a specific Qt binding,
66either import that binding first, or set the ``QT_API`` environment
67variable.
68
69Deprecation of the ``nbagg.transparent`` rcParam.  To control
70transparency of figure patches in the nbagg (or any other) backend,
71directly set ``figure.patch.facecolor``, or the ``figure.facecolor``
72rcParam.
73
74Deprecated ``Axis.unit_data``
75~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77Use `.Axis.units` (which has long existed) instead.
78
79
80Removals
81--------
82
83Function Signatures
84~~~~~~~~~~~~~~~~~~~
85
86Contouring no longer supports ``legacy`` corner masking.  The
87deprecated ``ContourSet.vmin`` and ``ContourSet.vmax`` properties have
88been removed.
89
90Passing ``None`` instead of ``"none"`` as format to `~.Axes.errorbar` is no
91longer supported.
92
93The ``bgcolor`` keyword argument to ``Axes`` has been removed.
94
95Modules, methods, and functions
96~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97
98The ``matplotlib.finance``, ``mpl_toolkits.exceltools`` and
99``mpl_toolkits.gtktools`` modules have been removed.  ``matplotlib.finance``
100remains available at https://github.com/matplotlib/mpl_finance.
101
102The ``mpl_toolkits.mplot3d.art3d.iscolor`` function has been removed.
103
104The ``Axes.get_axis_bgcolor``, ``Axes.set_axis_bgcolor``,
105``Bbox.update_from_data``, ``Bbox.update_datalim_numerix``,
106``MaxNLocator.bin_boundaries`` methods have been removed.
107
108``mencoder`` can no longer be used to encode animations.
109
110The unused ``FONT_SCALE`` and ``fontd`` attributes of the `.RendererSVG`
111class have been removed.
112
113colormaps
114~~~~~~~~~
115
116The ``spectral`` colormap has been removed.  The ``Vega*`` colormaps, which
117were aliases for the ``tab*`` colormaps, have been removed.
118
119
120rcparams
121~~~~~~~~
122
123The following deprecated rcParams have been removed:
124
125- ``axes.color_cycle`` (see ``axes.prop_cycle``),
126- ``legend.isaxes``,
127- ``svg.embed_char_paths`` (see ``svg.fonttype``),
128- ``text.fontstyle``, ``text.fontangle``, ``text.fontvariant``,
129  ``text.fontweight``, ``text.fontsize`` (renamed to ``text.style``, etc.),
130- ``tick.size`` (renamed to ``tick.major.size``).
131
132
133
134Only accept string-like for Categorical input
135---------------------------------------------
136
137Do not accept mixed string / float / int input, only
138strings are valid categoricals.
139
140Removal of unused imports
141-------------------------
142Many unused imports were removed from the codebase.  As a result,
143trying to import certain classes or functions from the "wrong" module
144(e.g. `~.Figure` from :mod:`matplotlib.backends.backend_agg` instead of
145:mod:`matplotlib.figure`) will now raise an `ImportError`.
146
147
148``Axes3D.get_xlim``, ``get_ylim`` and ``get_zlim`` now return a tuple
149---------------------------------------------------------------------
150
151They previously returned an array.  Returning a tuple is consistent with the
152behavior for 2D axes.
153
154
155Exception type changes
156----------------------
157
158If `.MovieWriterRegistry` can't find the requested `.MovieWriter`, a
159more helpful `RuntimeError` message is now raised instead of the
160previously raised `KeyError`.
161
162`~.tight_layout.auto_adjust_subplotpars` now raises `ValueError`
163instead of `RuntimeError` when sizes of input lists don't match
164
165
166`.Figure.set_figwidth` and `.Figure.set_figheight` default *forward* to True
167----------------------------------------------------------------------------
168
169`matplotlib.figure.Figure.set_figwidth` and
170`matplotlib.figure.Figure.set_figheight` had the keyword argument
171``forward=False`` by default, but `.figure.Figure.set_size_inches` now defaults
172to ``forward=True``.  This makes these functions conistent.
173
174
175Do not truncate svg sizes to nearest point
176------------------------------------------
177
178There is no reason to size the SVG out put in integer points, change
179to out putting floats for the *height*, *width*, and *viewBox* attributes
180of the *svg* element.
181
182
183Fontsizes less than 1 pt are clipped to be 1 pt.
184------------------------------------------------
185
186FreeType doesn't allow fonts to get smaller than 1 pt, so all Agg
187backends were silently rounding up to 1 pt.  PDF (other vector
188backends?) were letting us write fonts that were less than 1 pt, but
189they could not be placed properly because position information comes from
190FreeType.  This change makes it so no backends can use fonts smaller than
1911 pt, consistent with FreeType and ensuring more consistent results across
192backends.
193
194
195
196Changes to Qt backend class MRO
197-------------------------------
198
199To support both Agg and cairo rendering for Qt backends all of the non-Agg
200specific code previously in ``backend_qt5agg.FigureCanvasQTAggBase`` has been
201moved to :class:`.backend_qt5.FigureCanvasQT` so it can be shared with the
202cairo implementation.  The ``FigureCanvasQTAggBase.paintEvent``,
203``FigureCanvasQTAggBase.blit``, and ``FigureCanvasQTAggBase.print_figure``
204methods have moved to :meth:`.FigureCanvasQTAgg.paintEvent`,
205:meth:`.FigureCanvasQTAgg.blit`, and :meth:`.FigureCanvasQTAgg.print_figure`.
206The first two methods assume that the instance is also a ``QWidget`` so to use
207``FigureCanvasQTAggBase`` it was required to multiple inherit from a
208``QWidget`` sub-class.
209
210Having moved all of its methods either up or down the class hierarchy
211``FigureCanvasQTAggBase`` has been deprecated.  To do this without warning and
212to preserve as much API as possible, ``.backend_qt5agg.FigureCanvasQTAggBase``
213now inherits from :class:`.backend_qt5.FigureCanvasQTAgg`.
214
215The MRO for :class:`.FigureCanvasQTAgg` and ``FigureCanvasQTAggBase`` used to
216be ::
217
218
219   [matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg,
220    matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase,
221    matplotlib.backends.backend_agg.FigureCanvasAgg,
222    matplotlib.backends.backend_qt5.FigureCanvasQT,
223    PyQt5.QtWidgets.QWidget,
224    PyQt5.QtCore.QObject,
225    sip.wrapper,
226    PyQt5.QtGui.QPaintDevice,
227    sip.simplewrapper,
228    matplotlib.backend_bases.FigureCanvasBase,
229    object]
230
231and ::
232
233
234   [matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase,
235    matplotlib.backends.backend_agg.FigureCanvasAgg,
236    matplotlib.backend_bases.FigureCanvasBase,
237    object]
238
239
240respectively.  They are now ::
241
242   [matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg,
243    matplotlib.backends.backend_agg.FigureCanvasAgg,
244    matplotlib.backends.backend_qt5.FigureCanvasQT,
245    PyQt5.QtWidgets.QWidget,
246    PyQt5.QtCore.QObject,
247    sip.wrapper,
248    PyQt5.QtGui.QPaintDevice,
249    sip.simplewrapper,
250    matplotlib.backend_bases.FigureCanvasBase,
251    object]
252
253and ::
254
255   [matplotlib.backends.backend_qt5agg.FigureCanvasQTAggBase,
256    matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg,
257    matplotlib.backends.backend_agg.FigureCanvasAgg,
258    matplotlib.backends.backend_qt5.FigureCanvasQT,
259    PyQt5.QtWidgets.QWidget,
260    PyQt5.QtCore.QObject,
261    sip.wrapper,
262    PyQt5.QtGui.QPaintDevice,
263    sip.simplewrapper,
264    matplotlib.backend_bases.FigureCanvasBase,
265    object]
266
267
268
269
270`.axes.Axes.imshow` clips RGB values to the valid range
271-------------------------------------------------------
272
273When `.axes.Axes.imshow` is passed an RGB or RGBA value with out-of-range
274values, it now logs a warning and clips them to the valid range.
275The old behaviour, wrapping back in to the range, often hid outliers
276and made interpreting RGB images unreliable.
277
278
279GTKAgg and GTKCairo backends deprecated
280---------------------------------------
281
282The GTKAgg and GTKCairo backends have been deprecated. These obsolete backends
283allow figures to be rendered via the GTK+ 2 toolkit. They are untested, known
284to be broken, will not work with Python 3, and their use has been discouraged
285for some time. Instead, use the ``GTK3Agg`` and ``GTK3Cairo`` backends for
286rendering to GTK+ 3 windows.
287