# Deprecations

## Extra parameters to Axes constructor

Parameters of the Axes constructor other than *fig* and *rect* will
become keyword-only in a future version.

## `pyplot.gca` and `Figure.gca` keyword arguments

Passing keyword arguments to [.pyplot.gca]{.title-ref} or
[.figure.Figure.gca]{.title-ref} will not be supported in a future
release.

## `Axis.cla`, `RadialAxis.cla`, `ThetaAxis.cla` and `Spine.cla`

These methods are deprecated in favor of the respective `clear()`
methods.

## Invalid hatch pattern characters are no longer ignored

When specifying hatching patterns, characters that are not recognized
will raise a deprecation warning. In the future, this will become a hard
error.

## `imread` reading from URLs

Passing a URL to [\~.pyplot.imread()]{.title-ref} is deprecated. Please
open the URL for reading and directly use the Pillow API
(`PIL.Image.open(urllib.request.urlopen(url))`, or
`PIL.Image.open(io.BytesIO(requests.get(url).content))`) instead.

## Subplot-related attributes and methods

Some `SubplotBase` methods and attributes have been deprecated and/or
moved to \`.SubplotSpec\`:

-   `get_geometry` (use `SubplotBase.get_subplotspec` instead),
-   `change_geometry` (use `SubplotBase.set_subplotspec` instead),
-   `is_first_row`, `is_last_row`, `is_first_col`, `is_last_col` (use
    the corresponding methods on the [.SubplotSpec]{.title-ref} instance
    instead),
-   `update_params` (now a no-op),
-   `figbox` (use `ax.get_subplotspec().get_geometry(ax.figure)` instead
    to recompute the geometry, or `ax.get_position()` to read its
    current value),
-   `numRows`, `numCols` (use the `nrows` and `ncols` attribute on the
    [.GridSpec]{.title-ref} instead).

Likewise, the `get_geometry`, `change_geometry`, `update_params`, and
`figbox` methods/attributes of [.SubplotDivider]{.title-ref} have been
deprecated, with similar replacements.

## `is_url` and `URL_REGEX`

\... are deprecated. (They were previously defined in the toplevel
`matplotlib`{.interpreted-text role="mod"} module.)

## `matplotlib.style.core` deprecations

`STYLE_FILE_PATTERN`, `load_base_library`, and `iter_user_libraries` are
deprecated.

## `dpi_cor` property of [.FancyArrowPatch]{.title-ref}

This parameter is considered internal and deprecated.

## Passing `boxstyle="custom", bbox_transmuter=...` to `FancyBboxPatch`

In order to use a custom boxstyle, directly pass it as the *boxstyle*
argument to [.FancyBboxPatch]{.title-ref}. This was previously already
possible, and is consistent with custom arrow styles and connection
styles.

## BoxStyles are now called without passing the *mutation_aspect* parameter

Mutation aspect is now handled by the artist itself. Hence the
*mutation_aspect* parameter of `BoxStyle._Base.__call__` is deprecated,
and custom boxstyles should be implemented to not require this parameter
(it can be left as a parameter defaulting to 1 for back-compatibility).

## `ContourLabeler.get_label_coords` is deprecated

It is considered an internal helper.

## Line2D and Patch no longer duplicate `validJoin` and `validCap`

Validation of joinstyle and capstyles is now centralized in `rcsetup`.

## Setting a Line2D\'s pickradius via `set_picker` is undeprecated

This cancels the deprecation introduced in Matplotlib 3.3.0.

## `MarkerStyle` is considered immutable

`MarkerStyle.set_fillstyle()` and `MarkerStyle.set_marker()` are
deprecated. Create a new `MarkerStyle` with the respective parameters
instead.

## `MovieWriter.cleanup` is deprecated

Cleanup logic is now fully implemented in
[.MovieWriter.finish]{.title-ref}. Third-party movie writers should
likewise move the relevant cleanup logic there, as overridden `cleanup`s
will no longer be called in the future.

## *minimumdescent* parameter/property of `TextArea`

[.offsetbox.TextArea]{.title-ref} has behaved as if *minimumdescent* was
always True (regardless of the value to which it was set) since
Matplotlib 1.3, so the parameter/property is deprecated.

## `colorbar` now warns when the mappable\'s Axes is different from the current Axes

Currently, [.Figure.colorbar]{.title-ref} and
[.pyplot.colorbar]{.title-ref} steal space by default from the current
Axes to place the colorbar. In a future version, they will steal space
from the mappable\'s Axes instead. In preparation for this change,
[.Figure.colorbar]{.title-ref} and [.pyplot.colorbar]{.title-ref} now
emits a warning when the current Axes is not the same as the mappable\'s
Axes.

## Colorbar docstrings

The following globals in `matplotlib.colorbar`{.interpreted-text
role="mod"} are deprecated: `colorbar_doc`, `colormap_kw_doc`,
`make_axes_kw_doc`.

## `ColorbarPatch` and `colorbar_factory` are deprecated

All the relevant functionality has been moved to the
[\~matplotlib.colorbar.Colorbar]{.title-ref} class.

## Backend deprecations

-   `FigureCanvasBase.get_window_title` and
    `FigureCanvasBase.set_window_title` are deprecated. Use the
    corresponding methods on the FigureManager if using pyplot, or
    GUI-specific methods if embedding.
-   The *resize_callback* parameter to `FigureCanvasTk` was never used
    internally and is deprecated. Tk-level custom event handlers for
    resize events can be added to a `FigureCanvasTk` using e.g.
    `get_tk_widget().bind('<Configure>', ..., True)`.
-   The `key_press` and `button_press` methods of
    [.FigureManagerBase]{.title-ref}, which incorrectly did nothing when
    using `toolmanager`, are deprecated in favor of directly passing the
    event to the [.CallbackRegistry]{.title-ref} via
    `self.canvas.callbacks.process(event.name, event)`.
-   `RendererAgg.get_content_extents` and
    `RendererAgg.tostring_rgba_minimized` are deprecated.
-   `backend_pgf.TmpDirCleaner` is deprecated, with no replacement.
-   `GraphicsContextPS` is deprecated. The PostScript backend now uses
    [.GraphicsContextBase]{.title-ref}.

## wx backend cleanups

The *origin* parameter to `_FigureCanvasWxBase.gui_repaint` is
deprecated with no replacement; `gui_repaint` now automatically detects
the case where it is used with the wx renderer.

The `NavigationToolbar2Wx.get_canvas` method is deprecated; directly
instantiate a canvas (`FigureCanvasWxAgg(frame, -1, figure)`) if needed.

## Unused positional parameters to `print_<fmt>` methods are deprecated

None of the `print_<fmt>` methods implemented by canvas subclasses used
positional arguments other that the first (the output filename or
file-like), so these extra parameters are deprecated.

## The *dpi* parameter of `FigureCanvas.print_foo` printers is deprecated

The [\~.Figure.savefig]{.title-ref} machinery already took care of
setting the figure DPI to the desired value, so `print_foo` can directly
read it from there. Not passing *dpi* to `print_foo` allows clearer
detection of unused parameters passed to
[\~.Figure.savefig]{.title-ref}.

## Passing [bytes]{.title-ref} to `FT2Font.set_text`

\... is deprecated, pass [str]{.title-ref} instead.

## `ps.useafm` deprecated for mathtext

Outputting mathtext using only standard PostScript fonts has likely been
broken for a while (issue
[#18722](https://github.com/matplotlib/matplotlib/issues/18722)). In
Matplotlib 3.5, the setting `ps.useafm`{.interpreted-text role="rc"}
will have no effect on mathtext.

## `MathTextParser("bitmap")` is deprecated

The associated APIs `MathtextBackendBitmap`, `MathTextParser.to_mask`,
`MathTextParser.to_rgba`, `MathTextParser.to_png`, and
`MathTextParser.get_depth` are likewise deprecated.

To convert a text string to an image, either directly draw the text to
an empty [.Figure]{.title-ref} and save the figure using a tight bbox,
as demonstrated in
`/gallery/text_labels_and_annotations/mathtext_asarray`{.interpreted-text
role="doc"}, or use [.mathtext.math_to_image]{.title-ref}.

When using [.math_to_image]{.title-ref}, text color can be set with
e.g.:

    with plt.rc_context({"text.color": "tab:blue"}):
        mathtext.math_to_image(text, filename)

and an RGBA array can be obtained with e.g.:

    from io import BytesIO
    buf = BytesIO()
    mathtext.math_to_image(text, buf, format="png")
    buf.seek(0)
    rgba = plt.imread(buf)

## Deprecation of mathtext internals

The following API elements previously exposed by the
`.mathtext`{.interpreted-text role="mod"} module are considered to be
implementation details and public access to them is deprecated:

-   `Fonts` and all its subclasses,
-   `FontConstantsBase` and all its subclasses,
-   `Node` and all its subclasses,
-   `Ship`, `ship`,
-   `Error`,
-   `Parser`,
-   `SHRINK_FACTOR`, `GROW_FACTOR`,
-   `NUM_SIZE_LEVELS`,
-   `latex_to_bakoma`, `latex_to_cmex`, `latex_to_standard`,
-   `stix_virtual_fonts`,
-   `tex2uni`.

## Deprecation of various mathtext helpers

The `MathtextBackendPdf`, `MathtextBackendPs`, `MathtextBackendSvg`, and
`MathtextBackendCairo` classes from the `.mathtext`{.interpreted-text
role="mod"} module, as well as the corresponding `.mathtext_parser`
attributes on `RendererPdf`, `RendererPS`, `RendererSVG`, and
`RendererCairo`, are deprecated. The `MathtextBackendPath` class can be
used to obtain a list of glyphs and rectangles in a mathtext expression,
and renderer-specific logic should be directly implemented in the
renderer.

`StandardPsFonts.pswriter` is unused and deprecated.

## Widget class internals

Several [.widgets.Widget]{.title-ref} class internals have been
privatized and deprecated:

-   `AxesWidget.cids`
-   `Button.cnt` and `Button.observers`
-   `CheckButtons.cnt` and `CheckButtons.observers`
-   `RadioButtons.cnt` and `RadioButtons.observers`
-   `Slider.cnt` and `Slider.observers`
-   `TextBox.cnt`, `TextBox.change_observers` and
    `TextBox.submit_observers`

## 3D properties on renderers

The properties of the 3D Axes that were placed on the Renderer during
draw are now deprecated:

-   `renderer.M`
-   `renderer.eye`
-   `renderer.vvec`
-   `renderer.get_axis_position`

These attributes are all available via [.Axes3D]{.title-ref}, which can
be accessed via `self.axes` on all [.Artist]{.title-ref}s.

## *renderer* argument of `do_3d_projection` method for `Collection3D`/`Patch3D`

The *renderer* argument for the `do_3d_projection` method on
`Collection3D` and `Patch3D` is no longer necessary, and passing it
during draw is deprecated.

## *project* argument of `draw` method for `Line3DCollection`

The *project* argument for the `draw` method on `Line3DCollection` is
deprecated. Call [.Line3DCollection.do_3d_projection]{.title-ref}
explicitly instead.

## Extra positional parameters to `plot_surface` and `plot_wireframe`

Positional parameters to [\~.axes3d.Axes3D.plot_surface]{.title-ref} and
[\~.axes3d.Axes3D.plot_wireframe]{.title-ref} other than `X`, `Y`, and
`Z` are deprecated. Pass additional artist properties as keyword
arguments instead.

## `ParasiteAxesAuxTransBase` class

The functionality of that mixin class has been moved to the base
`ParasiteAxesBase` class. Thus, `ParasiteAxesAuxTransBase`,
`ParasiteAxesAuxTrans`, and `parasite_axes_auxtrans_class_factory` are
deprecated.

In general, it is suggested to use `HostAxes.get_aux_axes` to create
parasite Axes, as this saves the need of manually appending the parasite
to `host.parasites` and makes sure that their `remove()` method works
properly.

## `AxisArtist.ZORDER` attribute

Use `AxisArtist.zorder` instead.

## `GridHelperBase` invalidation

The `GridHelperBase.invalidate`, `GridHelperBase.valid`, and
`axislines.Axes.invalidate_grid_helper` methods are considered internal
and deprecated.

## `sphinext.plot_directive.align`

\... is deprecated. Use
`docutils.parsers.rst.directives.images.Image.align` instead.

## Deprecation-related functionality is considered internal

The module `matplotlib.cbook.deprecation` is considered internal and
will be removed from the public API. This also holds for
deprecation-related re-imports in `matplotlib.cbook`, i.e.
`matplotlib.cbook.deprecated()`, `matplotlib.cbook.warn_deprecated()`,
`matplotlib.cbook.MatplotlibDeprecationWarning` and
`matplotlib.cbook.mplDeprecation`.

If needed, external users may import `MatplotlibDeprecationWarning`
directly from the `matplotlib` namespace. `mplDeprecation` is only an
alias of `MatplotlibDeprecationWarning` and should not be used anymore.