# Behaviour changes

## `plt.get_cmap` and `matplotlib.cm.get_cmap` return a copy

Formerly, [\~.pyplot.get_cmap]{.title-ref} and `matplotlib.cm.get_cmap`
returned a global version of a [.Colormap]{.title-ref}. This was prone
to errors as modification of the colormap would propagate from one
location to another without warning. Now, a new copy of the colormap is
returned.

## Large `imshow` images are now downsampled

When showing an image using [\~matplotlib.axes.Axes.imshow]{.title-ref}
that has more than $2^{24}$ columns or $2^{23}$ rows, the image will now
be downsampled to below this resolution before being resampled for
display by the AGG renderer. Previously such a large image would be
shown incorrectly. To prevent this downsampling and the warning it
raises, manually downsample your data before handing it to
[\~matplotlib.axes.Axes.imshow]{.title-ref}.

## Default date limits changed to 1970-01-01 -- 1970-01-02

Previously the default limits for an empty axis set up for dates
([.Axis.axis_date]{.title-ref}) was 2000-01-01 to 2010-01-01. This has
been changed to 1970-01-01 to 1970-01-02. With the default epoch, this
makes the numeric limit for date axes the same as for other axes
(0.0-1.0), and users are less likely to set a locator with far too many
ticks.

## *markerfmt* argument to `stem`

The behavior of the *markerfmt* parameter of [\~.Axes.stem]{.title-ref}
has changed:

-   If *markerfmt* does not contain a color, the color is taken from
    *linefmt*.
-   If *markerfmt* does not contain a marker, the default is \'o\'.

Before, *markerfmt* was passed unmodified to `plot(..., fmt)`, which had
a number of unintended side-effects; e.g. only giving a color switched
to a solid line without markers.

For a simple call `stem(x, y)` without parameters, the new rules still
reproduce the old behavior.

## `get_ticklabels` now always populates labels

Previously [.Axis.get_ticklabels]{.title-ref} (and
[.Axes.get_xticklabels]{.title-ref},
[.Axes.get_yticklabels]{.title-ref}) would only return empty strings
unless a draw had already been performed. Now the ticks and their labels
are updated when the labels are requested.

## Warning when scatter plot color settings discarded

When making an animation of a scatter plot, if you don\'t set *c* (the
color value parameter) when initializing the artist, the color settings
are ignored. [.Axes.scatter]{.title-ref} now raises a warning if
color-related settings are changed without setting *c*.

## 3D `contourf` polygons placed between levels

The polygons used in a 3D [\~.Axes3D.contourf]{.title-ref} plot are now
placed halfway between the contour levels, as each polygon represents
the location of values that lie between two levels.

## Axes title now avoids y-axis offset

Previously, Axes titles could overlap the y-axis offset text, which is
often in the upper left corner of the axes. Now titles are moved above
the offset text if overlapping when automatic title positioning is in
effect (i.e. if *y* in [.Axes.set_title]{.title-ref} is *None* and
`axes.titley`{.interpreted-text role="rc"} is also *None*).

## Dotted operators gain extra space in mathtext

In mathtext, `\doteq \doteqdot \dotminus \dotplus \dots` are now
surrounded by extra space because they are correctly treated as
relational or binary operators.

## *math* parameter of `mathtext.get_unicode_index` defaults to False

In math mode, ASCII hyphens (U+002D) are now replaced by Unicode minus
signs (U+2212) at the parsing stage.

## `ArtistList` proxies copy contents on iteration

When iterating over the contents of the dynamically generated proxy
lists for the Artist-type accessors (see
`Behavioural API Changes 3.5 - Axes
children combined`{.interpreted-text role="ref"}), a copy of the
contents is made. This ensure that artists can safely be added or
removed from the Axes while iterating over their children.

This is a departure from the expected behavior of mutable iterable data
types in Python --- iterating over a list while mutating it has
surprising consequences and dictionaries will error if they change size
during iteration. Because all of the accessors are filtered views of the
same underlying list, it is possible for seemingly unrelated changes,
such as removing a Line, to affect the iteration over any of the other
accessors. In this case, we have opted to make a copy of the relevant
children before yielding them to the user.

This change is also consistent with our plan to make these accessors
immutable in Matplotlib 3.7.

## `AxesImage` string representation

The string representation of [.AxesImage]{.title-ref} changes from
stating the position in the figure `"AxesImage(80,52.8;496x369.6)"` to
giving the number of pixels `"AxesImage(size=(300, 200))"`.

## Improved autoscaling for Bézier curves

Bézier curves are now autoscaled to their extents - previously they were
autoscaled to their ends and control points, which in some cases led to
unnecessarily large limits.

## `QuadMesh` mouseover defaults to False

