API Changes for 3.10.0#

Behavior Changes#

onselect argument to selector widgets made optional#

The onselect argument to EllipseSelector, LassoSelector, PolygonSelector, and RectangleSelector is no longer required.

SVG output: improved reproducibility#

Some SVG-format plots produced different output on each render, even with a static svg.hashsalt value configured.

The problem was a non-deterministic ID-generation scheme for clip paths; the fix introduces a repeatable, monotonically increasing integer ID scheme as a replacement.

Provided that plots add clip paths themselves in deterministic order, this enables repeatable (a.k.a. reproducible, deterministic) SVG output.

ft2font classes are now final#

The ft2font classes ft2font.FT2Font, and ft2font.FT2Image are now final and can no longer be subclassed.

InsetIndicator artist#

indicate_inset and indicate_inset_zoom now return an instance of InsetIndicator. Use the rectangle and connectors properties of this artist to access the objects that were previously returned directly.

imshow interpolation_stage default changed to 'auto'#

The interpolation_stage parameter of imshow has a new default value 'auto'. For images that are up-sampled less than a factor of three or down-sampled, image interpolation will occur in 'rgba' space. For images that are up-sampled by a factor of 3 or more, then image interpolation occurs in 'data' space.

The previous default was 'data', so down-sampled images may change subtly with the new default. However, the new default also avoids floating point artifacts at sharp boundaries in a colormap when down-sampling.

The previous behavior can achieved by setting the interpolation_stage parameter or rcParams["image.interpolation_stage"] (default: 'auto') to 'data'.

imshow default interpolation changed to 'auto'#

The interpolation parameter of imshow has a new default value 'auto', changed from 'antialiased', for consistency with interpolation_stage and because the interpolation is only anti-aliasing during down-sampling. Passing 'antialiased' still works, and behaves exactly the same as 'auto', but is discouraged.

dark_background and fivethirtyeight styles no longer set savefig.facecolor and savefig.edgecolor#

When using these styles, rcParams["savefig.facecolor"] (default: 'auto') and rcParams["savefig.edgecolor"] (default: 'auto') now inherit the global default value of "auto", which means that the actual figure colors will be used. Previously, these rcParams were set to the same values as rcParams["figure.facecolor"] (default: 'white') and rcParams["figure.edgecolor"] (default: 'white'), i.e. a saved figure would always use the theme colors even if the user manually overrode them; this is no longer the case.

This change should have no impact for users that do not manually set the figure face and edge colors.

Add zorder option in QuiverKey#

zorder can be used as a keyword argument to QuiverKey. Previously, that parameter did not have any effect because the zorder was hard coded.

Subfigures#

Figure.subfigures are now added in row-major order to be consistent with Figure.subplots. The return value of subfigures is not changed, but the order of fig.subfigs is.

(Sub)Figure.get_figure#

...in future will by default return the direct parent figure, which may be a SubFigure. This will make the default behavior consistent with the get_figure method of other artists. To control the behavior, use the newly introduced root parameter.

transforms.AffineDeltaTransform updates correctly on axis limit changes#

Before this change, transform sub-graphs with AffineDeltaTransform did not update correctly. This PR ensures that changes to the child transform are passed through correctly.

The offset string associated with ConciseDateFormatter will now invert when the axis is inverted#

Previously, when the axis was inverted, the offset string associated with ConciseDateFormatter would not change, so the offset string indicated the axis was oriented in the wrong direction. Now, when the axis is inverted, the offset string is oriented correctly.

suptitle in compressed layout#

Compressed layout now automatically positions the suptitle just above the top row of axes. To keep this title in its previous position, either pass in_layout=False or explicitly set y=0.98 in the suptitle call.

Deprecations#

Positional parameters in plotting functions#

Many plotting functions will restrict positional arguments to the first few parameters in the future. All further configuration parameters will have to be passed as keyword arguments. This is to enforce better code and and allow for future changes with reduced risk of breaking existing code.

Changing Figure.number#

Changing Figure.number is deprecated. This value is used by pyplot to identify figures. It must stay in sync with the pyplot internal state and is not intended to be modified by the user.

PdfFile.hatchPatterns#

... is deprecated.

