1.. _changes_in_1_3:
2
3
4Changes in 1.3.x
5================
6
7Changes in 1.3.1
8----------------
9
10It is rare that we make an API change in a bugfix release, however,
11for 1.3.1 since 1.3.0 the following change was made:
12
13- ``text.Text.cached`` (used to cache font objects) has been made into a
14  private variable.  Among the obvious encapsulation benefit, this
15  removes this confusing-looking member from the documentation.
16
17- The method :meth:`~matplotlib.axes.Axes.hist` now always returns bin
18  occupancies as an array of type `float`. Previously, it was sometimes
19  an array of type `int`, depending on the call.
20
21Code removal
22------------
23
24* The following items that were deprecated in version 1.2 or earlier
25  have now been removed completely.
26
27    - The Qt 3.x backends (``qt`` and ``qtagg``) have been removed in
28      favor of the Qt 4.x backends (``qt4`` and ``qt4agg``).
29
30    - The FltkAgg and Emf backends have been removed.
31
32    - The ``matplotlib.nxutils`` module has been removed.  Use the
33      functionality on `matplotlib.path.Path.contains_point` and
34      friends instead.
35
36    - Instead of ``axes.Axes.get_frame``, use `.axes.Axes.patch`.
37
38    - The following keyword arguments to the `~.axes.Axes.legend` function have
39      been renamed:
40
41      - *pad* -> *borderpad*
42      - *labelsep* -> *labelspacing*
43      - *handlelen* -> *handlelength*
44      - *handletextsep* -> *handletextpad*
45      - *axespad* -> *borderaxespad*
46
47      Related to this, the following rcParams have been removed:
48
49      - ``legend.pad``,
50      - ``legend.labelsep``,
51      - ``legend.handlelen``,
52      - ``legend.handletextsep`` and
53      - ``legend.axespad``
54
55    - For the `~.axes.Axes.hist` function, instead of *width*, use *rwidth*
56      (relative width).
57
58    - On `.patches.Circle`, the *resolution* keyword argument has been removed.
59      For a circle made up of line segments, use
60      `.patches.CirclePolygon`.
61
62    - The printing functions in the Wx backend have been removed due
63      to the burden of keeping them up-to-date.
64
65    - ``mlab.liaupunov`` has been removed.
66
67    - ``mlab.save``, ``mlab.load``, ``pylab.save`` and ``pylab.load`` have
68      been removed.  We recommend using `numpy.savetxt` and
69      `numpy.loadtxt` instead.
70
71    - ``widgets.HorizontalSpanSelector`` has been removed.  Use
72      `.widgets.SpanSelector` instead.
73
74Code deprecation
75----------------
76
77* The CocoaAgg backend has been deprecated, with the possibility for
78  deletion or resurrection in a future release.
79
80* The top-level functions in `matplotlib.path` that are implemented in
81  C++ were never meant to be public.  Instead, users should use the
82  Pythonic wrappers for them in the `.path.Path` and
83  `.collections.Collection` classes.  Use the following mapping to update
84  your code:
85
86    - ``point_in_path`` -> `.path.Path.contains_point`
87    - ``get_path_extents`` -> `.path.Path.get_extents`
88    - ``point_in_path_collection`` -> `.collections.Collection.contains`
89    - ``path_in_path`` -> `.path.Path.contains_path`
90    - ``path_intersects_path`` -> `.path.Path.intersects_path`
91    - ``convert_path_to_polygons`` -> `.path.Path.to_polygons`
92    - ``cleanup_path`` -> `.path.Path.cleaned`
93    - ``points_in_path`` -> `.path.Path.contains_points`
94    - ``clip_path_to_rect`` -> `.path.Path.clip_to_bbox`
95
96* ``matplotlib.colors.normalize`` and ``matplotlib.colors.no_norm`` have
97  been deprecated in favour of `matplotlib.colors.Normalize` and
98  `matplotlib.colors.NoNorm` respectively.
99
100* The `.ScalarMappable` class' ``set_colorbar`` method is now deprecated.
101  Instead, the :attr:`matplotlib.cm.ScalarMappable.colorbar` attribute should
102  be used.  In previous Matplotlib versions this attribute was an undocumented
103  tuple of ``(colorbar_instance, colorbar_axes)`` but is now just
104  ``colorbar_instance``.  To get the colorbar axes it is possible to just use
105  the :attr:`~matplotlib.colorbar.ColorbarBase.ax` attribute on a colorbar
106  instance.
107
108* The ``matplotlib.mpl`` module is now deprecated.  Those who relied on this
109  module should transition to simply using ``import matplotlib as mpl``.
110
111Code changes
112------------
113
114* :class:`~matplotlib.patches.Patch` now fully supports using RGBA values for
115  its ``facecolor`` and ``edgecolor`` attributes, which enables faces and
116  edges to have different alpha values. If the
117  :class:`~matplotlib.patches.Patch` object's ``alpha`` attribute is set to
118  anything other than ``None``, that value will override any alpha-channel
119  value in both the face and edge colors. Previously, if
120  :class:`~matplotlib.patches.Patch` had ``alpha=None``, the alpha component
121  of ``edgecolor`` would be applied to both the edge and face.
122
123* The optional ``isRGB`` argument to
124  :meth:`~matplotlib.backend_bases.GraphicsContextBase.set_foreground` (and
125  the other GraphicsContext classes that descend from it) has been renamed to
126  ``isRGBA``, and should now only be set to ``True`` if the ``fg`` color
127  argument is known to be an RGBA tuple.
128
129* For :class:`~matplotlib.patches.Patch`, the ``capstyle`` used is now
130  ``butt``, to be consistent with the default for most other objects, and to
131  avoid problems with non-solid ``linestyle`` appearing solid when using a
132  large ``linewidth``. Previously, :class:`~matplotlib.patches.Patch` used
133  ``capstyle='projecting'``.
134
135* `.Path` objects can now be marked as *readonly* by passing
136  ``readonly=True`` to its constructor.  The built-in path singletons,
137  obtained through ``Path.unit*`` class methods return readonly paths.
138  If you have code that modified these, you will need to make a
139  deepcopy first, using either::
140
141    import copy
142    path = copy.deepcopy(Path.unit_circle())
143
144    # or
145
146    path = Path.unit_circle().deepcopy()
147
148  Deep copying a `.Path` always creates an editable (i.e. non-readonly)
149  `.Path`.
150
151* The list at ``Path.NUM_VERTICES`` was replaced by a dictionary mapping
152  Path codes to the number of expected vertices at
153  :attr:`~matplotlib.path.Path.NUM_VERTICES_FOR_CODE`.
154
155* To support XKCD style plots, the ``matplotlib.path.cleanup_path``
156  method's signature was updated to require a sketch argument. Users of
157  ``matplotlib.path.cleanup_path`` are encouraged to use the new
158  :meth:`~matplotlib.path.Path.cleaned` Path method.
159
160* Data limits on a plot now start from a state of having "null"
161  limits, rather than limits in the range (0, 1).  This has an effect
162  on artists that only control limits in one direction, such as
163  `.axes.Axes.axvline` and `.axes.Axes.axhline`, since their limits will no
164  longer also include the range (0, 1).  This fixes some problems where the
165  computed limits would be dependent on the order in which artists
166  were added to the axes.
167
168* Fixed a bug in setting the position for the right/top spine with data
169  position type. Previously, it would draw the right or top spine at
170  +1 data offset.
171
172* In :class:`~matplotlib.patches.FancyArrow`, the default arrow head
173  width, ``head_width``, has been made larger to produce a visible
174  arrow head. The new value of this kwarg is ``head_width = 20 *
175  width``.
176
177* It is now possible to provide ``number of levels + 1`` colors in the case of
178  ``extend='both'`` for contourf (or just ``number of levels`` colors for an
179  extend value ``min`` or ``max``) such that the resulting colormap's
180  ``set_under`` and ``set_over`` are defined appropriately. Any other number
181  of colors will continue to behave as before (if more colors are provided
182  than levels, the colors will be unused). A similar change has been applied
183  to contour, where ``extend='both'`` would expect ``number of levels + 2``
184  colors.
185
186* A new keyword *extendrect* in :meth:`~matplotlib.pyplot.colorbar` and
187  :class:`~matplotlib.colorbar.ColorbarBase` allows one to control the shape
188  of colorbar extensions.
189
190* The extension of :class:`~matplotlib.widgets.MultiCursor` to both vertical
191  (default) and/or horizontal cursor implied that ``self.line`` is replaced
192  by ``self.vline`` for vertical cursors lines and ``self.hline`` is added
193  for the horizontal cursors lines.
194
195* On POSIX platforms, the :func:`~matplotlib.cbook.report_memory` function
196  raises :class:`NotImplementedError` instead of :class:`OSError` if the
197  :command:`ps` command cannot be run.
198
199* The ``matplotlib.cbook.check_output`` function has been moved to
200  ``matplotlib.compat.subprocess``.
201
202Configuration and rcParams
203--------------------------
204
205* On Linux, the user-specific :file:`matplotlibrc` configuration file is now
206  located in :file:`~/.config/matplotlib/matplotlibrc` to conform to the
207  `XDG Base Directory Specification
208  <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_.
209
210* The ``font.*`` rcParams now affect only text objects created after the
211  rcParam has been set, and will not retroactively affect already
212  existing text objects.  This brings their behavior in line with most
213  other rcParams.
214
215* Removed call of :meth:`~matplotlib.axes.Axes.grid` in
216  ``matplotlib.pyplot.plotfile``. To draw the axes grid, set the
217  ``axes.grid`` rcParam to *True*, or explicitly call
218  :meth:`~matplotlib.axes.Axes.grid`.
219