.. _changes_in_1_3:

API Changes in 1.3.x

Changes in 1.3.1

It is rare that we make an API change in a micro release, however, for 1.3.1 since 1.3.0 the following change was made:

text.Text.cached (used to cache font objects) has been made into a private variable. Among the obvious encapsulation benefit, this removes this confusing-looking member from the documentation.
The method :meth:~matplotlib.axes.Axes.hist now always returns bin occupancies as an array of type float. Previously, it was sometimes an array of type int, depending on the call.

Code removal

The following items that were deprecated in version 1.2 or earlier have now been removed completely.
- The Qt 3.x backends (qt and qtagg) have been removed in favor of the Qt 4.x backends (qt4 and qt4agg).
- The FltkAgg and Emf backends have been removed.
- The matplotlib.nxutils module has been removed. Use the functionality on matplotlib.path.Path.contains_point and friends instead.
- Instead of axes.Axes.get_frame, use axes.Axes.patch.
- The following keyword arguments to the ~.axes.Axes.legend function have been renamed:
  - pad -> borderpad
  - labelsep -> labelspacing
  - handlelen -> handlelength
  - handletextsep -> handletextpad
  - axespad -> borderaxespad
  Related to this, the following rcParams have been removed:
  - legend.pad,
  - legend.labelsep,
  - legend.handlelen,
  - legend.handletextsep and
  - legend.axespad
- For the ~.axes.Axes.hist function, instead of width, use rwidth (relative width).
- On .patches.Circle, the resolution keyword argument has been removed. For a circle made up of line segments, use .patches.CirclePolygon.
- The printing functions in the Wx backend have been removed due to the burden of keeping them up-to-date.
- mlab.liaupunov has been removed.
- mlab.save, mlab.load, pylab.save and pylab.load have been removed. We recommend using numpy.savetxt and numpy.loadtxt instead.
- widgets.HorizontalSpanSelector has been removed. Use .widgets.SpanSelector instead.

Code deprecation

The CocoaAgg backend has been deprecated, with the possibility for deletion or resurrection in a future release.
The top-level functions in matplotlib.path that are implemented in C++ were never meant to be public. Instead, users should use the Pythonic wrappers for them in the .path.Path and .collections.Collection classes. Use the following mapping to update your code:
- point_in_path -> .path.Path.contains_point
- get_path_extents -> .path.Path.get_extents
- point_in_path_collection -> .collections.Collection.contains
- path_in_path -> .path.Path.contains_path
- path_intersects_path -> .path.Path.intersects_path
- convert_path_to_polygons -> .path.Path.to_polygons
- cleanup_path -> .path.Path.cleaned
- points_in_path -> .path.Path.contains_points
- clip_path_to_rect -> .path.Path.clip_to_bbox
matplotlib.colors.normalize and matplotlib.colors.no_norm have been deprecated in favour of matplotlib.colors.Normalize and matplotlib.colors.NoNorm respectively.
The .ScalarMappable class' set_colorbar method is now deprecated. Instead, the :attr:matplotlib.cm.ScalarMappable.colorbar attribute should be used. In previous Matplotlib versions this attribute was an undocumented tuple of (colorbar_instance, colorbar_axes) but is now just colorbar_instance. To get the colorbar axes it is possible to just use the matplotlib.colorbar.ColorbarBase.ax attribute on a colorbar instance.
The matplotlib.mpl module is now deprecated. Those who relied on this module should transition to simply using import matplotlib as mpl.

Code changes

:class:~matplotlib.patches.Patch now fully supports using RGBA values for its facecolor and edgecolor attributes, which enables faces and edges to have different alpha values. If the :class:~matplotlib.patches.Patch object's alpha attribute is set to anything other than None, that value will override any alpha-channel value in both the face and edge colors. Previously, if :class:~matplotlib.patches.Patch had alpha=None, the alpha component of edgecolor would be applied to both the edge and face.
The optional isRGB argument to :meth:~matplotlib.backend_bases.GraphicsContextBase.set_foreground (and the other GraphicsContext classes that descend from it) has been renamed to isRGBA, and should now only be set to True if the fg color argument is known to be an RGBA tuple.
For :class:~matplotlib.patches.Patch, the capstyle used is now butt, to be consistent with the default for most other objects, and to avoid problems with non-solid linestyle appearing solid when using a large linewidth. Previously, :class:~matplotlib.patches.Patch used capstyle='projecting'.
.Path objects can now be marked as readonly by passing readonly=True to its constructor. The built-in path singletons, obtained through Path.unit* class methods return readonly paths. If you have code that modified these, you will need to make a deepcopy first, using either::

import copy path = copy.deepcopy(Path.unit_circle())

or

path = Path.unit_circle().deepcopy()

Deep copying a .Path always creates an editable (i.e. non-readonly) .Path.
The list at Path.NUM_VERTICES was replaced by a dictionary mapping Path codes to the number of expected vertices at :attr:~matplotlib.path.Path.NUM_VERTICES_FOR_CODE.
To support XKCD style plots, the matplotlib.path.cleanup_path method's signature was updated to require a sketch argument. Users of matplotlib.path.cleanup_path are encouraged to use the new :meth:~matplotlib.path.Path.cleaned Path method.
Data limits on a plot now start from a state of having "null" limits, rather than limits in the range (0, 1). This has an effect on artists that only control limits in one direction, such as .axes.Axes.axvline and .axes.Axes.axhline, since their limits will no longer also include the range (0, 1). This fixes some problems where the computed limits would be dependent on the order in which artists were added to the axes.
Fixed a bug in setting the position for the right/top spine with data position type. Previously, it would draw the right or top spine at +1 data offset.
In :class:~matplotlib.patches.FancyArrow, the default arrow head width, head_width, has been made larger to produce a visible arrow head. The new value of this kwarg is head_width = 20 * width.
It is now possible to provide number of levels + 1 colors in the case of extend='both' for contourf (or just number of levels colors for an extend value min or max) such that the resulting colormap's set_under and set_over are defined appropriately. Any other number of colors will continue to behave as before (if more colors are provided than levels, the colors will be unused). A similar change has been applied to contour, where extend='both' would expect number of levels + 2 colors.
A new keyword extendrect in :meth:~matplotlib.pyplot.colorbar and :class:~matplotlib.colorbar.ColorbarBase allows one to control the shape of colorbar extensions.
The extension of :class:~matplotlib.widgets.MultiCursor to both vertical (default) and/or horizontal cursor implied that self.line is replaced by self.vline for vertical cursors lines and self.hline is added for the horizontal cursors lines.
On POSIX platforms, the matplotlib.cbook.report_memory function raises :class:NotImplementedError instead of :class:OSError if the :command:ps command cannot be run.
The matplotlib.cbook.check_output function has been moved to matplotlib.compat.subprocess.

Configuration and rcParams

On Linux, the user-specific :file:matplotlibrc configuration file is now located in :file:~/.config/matplotlib/matplotlibrc to conform to the XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>_.
The font.* rcParams now affect only text objects created after the rcParam has been set, and will not retroactively affect already existing text objects. This brings their behavior in line with most other rcParams.
Removed call of :meth:~matplotlib.axes.Axes.grid in matplotlib.pyplot.plotfile. To draw the axes grid, set the axes.grid rcParam to True, or explicitly call :meth:~matplotlib.axes.Axes.grid.