(Sub)Figure.set_figure#

...is deprecated and in future will always raise an exception. The parent and root figures of a (Sub)Figure are set at instantiation and cannot be changed.

Poly3DCollection.get_vector#

... is deprecated with no replacement.

Deprecated register on matplotlib.patches._Styles and subclasses#

This class method is never used internally. Due to the internal check in the method it only accepts subclasses of a private baseclass embedded in the host class which makes it unlikely that it has been used externally.

matplotlib.validate_backend#

...is deprecated. Please use matplotlib.rcsetup.validate_backend instead.

matplotlib.sanitize_sequence#

...is deprecated. Please use matplotlib.cbook.sanitize_sequence instead.

ft2font module-level constants replaced by enums#

The ft2font-level constants have been converted to enum classes, and all API using them now take/return the new types.

The following constants are now part of ft2font.Kerning (without the KERNING_ prefix):

  • KERNING_DEFAULT

  • KERNING_UNFITTED

  • KERNING_UNSCALED

The following constants are now part of ft2font.LoadFlags (without the LOAD_ prefix):

  • LOAD_DEFAULT

  • LOAD_NO_SCALE

  • LOAD_NO_HINTING

  • LOAD_RENDER

  • LOAD_NO_BITMAP

  • LOAD_VERTICAL_LAYOUT

  • LOAD_FORCE_AUTOHINT

  • LOAD_CROP_BITMAP

  • LOAD_PEDANTIC

  • LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH

  • LOAD_NO_RECURSE

  • LOAD_IGNORE_TRANSFORM

  • LOAD_MONOCHROME

  • LOAD_LINEAR_DESIGN

  • LOAD_NO_AUTOHINT

  • LOAD_TARGET_NORMAL

  • LOAD_TARGET_LIGHT

  • LOAD_TARGET_MONO

  • LOAD_TARGET_LCD

  • LOAD_TARGET_LCD_V

The following constants are now part of ft2font.FaceFlags:

  • EXTERNAL_STREAM

  • FAST_GLYPHS

  • FIXED_SIZES

  • FIXED_WIDTH

  • GLYPH_NAMES

  • HORIZONTAL

  • KERNING

  • MULTIPLE_MASTERS

  • SCALABLE

  • SFNT

  • VERTICAL

The following constants are now part of ft2font.StyleFlags:

  • ITALIC

  • BOLD

FontProperties initialization#

FontProperties initialization is limited to the two call patterns:

  • single positional parameter, interpreted as fontconfig pattern

  • only keyword parameters for setting individual properties

All other previously supported call patterns are deprecated.

AxLine xy1 and xy2 setters#

These setters now each take a single argument, xy1 or xy2 as a tuple. The old form, where x and y were passed as separate arguments, is deprecated.

Calling pyplot.polar() with an existing non-polar Axes#

This currently plots the data into the non-polar Axes, ignoring the "polar" intention. This usage scenario is deprecated and will raise an error in the future.

Passing floating-point values to RendererAgg.draw_text_image#

Any floating-point values passed to the x and y parameters were truncated to integers silently. This behaviour is now deprecated, and only int values should be used.

Passing floating-point values to FT2Image#

Any floating-point values passed to the FT2Image constructor, or the x0, y0, x1, and y1 parameters of FT2Image.draw_rect_filled were truncated to integers silently. This behaviour is now deprecated, and only int values should be used.

boxplot and bxp vert parameter, and rcParams["boxplot.vertical"]#

The parameter vert: bool has been deprecated on boxplot and bxp. It is replaced by orientation: {"vertical", "horizontal"} for API consistency.

rcParams["boxplot.vertical"], which controlled the orientation of boxplot, is deprecated without replacement.

This deprecation is currently marked as pending and will be fully deprecated in Matplotlib 3.11.

violinplot and violin vert parameter#

The parameter vert: bool has been deprecated on violinplot and violin. It will be replaced by orientation: {"vertical", "horizontal"} for API consistency.

This deprecation is currently marked as pending and will be fully deprecated in Matplotlib 3.11.

proj3d.proj_transform_clip#

... is deprecated with no replacement.

Removals#

ttconv removed#

