Deprecations

The ``Figure`` parameters *tight_layout* and *constrained_layout* are
triggering competing layout mechanisms and thus should not be used together.

To make the API clearer, we've merged them under the new parameter *layout*
with values 'constrained' (equal to ``constrained_layout=True``), 'tight'
(equal to ``tight_layout=True``). If given, *layout* takes precedence.

The use of *tight_layout* and *constrained_layout* is discouraged in favor of
*layout*. However, these parameters will stay available for backward
compatibility.

Modification of ``Axes`` children sublists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See :ref:`Behavioural API Changes 3.5 - Axes children combined` for more
information; modification of the following sublists is deprecated:

* ``Axes.artists``
* ``Axes.collections``
* ``Axes.images``
* ``Axes.lines``
* ``Axes.patches``
* ``Axes.tables``
* ``Axes.texts``

To remove an Artist, use its `.Artist.remove` method. To add an Artist, use the
corresponding ``Axes.add_*`` method.

Passing incorrect types to ``Axes.add_*`` methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following ``Axes.add_*`` methods will now warn if passed an unexpected
type. See their documentation for the types they expect.

- `.Axes.add_collection`
- `.Axes.add_image`
- `.Axes.add_line`
- `.Axes.add_patch`
- `.Axes.add_table`

Discouraged: ``plot_date``
~~~~~~~~~~~~~~~~~~~~~~~~~~

The use of `~.Axes.plot_date` is discouraged. This method exists for historic
reasons and may be deprecated in the future.

- ``datetime``-like data should directly be plotted using `~.Axes.plot`.
- If you need to plot plain numeric data as :ref:`date-format` or
  need to set a timezone, call ``ax.xaxis.axis_date`` / ``ax.yaxis.axis_date``
  before `~.Axes.plot`. See `.Axis.axis_date`.

``epoch2num`` and ``num2epoch`` are deprecated
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These methods convert from unix timestamps to matplotlib floats, but are not
used internally to matplotlib, and should not be needed by end users. To
convert a unix timestamp to datetime, simply use
`datetime.datetime.utcfromtimestamp`, or to use NumPy `~numpy.datetime64`
``dt = np.datetime64(e*1e6, 'us')``.

Auto-removal of grids by `~.Axes.pcolor` and `~.Axes.pcolormesh`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`~.Axes.pcolor` and `~.Axes.pcolormesh` currently remove any visible axes major
grid. This behavior is deprecated; please explicitly call ``ax.grid(False)`` to
remove the grid.

The first parameter of ``Axes.grid`` and ``Axis.grid`` has been renamed to *visible*

The API for Selector widgets has been unified to use:

- *props* for the properties of the Artist representing the selection.
- *handle_props* for the Artists representing handles for modifying the
  selection.
- *grab_range* for the maximal tolerance to grab a handle with the mouse.

Additionally, several internal parameters and attribute have been deprecated
with the intention of keeping them private.

RectangleSelector and EllipseSelector
.....................................

The *drawtype* keyword argument to `~matplotlib.widgets.RectangleSelector` is
deprecated. In the future the only behaviour will be the default behaviour of
``drawtype='box'``.

Support for ``drawtype=line`` will be removed altogether as it is not clear
which points are within and outside a selector that is just a line. As a
result, the *lineprops* keyword argument to
`~matplotlib.widgets.RectangleSelector` is also deprecated.

To retain the behaviour of ``drawtype='none'``, use ``rectprops={'visible':
False}`` to make the drawn `~matplotlib.patches.Rectangle` invisible.

Cleaned up attributes and arguments are:

- The ``active_handle`` attribute has been privatized and deprecated.
- The ``drawtype`` attribute has been privatized and deprecated.
- The ``eventpress`` attribute has been privatized and deprecated.
- The ``eventrelease`` attribute has been privatized and deprecated.
- The ``interactive`` attribute has been privatized and deprecated.
- The *marker_props* argument is deprecated, use *handle_props* instead.
- The *maxdist* argument is deprecated, use *grab_range* instead.
- The *rectprops* argument is deprecated, use *props* instead.
- The ``rectprops`` attribute has been privatized and deprecated.
- The ``state`` attribute has been privatized and deprecated.
- The ``to_draw`` attribute has been privatized and deprecated.