New in 3.5, [.QuadMesh.get_cursor_data]{.title-ref} allows display of
data values under the cursor. However, this can be very slow for large
meshes, so mouseover now defaults to *False*.

## Changed pgf backend document class

The pgf backend now uses the `article` document class as basis for
compilation.

## `MathtextBackendAgg.get_results` no longer returns `used_characters`

The last item (`used_characters`) in the tuple returned by
`MathtextBackendAgg.get_results` has been removed. In order to unpack
this tuple in a backward and forward-compatible way, use e.g.
`ox, oy, width, height, descent, image, *_ = parse(...)`, which will
ignore `used_characters` if it was present.

## `Type1Font` objects include more properties

The `matplotlib._type1font.Type1Font.prop` dictionary now includes more
keys, such as `CharStrings` and `Subrs`. The value of the `Encoding` key
is now a dictionary mapping codes to glyph names. The
`matplotlib._type1font.Type1Font.transform` method now correctly removes
`UniqueID` properties from the font.

## `rcParams.copy()` returns `RcParams` rather than `dict`

Returning an [.RcParams]{.title-ref} instance from
[.RcParams.copy]{.title-ref} makes the copy still validate inputs, and
additionally avoids emitting deprecation warnings when using a
previously copied instance to update the global instance (even if some
entries are deprecated).

## `rc_context` no longer resets the value of `'backend'`

[matplotlib.rc_context]{.title-ref} incorrectly reset the value of
`backend`{.interpreted-text role="rc"} if backend resolution was
triggered in the context. This affected only the value. The actual
backend was not changed. Now, [matplotlib.rc_context]{.title-ref} does
not reset `backend`{.interpreted-text role="rc"} anymore.

## Default `rcParams["animation.convert_args"]` changed

It now defaults to `["-layers", "OptimizePlus"]` to try to generate
smaller GIFs. Set it back to an empty list to recover the previous
behavior.

## Style file encoding now specified to be UTF-8

It has been impossible to import Matplotlib with a non UTF-8 compatible
locale encoding because we read the style library at import time. This
change is formalizing and documenting the status quo so there is no
deprecation period.

## MacOSX backend uses sRGB instead of GenericRGB color space

MacOSX backend now display sRGB tagged image instead of GenericRGB which
is an older (now deprecated) Apple color space. This is the source color
space used by ColorSync to convert to the current display profile.

## Renderer optional for `get_tightbbox` and `get_window_extent`

The [.Artist.get_tightbbox]{.title-ref} and
[.Artist.get_window_extent]{.title-ref} methods no longer require the
*renderer* keyword argument, saving users from having to query it from
`fig.canvas.get_renderer`. If the *renderer* keyword argument is not
supplied, these methods first check if there is a cached renderer from a
previous draw and use that. If there is no cached renderer, then the
methods will use `fig.canvas.get_renderer()` as a fallback.

## `FigureFrameWx` constructor, subclasses, and `get_canvas`

The `FigureCanvasWx` constructor gained a *canvas_class* keyword-only
parameter which specifies the canvas class that should be used. This
parameter will become required in the future. The `get_canvas` method,
which was previously used to customize canvas creation, is deprecated.
The `FigureFrameWxAgg` and `FigureFrameWxCairo` subclasses, which
overrode `get_canvas`, are deprecated.

## `FigureFrameWx.sizer`

\... has been removed. The frame layout is no longer based on a sizer,
as the canvas is now the sole child widget; the toolbar is now a regular
toolbar added using `SetToolBar`.

## Incompatible layout engines raise

You cannot switch between `tight_layout` and `constrained_layout` if a
colorbar has already been added to a figure. Invoking the incompatible
layout engine used to warn, but now raises with a
[RuntimeError]{.title-ref}.

## `CallbackRegistry` raises on unknown signals

When Matplotlib instantiates a [.CallbackRegistry]{.title-ref}, it now
limits callbacks to the signals that the registry knows about. In
practice, this means that calling
[\~.FigureCanvasBase.mpl_connect]{.title-ref} with an invalid signal
name now raises a [ValueError]{.title-ref}.

## Changed exception type for incorrect SVG date metadata

Providing date metadata with incorrect type to the SVG backend earlier
resulted in a [ValueError]{.title-ref}. Now, a [TypeError]{.title-ref}
is raised instead.

## Specified exception types in `Grid`

In a few cases an [Exception]{.title-ref} was thrown when an incorrect
argument value was set in the
[mpl_toolkits.axes_grid1.axes_grid.Grid]{.title-ref} (=
`mpl_toolkits.axisartist.axes_grid.Grid`) constructor. These are
replaced as follows:

-   Providing an incorrect value for *ngrids* now raises a
    [ValueError]{.title-ref}
-   Providing an incorrect type for *rect* now raises a
    [TypeError]{.title-ref}