The matplotlib._ttconv extension has been removed. Most of its functionaliy was already replaced by other code, and the only thing left was embedding TTF fonts in PostScript in Type 42 format. This is now done in the PS backend using the FontTools library.

Remove hard reference to lastevent in LocationEvent#

This was previously used to detect exiting from axes, however the hard reference would keep closed Figure objects and their children alive longer than expected.

ft2font.FT2Image.draw_rect and ft2font.FT2Font.get_xys#

... have been removed as they are unused.

Tick.set_label, Tick.set_label1 and Tick.set_label2#

... are removed. Calling these methods from third-party code usually had no effect, as the labels are overwritten at draw time by the tick formatter.

Functions in mpl_toolkits.mplot3d.proj3d#

The function transform is just an alias for proj_transform, use the latter instead.

The following functions were either unused (so no longer required in Matplotlib) or considered private.

  • ortho_transformation

  • persp_transformation

  • proj_points

  • proj_trans_points

  • rot_x

  • rotation_about_vector

  • view_transformation

Arguments other than renderer to get_tightbbox#

... are keyword-only arguments. This is for consistency and that different classes have different additional arguments.

Method parameters renamed to match base classes#

The only parameter of transform_affine and transform_non_affine in Transform subclasses is renamed to values.

The points parameter of transforms.IdentityTransform.transform is renamed to values.

The trans parameter of table.Cell.set_transform is renamed to t consistently with Artist.set_transform.

The clippath parameters of axis.Axis.set_clip_path and axis.Tick.set_clip_path are renamed to path consistently with Artist.set_clip_path.

The s parameter of images.NonUniformImage.set_filternorm is renamed to filternorm consistently with _ImageBase.set_filternorm.

The s parameter of images.NonUniformImage.set_filterrad is renamed to filterrad consistently with _ImageBase.set_filterrad.

The only parameter of Annotation.contains and Legend.contains is renamed to mouseevent consistently with Artist.contains.

Method parameters renamed#

The p parameter of BboxBase.padded is renamed to w_pad, consistently with the other parameter, h_pad

numdecs parameter and attribute of LogLocator#

... are removed without replacement, because they had no effect. The PolyQuadMesh class requires full 2D arrays of values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Previously, if a masked array was input, the list of polygons within the collection would shrink to the size of valid polygons and users were required to keep track of which polygons were drawn and call set_array() with the smaller "compressed" array size. Passing the "compressed" and flattened array values will no longer work and the full 2D array of values (including the mask) should be passed to PolyQuadMesh.set_array. ContourSet.collections ~~~~~~~~~~~~~~~~~~~~~~~~~~

... has been removed. ContourSet is now implemented as a single Collection of paths, each path corresponding to a contour level, possibly including multiple unconnected components.

ContourSet.antialiased#

... has been removed. Use get_antialiased or set_antialiased instead. Note that get_antialiased returns an array.

tcolors and tlinewidths attributes of ContourSet#

... have been removed. Use get_facecolor, get_edgecolor or get_linewidths instead.

calc_label_rot_and_inline method of ContourLabeler#

... has been removed without replacement.

add_label_clabeltext method of ContourLabeler#

... has been removed. Use add_label instead. Passing extra positional arguments to Figure.add_axes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Positional arguments passed to Figure.add_axes other than a rect or an existing Axes were previously ignored, and is now an error.

Artists explicitly passed in will no longer be filtered by legend() based on their label#

Previously, artists explicitly passed to legend(handles=[...]) are filtered out if their label starts with an underscore. This filter is no longer applied; explicitly filter out such artists ([art for art in artists if not art.get_label().startswith('_')]) if necessary.

Note that if no handles are specified at all, then the default still filters out labels starting with an underscore.

The parameter of Annotation.contains and Legend.contains is renamed to mouseevent#

... consistently with Artist.contains.

Support for passing the "frac" key in annotate(..., arrowprops={"frac": ...})#

... has been removed. This key has had no effect since Matplotlib 1.5.

Passing non-int or sequence of non-int to Table.auto_set_column_width#

Column numbers are ints, and formerly passing any other type was effectively ignored. This has now become an error.

Widgets#

The visible attribute getter of *Selector widgets has been removed; use get_visible instead.