PolygonSelector
...............

- The *line* attribute is deprecated. If you want to change the selector artist
  properties, use the ``set_props`` or ``set_handle_props`` methods.
- The *lineprops* argument is deprecated, use *props* instead.
- The *markerprops* argument is deprecated, use *handle_props* instead.
- The *maxdist* argument and attribute is deprecated, use *grab_range* instead.
- The *vertex_select_radius* argument and attribute is deprecated, use
  *grab_range* instead.

SpanSelector
............

- The ``active_handle`` attribute has been privatized and deprecated.
- The ``eventpress`` attribute has been privatized and deprecated.
- The ``eventrelease`` attribute has been privatized and deprecated.
- The *maxdist* argument and attribute is deprecated, use *grab_range* instead.
- The ``pressv`` attribute has been privatized and deprecated.
- The ``prev`` attribute has been privatized and deprecated.
- The ``rect`` attribute has been privatized and deprecated.
- The *rectprops* argument is deprecated, use *props* instead.
- The ``rectprops`` attribute has been privatized and deprecated.
- The *span_stays* argument is deprecated, use the *interactive* argument
  instead.
- The ``span_stays`` attribute has been privatized and deprecated.
- The ``state`` attribute has been privatized and deprecated.

LassoSelector
.............

- The *lineprops* argument is deprecated, use *props* instead.
- The ``onpress`` and ``onrelease`` methods are deprecated. They are straight
  aliases for ``press`` and ``release``.

``ConversionInterface.convert`` no longer needs to accept unitless values

The ``set_view_interval``, ``set_data_interval`` and ``set_bounds`` methods of
`.Locator`\s and `.Formatter`\s (and their common base class, TickHelper) are
deprecated. Directly manipulate the view and data intervals on the underlying
axis instead.

Unused positional parameters to ``print_<fmt>`` methods

The `.QuadMesh` signature ::

    def __init__(meshWidth, meshHeight, coordinates,
                 antialiased=True, shading='flat', **kwargs)

is deprecated and replaced by the new signature ::

    def __init__(coordinates, *, antialiased=True, shading='flat', **kwargs)

In particular:

- The *coordinates* argument must now be a (M, N, 2) array-like. Previously,
  the grid shape was separately specified as (*meshHeight* + 1, *meshWidth* +
  1) and *coordinates* could be an array-like of any shape with M * N * 2
  elements.
- All parameters except *coordinates* are keyword-only now.

rcParams will no longer cast inputs to str

Previously, scales could be set case-insensitively (e.g.,
``set_xscale("LoG")``). This is deprecated; all builtin scales use lowercase
names.

Interactive cursor details

- ``is_url`` and ``URL_REGEX`` are deprecated. (They were previously defined in
  the toplevel :mod:`matplotlib` module.)
- The ``ArrowStyle.beginarrow`` and ``ArrowStyle.endarrow`` attributes are
  deprecated; use the ``arrow`` attribute to define the desired heads and tails
  of the arrow.
- ``backend_pgf.LatexManager.str_cache`` is deprecated.
- ``backends.qt_compat.ETS`` and ``backends.qt_compat.QT_RC_MAJOR_VERSION`` are
  deprecated, with no replacement.
- The ``blocking_input`` module has been deprecated. Instead, use
  ``canvas.start_event_loop()`` and ``canvas.stop_event_loop()`` while
  connecting event callbacks as needed.
- ``cbook.report_memory`` is deprecated; use ``psutil.virtual_memory`` instead.
- ``cm.LUTSIZE`` is deprecated. Use :rc:`image.lut` instead. This value only
  affects colormap quantization levels for default colormaps generated at
  module import time.
- ``Collection.__init__`` previously ignored *transOffset* without *offsets* also
  being specified. In the future, *transOffset* will begin having an effect
  regardless of *offsets*. In the meantime, if you wish to set *transOffset*,
  call `.Collection.set_offset_transform` explicitly.
- ``Colorbar.patch`` is deprecated; this attribute is not correctly updated
  anymore.
