# Deprecations

## Calling `paths.get_path_collection_extents` with empty *offsets*

Calling [\~.get_path_collection_extents]{.title-ref} with an empty
*offsets* parameter has an ambiguous interpretation and is therefore
deprecated. When the deprecation period expires, this will produce an
error.

## `axes_grid1.axes_divider` API changes

The `AxesLocator` class is deprecated. The `new_locator` method of
divider instances now instead returns an opaque callable (which can
still be passed to `ax.set_axes_locator`).

`Divider.locate` is deprecated; use
`Divider.new_locator(...)(ax, renderer)` instead.

## `bbox.anchored()` with no explicit container

Not passing a *container* argument to [.BboxBase.anchored]{.title-ref}
is now deprecated.

## Functions in `mpl_toolkits.mplot3d.proj3d`

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

The following functions are either unused (so no longer required in
Matplotlib) or considered private. If you rely on them, please make a
copy of the code, including all functions that starts with a `_`
(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.

## The object returned by `pcolor()` has changed to a `PolyQuadMesh` class

The old object was a [.PolyCollection]{.title-ref} with flattened
vertices and array data. The new [.PolyQuadMesh]{.title-ref} class
subclasses [.PolyCollection]{.title-ref}, but adds in better 2D
coordinate and array handling in alignment with [.QuadMesh]{.title-ref}.
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 is now deprecated and the full
2D array of values (including the mask) should be passed to
[.PolyQuadMesh.set_array]{.title-ref}.

## `LocationEvent.lastevent`

\... is deprecated with no replacement.

## `allsegs`, `allkinds`, `tcolors` and `tlinewidths` attributes of [.ContourSet]{.title-ref}

These attributes are deprecated; if required, directly retrieve the
vertices and codes of the Path objects from `ContourSet.get_paths()` and
the colors and the linewidths via `ContourSet.get_facecolor()`,
`ContourSet.get_edgecolor()` and `ContourSet.get_linewidths()`.

## `ContourSet.collections`

\... is deprecated. [.ContourSet]{.title-ref} is now implemented as a
single [.Collection]{.title-ref} of paths, each path corresponding to a
contour level, possibly including multiple unconnected components.

During the deprecation period, accessing `ContourSet.collections` will
revert the current ContourSet instance to the old object layout, with a
separate [.PathCollection]{.title-ref} per contour level.

## `INVALID_NON_AFFINE`, `INVALID_AFFINE`, `INVALID` attributes of `TransformNode`

These attributes are deprecated.

## `Grouper.clean()`

with no replacement. The Grouper class now cleans itself up
automatically.

## `GridHelperCurveLinear.get_data_boundary`

\... is deprecated. Use `grid_finder.extreme_finder(*[None] * 5)` to get
the extremes of the grid.

## *np_load* parameter of `cbook.get_sample_data`

This parameter is deprecated; [.get_sample_data]{.title-ref} 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]{.title-ref}, if desired.

## `RendererAgg.tostring_rgb` and `FigureCanvasAgg.tostring_rgb`

\... are deprecated with no direct replacement. Consider using
`buffer_rgba` instead, which should cover most use cases.

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

\... consistently with [.Artist.contains]{.title-ref}.

## Accessing `event.guiEvent` after event handlers return

\... is deprecated: for some GUI toolkits, it is unsafe to do so. In the
future, `event.guiEvent` will be set to None once the event handlers
return; you may separately stash the object at your own risk.

## Widgets

The *visible* attribute getter of Selector widgets has been deprecated;
use `get_visible`

## 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]{.title-ref}.

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]{.title-ref}.

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`.

## *numdecs* parameter and attribute of `LogLocator`

\... are deprecated without replacement, because they have no effect.

## `NavigationToolbar2QT.message` is deprecated

\... with no replacement.

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

\... are deprecated as they are unused. If you rely on these, please let
us know.

## `backend_ps.psDefs`

The `psDefs` module-level variable in `backend_ps` is deprecated with no
replacement.

## Callable axisartist Axes

Calling an axisartist Axes to mean
[\~matplotlib.pyplot.axis]{.title-ref} is deprecated; explicitly call
the method instead.

## `AnchoredEllipse` is deprecated

Instead, directly construct an [.AnchoredOffsetbox]{.title-ref}, an
[.AuxTransformBox]{.title-ref}, and an [\~.patches.Ellipse]{.title-ref},
as demonstrated in `/gallery/misc/anchored_artists`{.interpreted-text
role="doc"}.

## Automatic papersize selection in PostScript

Setting `ps.papersize`{.interpreted-text role="rc"} to `'auto'` or
passing `papersize='auto'` to [.Figure.savefig]{.title-ref} is
deprecated. Either pass an explicit paper type name, or omit this
parameter to use the default from the rcParam.

## `Tick.set_label1` and `Tick.set_label2`

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

## Passing extra positional arguments to `Figure.add_axes`

Positional arguments passed to [.Figure.add_axes]{.title-ref} other than
a rect or an existing `Axes` are currently ignored, and doing so is now
deprecated.

## `CbarAxesBase.toggle_label`

\... is deprecated. Instead, use standard methods for manipulating
colorbar labels ([.Colorbar.set_label]{.title-ref}) and tick labels
([.Axes.tick_params]{.title-ref}).

## `TexManager.texcache`

\... is considered private and deprecated. The location of the cache
directory is clarified in the doc-string.

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

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

## `FigureCanvasBase.switch_backends`

\... is deprecated with no replacement.

## `cbook.Stack` is deprecated

\... with no replacement.

## `inset_location.InsetPosition` is deprecated

Use [\~.Axes.inset_axes]{.title-ref} instead.

## `axisartist.axes_grid` and `axisartist.axes_rgb`

These modules, which provide wrappers combining the functionality of
[.axes_grid1]{.title-ref} and [.axisartist]{.title-ref}, are deprecated;
directly use e.g. `AxesGrid(..., axes_class=axislines.Axes)` instead.

## `ContourSet.antialiased`

\... is deprecated; use [\~.Collection.get_antialiased]{.title-ref} or
[\~.Collection.set_antialiased]{.title-ref} instead. Note that
[\~.Collection.get_antialiased]{.title-ref} returns an array.

## 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 will become an error in the future.

## `PdfPages(keep_empty=True)`

A zero-page pdf is not valid, thus passing `keep_empty=True` to
[.backend_pdf.PdfPages]{.title-ref} and
[.backend_pgf.PdfPages]{.title-ref}, and the `keep_empty` attribute of
these classes, are deprecated. Currently, these classes default to
keeping empty outputs, but that behavior is deprecated too. Explicitly
passing `keep_empty=False` remains supported for now to help transition
to the new behavior.

Furthermore, [.backend_pdf.PdfPages]{.title-ref} 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: ...`).

## Auto-closing of figures when switching backend

\... is deprecated. Explicitly call `plt.close("all")` if necessary. In
the future, allowable backend switches (i.e. those that do not swap a
GUI event loop with another one) will not close existing figures.

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

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