Deprecations ------------ Parameters to ``plt.figure()`` and the ``Figure`` constructor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All parameters to `.pyplot.figure` and the `.Figure` constructor, other than *num*, *figsize*, and *dpi*, will become keyword-only after a deprecation period. Deprecation aliases in cbook ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The module ``matplotlib.cbook.deprecation`` was previously deprecated in Matplotlib 3.4, along with deprecation-related API in ``matplotlib.cbook``. Due to technical issues, ``matplotlib.cbook.MatplotlibDeprecationWarning`` and ``matplotlib.cbook.mplDeprecation`` did not raise deprecation warnings on use. Changes in Python have now made it possible to warn when these aliases are being used. In order to avoid downstream breakage, these aliases will now warn, and their removal has been pushed from 3.6 to 3.8 to give time to notice said warnings. As replacement, please use `matplotlib.MatplotlibDeprecationWarning`. ``Axes`` subclasses should override ``clear`` instead of ``cla`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For clarity, `.axes.Axes.clear` is now preferred over `.Axes.cla`. However, for backwards compatibility, the latter will remain as an alias for the former. For additional compatibility with third-party libraries, Matplotlib will continue to call the ``cla`` method of any `~.axes.Axes` subclasses if they define it. In the future, this will no longer occur, and Matplotlib will only call the ``clear`` method in `~.axes.Axes` subclasses. It is recommended to define only the ``clear`` method when on Matplotlib 3.6, and only ``cla`` for older versions. Pending deprecation top-level cmap registration and access functions in ``mpl.cm`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As part of a `multi-step process `_ we are refactoring the global state for managing the registered colormaps. In Matplotlib 3.5 we added a `.ColormapRegistry` class and exposed an instance at the top level as ``matplotlib.colormaps``. The existing top level functions in `matplotlib.cm` (``get_cmap``, ``register_cmap``, ``unregister_cmap``) were changed to be aliases around the same instance. In Matplotlib 3.6 we have marked those top level functions as pending deprecation with the intention of deprecation in Matplotlib 3.7. The following functions have been marked for pending deprecation: - ``matplotlib.cm.get_cmap``; use ``matplotlib.colormaps[name]`` instead if you have a `str`. **Added 3.6.1** Use `matplotlib.cm.ColormapRegistry.get_cmap` if you have a string, `None` or a `matplotlib.colors.Colormap` object that you want to convert to a `matplotlib.colors.Colormap` instance. - ``matplotlib.cm.register_cmap``; use `matplotlib.colormaps.register <.ColormapRegistry.register>` instead - ``matplotlib.cm.unregister_cmap``; use `matplotlib.colormaps.unregister <.ColormapRegistry.unregister>` instead - ``matplotlib.pyplot.register_cmap``; use `matplotlib.colormaps.register <.ColormapRegistry.register>` instead The `matplotlib.pyplot.get_cmap` function will stay available for backward compatibility. Pending deprecation of layout methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The methods `~.Figure.set_tight_layout`, `~.Figure.set_constrained_layout`, are discouraged, and now emit a `PendingDeprecationWarning` in favor of explicitly referencing the layout engine via ``figure.set_layout_engine('tight')`` and ``figure.set_layout_engine('constrained')``. End users should not see the warning, but library authors should adjust. The methods `~.Figure.set_constrained_layout_pads` and `~.Figure.get_constrained_layout_pads` are will be deprecated in favor of ``figure.get_layout_engine().set()`` and ``figure.get_layout_engine().get()``, and currently emit a `PendingDeprecationWarning`. seaborn styles renamed ~~~~~~~~~~~~~~~~~~~~~~ Matplotlib currently ships many style files inspired from the seaborn library ("seaborn", "seaborn-bright", "seaborn-colorblind", etc.) but they have gone out of sync with the library itself since the release of seaborn 0.9. To prevent confusion, the style files have been renamed "seaborn-v0_8", "seaborn-v0_8-bright", "seaborn-v0_8-colorblind", etc. Users are encouraged to directly use seaborn to access the up-to-date styles. Auto-removal of overlapping Axes by ``plt.subplot`` and ``plt.subplot2grid`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Previously, `.pyplot.subplot` and `.pyplot.subplot2grid` would automatically remove preexisting Axes that overlap with the newly added Axes. This behavior was deemed confusing, and is now deprecated. Explicitly call ``ax.remove()`` on Axes that need to be removed. Passing *linefmt* positionally to ``stem`` is undeprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Positional use of all formatting parameters in `~.Axes.stem` has been deprecated since Matplotlib 3.5. This deprecation is relaxed so that one can still pass *linefmt* positionally, i.e. ``stem(x, y, 'r')``. ``stem(..., use_line_collection=False)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ... is deprecated with no replacement. This was a compatibility fallback to a former more inefficient representation of the stem lines. Positional / keyword arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Passing all but the very few first arguments positionally in the constructors of Artists is deprecated. Most arguments will become keyword-only in a future version. Passing too many positional arguments to ``tripcolor`` is now deprecated (extra arguments were previously silently ignored). Passing *emit* and *auto* parameters of ``set_xlim``, ``set_ylim``, ``set_zlim``, ``set_rlim`` positionally is deprecated; they will become keyword-only in a future release. The *transOffset* parameter of `.Collection.set_offset_transform` and the various ``create_collection`` methods of legend handlers has been renamed to *offset_transform* (consistently with the property name). Calling ``MarkerStyle()`` with no arguments or ``MarkerStyle(None)`` is deprecated; use ``MarkerStyle("")`` to construct an empty marker style. ``Axes.get_window_extent`` / ``Figure.get_window_extent`` accept only *renderer*. This aligns the API with the general `.Artist.get_window_extent` API. All other parameters were ignored anyway. The *cleared* parameter of ``get_renderer``, which only existed for AGG-based backends, has been deprecated. Use ``renderer.clear()`` instead to explicitly clear the renderer buffer. Methods to set parameters in ``LogLocator`` and ``LogFormatter*`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In `~.LogFormatter` and derived subclasses, the methods ``base`` and ``label_minor`` for setting the respective parameter are deprecated and replaced by ``set_base`` and ``set_label_minor``, respectively. In `~.LogLocator`, the methods ``base`` and ``subs`` for setting the respective parameter are deprecated. Instead, use ``set_params(base=..., subs=...)``. ``Axes.get_renderer_cache`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The canvas now takes care of the renderer and whether to cache it or not. The alternative is to call ``axes.figure.canvas.get_renderer()``. Groupers from ``get_shared_x_axes`` / ``get_shared_y_axes`` will be immutable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Modifications to the Groupers returned by ``get_shared_x_axes`` and ``get_shared_y_axes`` are deprecated. In the future, these methods will return immutable views on the grouper structures. Note that previously, calling e.g. ``join()`` would already fail to set up the correct structures for sharing axes; use `.Axes.sharex` or `.Axes.sharey` instead. Unused methods in ``Axis``, ``Tick``, ``XAxis``, and ``YAxis`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``Tick.label`` has been pending deprecation since 3.1 and is now deprecated. Use ``Tick.label1`` instead. The following methods are no longer used and deprecated without a replacement: - ``Axis.get_ticklabel_extents`` - ``Tick.get_pad_pixels`` - ``XAxis.get_text_heights`` - ``YAxis.get_text_widths`` ``mlab.stride_windows`` ~~~~~~~~~~~~~~~~~~~~~~~ ... is deprecated. Use ``np.lib.stride_tricks.sliding_window_view`` instead (or ``np.lib.stride_tricks.as_strided`` on NumPy < 1.20). Event handlers ~~~~~~~~~~~~~~ The ``draw_event``, ``resize_event``, ``close_event``, ``key_press_event``, ``key_release_event``, ``pick_event``, ``scroll_event``, ``button_press_event``, ``button_release_event``, ``motion_notify_event``, ``enter_notify_event`` and ``leave_notify_event`` methods of `.FigureCanvasBase` are deprecated. They had inconsistent signatures across backends, and made it difficult to improve event metadata. In order to trigger an event on a canvas, directly construct an `.Event` object of the correct class and call ``canvas.callbacks.process(event.name, event)``. Widgets ~~~~~~~ All parameters to ``MultiCursor`` starting from *useblit* are becoming keyword-only (passing them positionally is deprecated). The ``canvas`` and ``background`` attributes of ``MultiCursor`` are deprecated with no replacement. The *visible* attribute of Selector widgets has been deprecated; use ``set_visible`` or ``get_visible`` instead. The *state_modifier_keys* attribute of Selector widgets has been privatized and the modifier keys must be set when creating the widget. ``Axes3D.dist`` ~~~~~~~~~~~~~~~ ... has been privatized. Use the *zoom* keyword argument in `.Axes3D.set_box_aspect` instead. 3D Axis ~~~~~~~ The previous constructor of `.axis3d.Axis`, with signature ``(self, adir, v_intervalx, d_intervalx, axes, *args, rotate_label=None, **kwargs)`` is deprecated in favor of a new signature closer to the one of 2D Axis; it is now ``(self, axes, *, rotate_label=None, **kwargs)`` where ``kwargs`` are forwarded to the 2D Axis constructor. The axis direction is now inferred from the axis class' ``axis_name`` attribute (as in the 2D case); the ``adir`` attribute is deprecated. The ``init3d`` method of 3D Axis is also deprecated; all the relevant initialization is done as part of the constructor. The ``d_interval`` and ``v_interval`` attributes of 3D Axis are deprecated; use ``get_data_interval`` and ``get_view_interval`` instead. The ``w_xaxis``, ``w_yaxis``, and ``w_zaxis`` attributes of ``Axis3D`` have been pending deprecation since 3.1. They are now deprecated. Instead use ``xaxis``, ``yaxis``, and ``zaxis``. ``mplot3d.axis3d.Axis.set_pane_pos`` is deprecated. This is an internal method where the provided values are overwritten during drawing. Hence, it does not serve any purpose to be directly accessible. The two helper functions ``mplot3d.axis3d.move_from_center`` and ``mplot3d.axis3d.tick_update_position`` are considered internal and deprecated. If these are required, please vendor the code from the corresponding private methods ``_move_from_center`` and ``_tick_update_position``. ``Figure.callbacks`` is deprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Figure ``callbacks`` property is deprecated. The only signal was "dpi_changed", which can be replaced by connecting to the "resize_event" on the canvas ``figure.canvas.mpl_connect("resize_event", func)`` instead. ``FigureCanvas`` without a ``required_interactive_framework`` attribute ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Support for such canvas classes is deprecated. Note that canvas classes which inherit from ``FigureCanvasBase`` always have such an attribute. Backend-specific deprecations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``backend_gtk3.FigureManagerGTK3Agg`` and ``backend_gtk4.FigureManagerGTK4Agg``; directly use ``backend_gtk3.FigureManagerGTK3`` and ``backend_gtk4.FigureManagerGTK4`` instead. - The *window* parameter to ``backend_gtk3.NavigationToolbar2GTK3`` had no effect, and is now deprecated. - ``backend_gtk3.NavigationToolbar2GTK3.win`` - ``backend_gtk3.RendererGTK3Cairo`` and ``backend_gtk4.RendererGTK4Cairo``; use `.RendererCairo` instead, which has gained the ``set_context`` method, which also auto-infers the size of the underlying surface. - ``backend_cairo.RendererCairo.set_ctx_from_surface`` and ``backend_cairo.RendererCairo.set_width_height`` in favor of `.RendererCairo.set_context`. - ``backend_gtk3.error_msg_gtk`` - ``backend_gtk3.icon_filename`` and ``backend_gtk3.window_icon`` - ``backend_macosx.NavigationToolbar2Mac.prepare_configure_subplots`` has been replaced by ``configure_subplots()``. - ``backend_pdf.Name.hexify`` - ``backend_pdf.Operator`` and ``backend_pdf.Op.op`` are deprecated in favor of a single standard `enum.Enum` interface on `.backend_pdf.Op`. - ``backend_pdf.fill``; vendor the code of the similarly named private functions if you rely on these functions. - ``backend_pgf.LatexManager.texcommand`` and ``backend_pgf.LatexManager.latex_header`` - ``backend_pgf.NO_ESCAPE`` - ``backend_pgf.common_texification`` - ``backend_pgf.get_fontspec`` - ``backend_pgf.get_preamble`` - ``backend_pgf.re_mathsep`` - ``backend_pgf.writeln`` - ``backend_ps.convert_psfrags`` - ``backend_ps.quote_ps_string``; vendor the code of the similarly named private functions if you rely on it. - ``backend_qt.qApp``; use ``QtWidgets.QApplication.instance()`` instead. - ``backend_svg.escape_attrib``; vendor the code of the similarly named private functions if you rely on it. - ``backend_svg.escape_cdata``; vendor the code of the similarly named private functions if you rely on it. - ``backend_svg.escape_comment``; vendor the code of the similarly named private functions if you rely on it. - ``backend_svg.short_float_fmt``; vendor the code of the similarly named private functions if you rely on it. - ``backend_svg.generate_transform`` and ``backend_svg.generate_css`` - ``backend_tk.NavigationToolbar2Tk.lastrect`` and ``backend_tk.RubberbandTk.lastrect`` - ``backend_tk.NavigationToolbar2Tk.window``; use ``toolbar.master`` instead. - ``backend_tools.ToolBase.destroy``; To run code upon tool removal, connect to the ``tool_removed_event`` event. - ``backend_wx.RendererWx.offset_text_height`` - ``backend_wx.error_msg_wx`` - ``FigureCanvasBase.pick``; directly call `.Figure.pick`, which has taken over the responsibility of checking the canvas widget lock as well. - ``FigureCanvasBase.resize``, which has no effect; use ``FigureManagerBase.resize`` instead. - ``FigureManagerMac.close`` - ``FigureFrameWx.sizer``; use ``frame.GetSizer()`` instead. - ``FigureFrameWx.figmgr`` and ``FigureFrameWx.get_figure_manager``; use ``frame.canvas.manager`` instead. - ``FigureFrameWx.num``; use ``frame.canvas.manager.num`` instead. - ``FigureFrameWx.toolbar``; use ``frame.GetToolBar()`` instead. - ``FigureFrameWx.toolmanager``; use ``frame.canvas.manager.toolmanager`` instead. Modules ~~~~~~~ The modules ``matplotlib.afm``, ``matplotlib.docstring``, ``matplotlib.fontconfig_pattern``, ``matplotlib.tight_bbox``, ``matplotlib.tight_layout``, and ``matplotlib.type1font`` are considered internal and public access is deprecated. ``checkdep_usetex`` deprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This method was only intended to disable tests in case no latex install was found. As such, it is considered to be private and for internal use only. Please vendor the code if you need this. ``date_ticker_factory`` deprecated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``date_ticker_factory`` method in the `matplotlib.dates` module is deprecated. Instead use `~.AutoDateLocator` and `~.AutoDateFormatter` for a more flexible and scalable locator and formatter. If you need the exact ``date_ticker_factory`` behavior, please copy the code. ``dviread.find_tex_file`` will raise ``FileNotFoundError`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the future, ``dviread.find_tex_file`` will raise a `FileNotFoundError` for missing files. Previously, it would return an empty string in such cases. Raising an exception allows attaching a user-friendly message instead. During the transition period, a warning is raised. ``transforms.Affine2D.identity()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ... is deprecated in favor of directly calling the `.Affine2D` constructor with no arguments. Deprecations in ``testing.decorators`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The unused class ``CleanupTestCase`` and decorator ``cleanup`` are deprecated and will be removed. Vendor the code, including the private function ``_cleanup_cm``. The function ``check_freetype_version`` is considered internal and deprecated. Vendor the code of the private function ``_check_freetype_version``. ``text.get_rotation()`` ~~~~~~~~~~~~~~~~~~~~~~~ ... is deprecated with no replacement. Copy the original implementation if needed. Miscellaneous internals ~~~~~~~~~~~~~~~~~~~~~~~ - ``axes_grid1.axes_size.AddList``; use ``sum(sizes, start=Fixed(0))`` (for example) to sum multiple size objects. - ``axes_size.Padded``; use ``size + pad`` instead - ``axes_size.SizeFromFunc``, ``axes_size.GetExtentHelper`` - ``AxisArtistHelper.delta1`` and ``AxisArtistHelper.delta2`` - ``axislines.GridHelperBase.new_gridlines`` and ``axislines.Axes.new_gridlines`` - ``cbook.maxdict``; use the standard library ``functools.lru_cache`` instead. - ``_DummyAxis.dataLim`` and ``_DummyAxis.viewLim``; use ``get_data_interval()``, ``set_data_interval()``, ``get_view_interval()``, and ``set_view_interval()`` instead. - ``GridSpecBase.get_grid_positions(..., raw=True)`` - ``ImageMagickBase.delay`` and ``ImageMagickBase.output_args`` - ``MathtextBackend``, ``MathtextBackendAgg``, ``MathtextBackendPath``, ``MathTextWarning`` - ``TexManager.get_font_config``; it previously returned an internal hashed key for used for caching purposes. - ``TextToPath.get_texmanager``; directly construct a `.texmanager.TexManager` instead. - ``ticker.is_close_to_int``; use ``math.isclose(x, round(x))`` instead. - ``ticker.is_decade``; use ``y = numpy.log(x)/numpy.log(base); numpy.isclose(y, numpy.round(y))`` instead.