Auto-closing of figures when switching backend#

Allowable backend switches (i.e. those that do not swap a GUI event loop with another one) will not close existing figures. If necessary, call plt.close("all") before switching.

FigureCanvasBase.switch_backends#

... has been removed with no replacement.

Accessing event.guiEvent after event handlers return#

... is no longer supported, and event.guiEvent will be set to None once the event handlers return. For some GUI toolkits, it is unsafe to use the event, though you may separately stash the object at your own risk.

PdfPages(keep_empty=True)#

A zero-page PDF is not valid, thus passing keep_empty=True to backend_pdf.PdfPages and backend_pgf.PdfPages, and the keep_empty attribute of these classes, is no longer allowed, and empty PDF files will not be created.

Furthermore, backend_pdf.PdfPages no longer immediately creates the target file upon instantiation, but only when the first figure is saved. To fully control file creation, directly pass an opened file object as argument (with open(path, "wb") as file, PdfPages(file) as pdf: ...).

backend_ps.psDefs#

The psDefs module-level variable in backend_ps has been removed with no replacement.

Automatic papersize selection in PostScript#

Setting rcParams["ps.papersize"] (default: 'letter') to 'auto' or passing papersize='auto' to Figure.savefig is no longer supported. Either pass an explicit paper type name, or omit this parameter to use the default from the rcParam.

RendererAgg.tostring_rgb and FigureCanvasAgg.tostring_rgb#

... have been remove with no direct replacement. Consider using buffer_rgba instead, which should cover most use cases.

TexManager.texcache#

... is considered private and has been removed. The location of the cache directory is clarified in the doc-string.

cbook API changes#

cbook.Stack has been removed with no replacement.

Grouper.clean() has been removed with no replacement. The Grouper class now cleans itself up automatically.

The np_load parameter of cbook.get_sample_data has been removed; get_sample_data now auto-loads numpy arrays. Use get_sample_data(..., asfileobj=False) instead to get the filename of the data file, which can then be passed to open, if desired.

Calling paths.get_path_collection_extents with empty offsets#

Calling get_path_collection_extents with an empty offsets parameter has an ambiguous interpretation and is no longer allowed.

bbox.anchored() with no explicit container#

Not passing a container argument to BboxBase.anchored is no longer supported.

INVALID_NON_AFFINE, INVALID_AFFINE, INVALID attributes of TransformNode#

These attributes have been removed.

axes_grid1 API changes#

anchored_artists.AnchoredEllipse has been removed. Instead, directly construct an AnchoredOffsetbox, an AuxTransformBox, and an Ellipse, as demonstrated in Anchored Artists.

The axes_divider.AxesLocator class has been removed. The new_locator method of divider instances now instead returns an opaque callable (which can still be passed to ax.set_axes_locator).

axes_divider.Divider.locate has been removed; use Divider.new_locator(...)(ax, renderer) instead.

axes_grid.CbarAxesBase.toggle_label has been removed. Instead, use standard methods for manipulating colorbar labels (Colorbar.set_label) and tick labels (Axes.tick_params).

inset_location.InsetPosition has been removed; use inset_axes instead.

axisartist API changes#

The axisartist.axes_grid and axisartist.axes_rgb modules, which provide wrappers combining the functionality of axes_grid1 and axisartist, have been removed; directly use e.g. AxesGrid(..., axes_class=axislines.Axes) instead.

Calling an axisartist Axes to mean axis has been removed; explicitly call the method instead.

floating_axes.GridHelperCurveLinear.get_data_boundary has been removed. Use grid_finder.extreme_finder(*[None] * 5) to get the extremes of the grid.

Development changes#

Documentation-specific custom Sphinx roles are now semi-public#

For third-party packages that derive types from Matplotlib, our use of custom roles may prevent Sphinx from building their docs. These custom Sphinx roles are now public solely for the purposes of use within projects that derive from Matplotlib types. See matplotlib.sphinxext.roles for details.

Increase to minimum supported versions of dependencies#

For Matplotlib 3.10, the minimum supported versions are being bumped:

Dependency

min in mpl3.9

min in mpl3.10

Python

3.9

3.10

This is consistent with our Dependency version policy and SPEC0

On this page