- ``ContourLabeler.get_label_width`` is deprecated.
- ``dviread.PsfontsMap`` now raises LookupError instead of KeyError for missing
  fonts.
- ``Dvi.baseline`` is deprecated (with no replacement).
- The *format* parameter of ``dviread.find_tex_file`` is deprecated (with no
  replacement).
- ``FancyArrowPatch.get_path_in_displaycoord`` and
  ``ConnectionPatch.get_path_in_displaycoord`` are deprecated. The path in
  display coordinates can still be obtained, as for other patches, using
  ``patch.get_transform().transform_path(patch.get_path())``.
- The ``font_manager.win32InstalledFonts`` and
  ``font_manager.get_fontconfig_fonts`` helper functions have been deprecated.
- All parameters of ``imshow`` starting from *aspect* will become keyword-only.
- ``QuadMesh.convert_mesh_to_paths`` and ``QuadMesh.convert_mesh_to_triangles``
  are deprecated. ``QuadMesh.get_paths()`` can be used as an alternative for
  the former; there is no replacement for the latter.
- ``ScalarMappable.callbacksSM`` is deprecated. Use
  ``ScalarMappable.callbacks`` instead.
- ``streamplot.get_integrator`` is deprecated.
- ``style.core.STYLE_FILE_PATTERN``, ``style.core.load_base_library``, and
  ``style.core.iter_user_libraries`` are deprecated.
- ``SubplotParams.validate`` is deprecated. Use `.SubplotParams.update` to
  change `.SubplotParams` while always keeping it in a valid state.
- The ``grey_arrayd``, ``font_family``, ``font_families``, and ``font_info``
  attributes of `.TexManager` are deprecated.
- ``Text.get_prop_tup`` is deprecated with no replacements (because the `.Text`
  class cannot know whether a backend needs to update cache e.g. when the
  text's color changes).
- ``Tick.apply_tickdir`` didn't actually update the tick markers on the
  existing Line2D objects used to draw the ticks and is deprecated; use
  `.Axis.set_tick_params` instead.
- ``tight_layout.auto_adjust_subplotpars`` is deprecated.

- The ``grid_info`` attribute of ``axisartist`` classes has been deprecated.
- ``axisartist.clip_path`` is deprecated with no replacement.
- ``axes_grid1.axes_grid.CbarAxes`` and ``axes_grid1.axisartist.CbarAxes`` are
  deprecated (they are now dynamically generated based on the owning axes
  class).
- The ``axes_grid1.Divider.get_vsize_hsize`` and
  ``axes_grid1.Grid.get_vsize_hsize`` methods are deprecated. Copy their
  implementations if needed.
- ``AxesDivider.append_axes(..., add_to_figure=False)`` is deprecated. Use
  ``ax.remove()`` to remove the Axes from the figure if needed.
- ``FixedAxisArtistHelper.change_tick_coord`` is deprecated with no
  replacement.
- ``floating_axes.GridHelperCurveLinear.get_boundary`` is deprecated, with no
  replacement.
- ``ParasiteAxesBase.get_images_artists`` has been deprecated.

- The "units finalize" signal (previously emitted by Axis instances) is
  deprecated. Connect to "units" instead.
- Passing formatting parameters positionally to ``stem()`` is deprecated

``plot_directive`` deprecations

``matplotlib.test()`` is deprecated
...................................

Run tests using ``pytest`` from the commandline instead. The variable
``matplotlib.default_test_modules`` is only used for ``matplotlib.test()`` and
is thus deprecated as well.

To test an installed copy, be sure to specify both ``matplotlib`` and
``mpl_toolkits`` with ``--pyargs``::

    pytest --pyargs matplotlib.tests mpl_toolkits.tests

See :ref:`testing` for more details.

Unused pytest fixtures and markers
..................................

The fixture ``matplotlib.testing.conftest.mpl_image_comparison_parameters`` is
not used internally by Matplotlib. If you use this please copy it into your
code base.

The ``@pytest.mark.style`` marker is deprecated; use ``@mpl.style.context``,
which has the same effect.

Support for ``nx1 = None`` or ``ny1 = None`` in ``AxesLocator`` and ``Divider.locate``