diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst index 5cde8c5b5fbf..f7f8b2986c64 100644 --- a/doc/api/api_changes.rst +++ b/doc/api/api_changes.rst @@ -26,12 +26,14 @@ This pages lists API changes for the most recent version of Matplotlib. - All the files in 'next_api_changes' should be moved to the bottom of this page - This note, and the toctree below should be commented out +.. -.. toctree:: - :glob: - :maxdepth: 1 + .. toctree:: + :glob: + :maxdepth: 1 + + next_api_changes/* - next_api_changes/* API Changes for 3.0.0 ===================== @@ -42,13 +44,20 @@ Drop support for python 2 Matplotlib 3 only supports python 3.5 and higher. -Hold machinery removed ----------------------- +Changes to backend loading +-------------------------- + +Failure to load backend modules (``macosx`` on non-framework builds and +``gtk3`` when running headless) now raises `ImportError` (instead of +`RuntimeError` and `TypeError`, respectively). + +Third-party backends that integrate with an interactive framework are now +encouraged to define the ``required_interactive_framework`` global value to one +of the following values: "qt5", "qt4", "gtk3", "wx", "tk", or "macosx". This +information will be used to determine whether it is possible to switch from a +backend to another (specifically, whether they use the same interactive +framework). -Setting or unsetting ``hold`` (deprecated in version 2.1) has now -been completely removed. Matplotlib now always behaves as if ``hold=True``. -To clear an axes you can manually use :meth:`~.axes.Axes.cla()`, -or to clear an entire figure use :meth:`~.figure.Figure.clf()`. `.Axes.hist2d` now uses `~.Axes.pcolormesh` instead of `~.Axes.pcolorfast` @@ -60,121 +69,39 @@ returned *image* now is of type `~.matplotlib.collections.QuadMesh` instead of `~.matplotlib.image.AxesImage`. -`Text.set_text` with string argument ``None`` sets string to empty ------------------------------------------------------------------- - -`Text.set_text` when passed a string value of ``None`` would set the -string to ``"None"``, so subsequent calls to `Text.get_text` would return -the ambiguous ``"None"`` string. - -This change sets text objects passed ``None`` to have empty strings, so that -`Text.get_text` returns and an empty string. - -Deprecations ------------- -The following modules are deprecated: - -- :mod:`matplotlib.compat.subprocess`. This was a python 2 workaround, but all - the functionality can now be found in the python 3 standard library - :mod:`subprocess`. -- :mod:`matplotlib.backends.wx_compat`. Python 3 is only compatible with - wxPython 4, so support for wxPython 3 or earlier can be dropped. - -The following classes, methods, functions, and attributes are deprecated: - -- ``RcParams.msg_depr``, ``RcParams.msg_depr_ignore``, - ``RcParams.msg_depr_set``, ``RcParams.msg_obsolete``, - ``RcParams.msg_backend_obsolete`` -- ``afm.parse_afm`` -- ``backend_pgf.get_texcommand`` -- ``backend_ps.get_bbox`` -- ``backend_qt5.error_msg_qt``, ``backend_qt5.exception_handler`` -- ``backend_wx.FigureCanvasWx.macros`` -- ``cbook.GetRealpathAndStat``, ``cbook.Locked`` -- ``cbook.is_numlike`` (use ``isinstance(..., numbers.Number)`` instead), - ``cbook.listFiles``, ``cbook.unicode_safe`` -- ``container.Container.set_remove_method`` -- ``contour.ContourLabeler.cl``, ``.cl_xy``, and ``.cl_cvalues`` -- ``dates.DateFormatter.strftime_pre_1900``, ``dates.DateFormatter.strftime`` -- ``font_manager.TempCache`` -- ``mathtext.unichr_safe`` (use ``chr`` instead) -- ``table.Table.get_child_artists`` (use ``get_children`` instead) -- ``testing.compare.ImageComparisonTest``, ``testing.compare.compare_float``, -- ``testing.decorators.CleanupTest`` - ``testing.decorators.skip_if_command_unavailable`` -- ``FigureCanvasQT.keyAutoRepeat`` (directly check - ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to - handle autorepeated key presses) -- ``FigureCanvasWx.macros`` -- ``_ImageBase.iterpnames``, use the ``interpolation_names`` property instead. - (this affects classes that inherit from ``_ImageBase`` including - :class:`FigureImage`, :class:`BboxImage`, and :class:`AxesImage`) -- ``patches.Polygon.xy`` -- ``texmanager.dvipng_hack_alpha`` -- ``text.Annotation.arrow`` -- `.Legend.draggable()`, in favor of `.Legend.set_draggable()` - (``Legend.draggable`` may be reintroduced as a property in future releases) - - -The following rcParams are deprecated: - -- ``examples.directory`` (use ``datapath`` instead) -- ``pgf.debug`` (the pgf backend relies on logging) -- ``text.latex.unicode`` - -The following keyword arguments are deprecated: +`.matplotlib.Axes.get_tightbbox` now includes all artists +--------------------------------------------------------- -- passing ``verts`` to ``Axes.scatter`` (use ``marker`` instead) -- passing ``obj_type`` to ``cbook.deprecated`` +Layout tools like `.Figure.tight_layout`, ``constrained_layout``, +and ``fig.savefig('fname.png', bbox_inches="tight")`` use +`.matplotlib.Axes.get_tightbbox` to determine the bounds of each axes on +a figure and adjust spacing between axes. -The following call signatures are deprecated: -- passing a ``wx.EvtHandler`` as first argument to ``backend_wx.TimerWx`` +In Matplotlib 2.2 ``get_tightbbox`` started to include legends made on the +axes, but still excluded some other artists, like text that may overspill an +axes. For Matplotlib 3.0, *all* artists are now included in the bounding box. -Deprecated methods removed from `matplotlib.testing` ----------------------------------------------------- +This new default may be overridden in either of two ways: -The deprecated methods `knownfailureif` and `remove_text` have been removed -from :mod:`matplotlib.testing.decorators`. +1. Make the artist to be excluded a child of the figure, not the axes. E.g., + call ``fig.legend()`` instead of ``ax.legend()`` (perhaps using + `~.matplotlib.Axes.get_legend_handles_labels` to gather handles and labels + from the parent axes). +2. If the artist is a child of the axes, set the artist property + ``artist.set_in_layout(False)``. -The entire contents of `testing.noseclasses` have also been removed. +`Text.set_text` with string argument ``None`` sets string to empty +------------------------------------------------------------------ -``matplotlib.cbook.deprecation.mplDeprecation`` is deprecated -------------------------------------------------------------- - -:class:`matplotlib.cbook.deprecation.mplDeprecation` will be removed in -future versions. It is just an alias for -:class:`matplotlib.cbook.deprecation.MatplotlibDeprecationWarning`. -Please use the :class:`~.MatplotlibDeprecationWarning` directly if neccessary. - - -matplotlib.cbook.Bunch deprecated ---------------------------------- - -The ``matplotlib.cbook.Bunch`` class has been deprecated. Instead, use -`types.SimpleNamespace` from the standard library which provides the same -functionality. - - -Deprecation of certain marker styles ------------------------------------- - -Using ``(n, 3)`` as marker style to specify a circle marker is deprecated. Use -``"o"`` instead. - -Using ``([(x0, y0), (x1, y1), ...], 0)`` as marker style to specify a custom -marker path is deprecated. Use ``[(x0, y0), (x1, y1), ...]`` instead. - +`Text.set_text` when passed a string value of ``None`` would set the +string to ``"None"``, so subsequent calls to `Text.get_text` would return +the ambiguous ``"None"`` string. -Removal of deprecated backends ------------------------------- +This change sets text objects passed ``None`` to have empty strings, so that +`Text.get_text` returns an empty string. -Deprecated backends have been removed: - * GTKAgg - * GTKCairo - * GTK - * GDK ``Axes3D.get_xlim``, ``get_ylim`` and ``get_zlim`` now return a tuple @@ -184,64 +111,6 @@ They previously returned an array. Returning a tuple is consistent with the behavior for 2D axes. -Modified APIs -------------- - -The following APIs have been modified: - -- ``Axes.mouseover_set`` is now a frozenset, and deprecated. Directly - manipulate the artist's ``.mouseover`` attribute to change their mouseover - status. - -Removal of deprecated APIs --------------------------- - -The following deprecated API elements have been removed: - -- ``matplotlib.checkdep_tex``, ``matplotlib.checkdep_xmllint``, -- ``backend_bases.IdleEvent``, -- ``cbook.converter``, ``cbook.tostr``, ``cbook.todatetime``, ``cbook.todate``, - ``cbook.tofloat``, ``cbook.toint``, ``cbook.unique``, - ``cbook.is_string_like``, ``cbook.is_sequence_of_strings``, - ``cbook.is_scalar``, ``cbook.soundex``, ``cbook.dict_delall``, - ``cbook.get_split_ind``, ``cbook.wrap``, ``cbook.get_recursive_filelist``, - ``cbook.pieces``, ``cbook.exception_to_str``, ``cbook.allequal``, - ``cbook.alltrue``, ``cbook.onetrue``, ``cbook.allpairs``, ``cbook.finddir``, - ``cbook.reverse_dict``, ``cbook.restrict_dict``, ``cbook.issubclass_safe``, - ``cbook.recursive_remove``, ``cbook.unmasked_index_ranges``, - ``cbook.Null``, ``cbook.RingBuffer``, ``cbook.Sorter``, ``cbook.Xlator``, -- ``font_manager.weight_as_number``, ``font_manager.ttfdict_to_fnames``, -- ``pyplot.colors``, ``pyplot.spectral``, -- ``rcsetup.validate_negative_linestyle``, - ``rcsetup.validate_negative_linestyle_legacy``, -- ``testing.compare.verifiers``, ``testing.compare.verify``, -- ``testing.decorators.knownfailureif``, - ``testing.decorators.ImageComparisonTest.remove_text``, -- ``tests.assert_str_equal``, ``tests.test_tinypages.file_same``, -- ``texmanager.dvipng_hack_alpha``, -- ``_AxesBase.axesPatch``, ``_AxesBase.set_color_cycle``, - ``_AxesBase.get_cursor_props``, ``_AxesBase.set_cursor_props``, -- ``_ImageBase.iterpnames``, -- ``FigureCanvasBase.start_event_loop_default``; -- ``FigureCanvasBase.stop_event_loop_default``; -- ``Figure.figurePatch``, -- ``FigureCanvasBase.dynamic_update``, ``FigureCanvasBase.idle_event``, - ``FigureCanvasBase.get_linestyle``, ``FigureCanvasBase.set_linestyle`` -- ``FigureCanvasQTAggBase`` -- ``FigureCanvasQTAgg.blitbox``, -- ``FigureCanvasTk.show`` (alternative: ``FigureCanvasTk.draw``) -- ``FigureManagerTkAgg`` (alternative: ``FigureManagerTk``) -- ``NavigationToolbar2TkAgg`` (alternative: ``NavigationToolbar2Tk``) -- ``backend_wxagg.Toolbar`` (alternative: ``backend_wxagg.NavigationToolbar2WxAgg``) -- ``RendererAgg.debug()`` -- passing non-numbers to ``EngFormatter.format_eng``, -- passing ``frac`` to ``PolarAxes.set_theta_grids``, -- any mention of idle events, - -The following API elements have been removed: - -- ``backend_cairo.HAS_CAIRO_CFFI``, -- ``sphinxext.sphinx_version``, ``font_manager.list_fonts`` now follows the platform's casefolding semantics @@ -250,10 +119,10 @@ The following API elements have been removed: i.e., it behaves case-insensitively on Windows only. -``bar``/``barh`` no longer accepts ``left``/``bottom`` as first named argument ------------------------------------------------------------------------------- +``bar`` / ``barh`` no longer accepts ``left`` / ``bottom`` as first named argument +---------------------------------------------------------------------------------- -These arguments were renamed in 2.0 to ``x``/``y`` following the change of the +These arguments were renamed in 2.0 to ``x`` / ``y`` following the change of the default alignment from ``edge`` to ``center``. @@ -273,8 +142,8 @@ Different exception types for undocumented options will be raised if they would override the earlier limit arguments. -Improved call signature for Axes.margins() ------------------------------------------- +Improved call signature for ``Axes.margins`` +-------------------------------------------- :meth:`matplotlib.axes.Axes.margins` and :meth:`mpl_toolkits.mplot3d.Axes3D.margins` no longer accept arbitrary keywords. ``TypeError`` will therefore be raised @@ -288,14 +157,6 @@ warning if only two positional arguments are passed. To supply only ``x`` and ``y`` margins, use keyword arguments. -lib/mpl_examples removed ------------------------- - -The symlink from lib/mpl_examples to ../examples has been removed. -This is not installed as an importable package and should not affect -end users, however this may require down-stream packagers to adjust. -The content is still available top-level examples directory. - Explicit arguments instead of \*args, \*\*kwargs ------------------------------------------------ @@ -308,18 +169,14 @@ now raise ``TypeError`` because ``**kwargs`` has been removed. - :meth:`matplotlib.axes.Axes.stem` no longer accepts unknown keywords, and raises ``TypeError`` instead of emitting a deprecation. +- :meth:`matplotlib.axex.Axes.stem` now raises TypeError when passed + unhandled positional arguments. If two or more arguments are passed + (ie X, Y, [linefmt], ...) and Y cannot be cast to an array, an error + will be raised instead of treating X as Y and Y as linefmt. - :meth:`mpl_toolkits.axes_grid1.axes_divider.SubPlotDivider` raises ``TypeError`` instead of ``Exception`` when passed unknown kwargs. -Consistent handling of \*args in Axes.stem ------------------------------------------- - -:meth:`matplotlib.axex.Axes.stem` now raises TypeError when passed -unhandled positional arguments. If two or more arguments are passed -(ie X, Y, [linefmt], ...) and Y cannot be cast to an array, an error -will be raised instead of treating X as Y and Y as linefmt. - Cleanup decorators and test classes no longer destroy warnings filter on exit ----------------------------------------------------------------------------- @@ -351,16 +208,6 @@ As a side effect of this change, `.image.thumbnail` now also supports .ps, .eps, and .svgz output. -Removed proprietary sphinx directives -------------------------------------- - -The matplotlib documentation used the proprietary sphinx directives -`.. htmlonly::`, and `.. latexonly::`. These have been replaced with the -standard sphinx directives `.. only:: html` and `.. only:: latex`. This -change will not affect any users. Only downstream package maintainers, who -have used the proprietary directives in their docs, will have to switch to the -sphinx directives. - `.FuncAnimation` now draws artists according to their zorder when blitting -------------------------------------------------------------------------- @@ -372,6 +219,7 @@ However, note that only zorder of passed artists will be respected, as they are drawn on top of any existing artists (see `#11369 `_). + Contour color autoscaling improvements -------------------------------------- @@ -397,21 +245,6 @@ A bug was fixed where the last row and column of data in `~.Axes.axes.streamplot` were being dropped. -Changes to backend loading --------------------------- - -Failure to load backend modules (``macosx`` on non-framework builds and -``gtk3`` when running headless) now raises `ImportError` (instead of -`RuntimeError` and `TypeError`, respectively). - -Third-party backends that integrate with an interactive framework are now -encouraged to define the ``required_interactive_framework`` global value to one -of the following values: "qt5", "qt4", "gtk3", "wx", "tk", or "macosx". This -information will be used to determine whether it is possible to switch from a -backend to another (specifically, whether they use the same interactive -framework). - - Changed default `AutoDateLocator` kwarg *interval_multiples* to ``True`` ------------------------------------------------------------------------ @@ -458,7 +291,7 @@ old behavior back: draw had been triggered or `.Axes.apply_aspect` had been called, even if the kwarg *original* was set to ``False``. Now `.Axes.apply_aspect` is called so ``ax.get_position()`` will return the new modified position. -To get the old behaviour use ``ax.get_position(original=True)``. +To get the old behavior use ``ax.get_position(original=True)``. The ticks for colorbar now adjust for the size of the colorbar @@ -468,7 +301,8 @@ Colorbar ticks now adjust for the size of the colorbar if the colorbar is made from a mappable that is not a contour or doesn't have a BoundaryNorm, or boundaries are not specified. If boundaries, etc are specified, the colorbar maintains the -original behaviour. +original behavior. + Colorbar for log-scaled hexbin ------------------------------ @@ -485,3 +319,259 @@ actually be the default color of whatever was rendering the pgf file (which was of course usually black). The new behavior is that black text is black, regardless of the default color. However, this means that there is no way to fall back on the default color of the renderer. + + +Blacklisted rcparams no longer updated by `rcdefaults`, `rc_file_defaults`, `rc_file` +------------------------------------------------------------------------------------- + +The rc modifier functions `rcdefaults`, `rc_file_defaults` and `rc_file` +now ignore rcParams in the `matplotlib.style.core.STYLE_BLACKLIST` set. In +particular, this prevents the ``backend`` and ``interactive`` rcParams from +being incorrectly modified by these functions. + + + +`CallbackRegistry` now stores callbacks using stdlib's `WeakMethod`\s +--------------------------------------------------------------------- + +In particular, this implies that ``CallbackRegistry.callbacks[signal]`` is now +a mapping of callback ids to `WeakMethod`\s (i.e., they need to be first called +with no arguments to retrieve the method itself). + + +Changes regarding the text.latex.unicode rcParam +------------------------------------------------ + +The rcParam now defaults to True and is deprecated (i.e., in future versions +of Maplotlib, unicode input will always be supported). + +Moreover, the underlying implementation now uses ``\usepackage[utf8]{inputenc}`` +instead of ``\usepackage{ucs}\usepackage[utf8x]{inputenc}``. + + +Removed ``pytz`` as a dependency +-------------------------------- + +Since ``dateutil`` and ``pytz`` both provide time zones, and +matplotlib already depends on ``dateutil``, matplotlib will now use +``dateutil`` time zones internally and drop the redundant dependency +on ``pytz``. While ``dateutil`` time zones are preferred (and +currently recommended in the Python documentation), the explicit use +of ``pytz`` zones is still supported. + +Deprecations +------------ + +Modules +``````` +The following modules are deprecated: + +- :mod:`matplotlib.compat.subprocess`. This was a python 2 workaround, but all + the functionality can now be found in the python 3 standard library + :mod:`subprocess`. +- :mod:`matplotlib.backends.wx_compat`. Python 3 is only compatible with + wxPython 4, so support for wxPython 3 or earlier can be dropped. + +Classes, methods, functions, and attributes +``````````````````````````````````````````` + +The following classes, methods, functions, and attributes are deprecated: + +- ``RcParams.msg_depr``, ``RcParams.msg_depr_ignore``, + ``RcParams.msg_depr_set``, ``RcParams.msg_obsolete``, + ``RcParams.msg_backend_obsolete`` +- ``afm.parse_afm`` +- ``backend_pdf.PdfFile.texFontMap`` +- ``backend_pgf.get_texcommand`` +- ``backend_ps.get_bbox`` +- ``backend_qt5.FigureCanvasQT.keyAutoRepeat`` (directly check + ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to + handle autorepeated key presses). +- ``backend_qt5.error_msg_qt``, ``backend_qt5.exception_handler`` +- ``backend_wx.FigureCanvasWx.macros`` +- ``backends.pylab_setup`` +- ``cbook.GetRealpathAndStat``, ``cbook.Locked`` +- ``cbook.is_numlike`` (use ``isinstance(..., numbers.Number)`` instead), + ``cbook.listFiles``, ``cbook.unicode_safe`` +- ``container.Container.set_remove_method``, +- ``contour.ContourLabeler.cl``, ``.cl_xy``, and ``.cl_cvalues`` +- ``dates.DateFormatter.strftime_pre_1900``, ``dates.DateFormatter.strftime`` +- ``font_manager.TempCache`` +- ``image._ImageBase.iterpnames``, use the ``interpolation_names`` property + instead. (this affects classes that inherit from ``_ImageBase`` including + :class:`FigureImage`, :class:`BboxImage`, and :class:`AxesImage`) +- ``mathtext.unichr_safe`` (use ``chr`` instead) +- ``patches.Polygon.xy`` +- ``table.Table.get_child_artists`` (use ``get_children`` instead) +- ``testing.compare.ImageComparisonTest``, ``testing.compare.compare_float`` +- ``testing.decorators.CleanupTest``, + ``testing.decorators.skip_if_command_unavailable`` +- ``FigureCanvasQT.keyAutoRepeat`` (directly check + ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to + handle autorepeated key presses) +- ``FigureCanvasWx.macros`` +- ``_ImageBase.iterpnames``, use the ``interpolation_names`` property instead. + (this affects classes that inherit from ``_ImageBase`` including + :class:`FigureImage`, :class:`BboxImage`, and :class:`AxesImage`) +- ``patches.Polygon.xy`` +- ``texmanager.dvipng_hack_alpha`` +- ``text.Annotation.arrow`` +- `.Legend.draggable()`, in favor of `.Legend.set_draggable()` + (``Legend.draggable`` may be reintroduced as a property in future releases) +- ``textpath.TextToPath.tex_font_map`` +- :class:`matplotlib.cbook.deprecation.mplDeprecation` will be removed + in future versions. It is just an alias for + :class:`matplotlib.cbook.deprecation.MatplotlibDeprecationWarning`. + Please use the + :class:`~matplotlib.cbook.MatplotlibDeprecationWarning` directly if + neccessary. +- The ``matplotlib.cbook.Bunch`` class has been deprecated. Instead, use + `types.SimpleNamespace` from the standard library which provides the same + functionality. +- ``Axes.mouseover_set`` is now a frozenset, and deprecated. Directly + manipulate the artist's ``.mouseover`` attribute to change their mouseover + status. + +The following keyword arguments are deprecated: + +- passing ``verts`` to ``Axes.scatter`` (use ``marker`` instead) +- passing ``obj_type`` to ``cbook.deprecated`` + +The following call signatures are deprecated: + +- passing a ``wx.EvtHandler`` as first argument to ``backend_wx.TimerWx`` + + +rcParams +```````` + +The following rcParams are deprecated: + +- ``examples.directory`` (use ``datapath`` instead) +- ``pgf.debug`` (the pgf backend relies on logging) +- ``text.latex.unicode`` (always True now) + + +marker styles +````````````` +- Using ``(n, 3)`` as marker style to specify a circle marker is deprecated. Use + ``"o"`` instead. +- Using ``([(x0, y0), (x1, y1), ...], 0)`` as marker style to specify a custom + marker path is deprecated. Use ``[(x0, y0), (x1, y1), ...]`` instead. + + +Deprecation of ``LocatableAxes`` in toolkits +```````````````````````````````````````````` + +The ``LocatableAxes`` classes in toolkits have been deprecated. The base `Axes` +classes provide the same functionality to all subclasses, thus these mixins are +no longer necessary. Related functions have also been deprecated. Specifically: + +* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxesBase``: no specific + replacement; use any other ``Axes``-derived class directly instead. +* ``mpl_toolkits.axes_grid1.axes_divider.locatable_axes_factory``: no specific + replacement; use any other ``Axes``-derived class directly instead. +* ``mpl_toolkits.axes_grid1.axes_divider.Axes``: use + `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly. +* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxes``: use + `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly. +* ``mpl_toolkits.axisartist.axes_divider.Axes``: use + `mpl_toolkits.axisartist.axislines.Axes` directly. +* ``mpl_toolkits.axisartist.axes_divider.LocatableAxes``: use + `mpl_toolkits.axisartist.axislines.Axes` directly. + +Removals +-------- + +Hold machinery +`````````````` + +Setting or unsetting ``hold`` (deprecated in version 2.1) has now +been completely removed. Matplotlib now always behaves as if ``hold=True``. +To clear an axes you can manually use :meth:`~.axes.Axes.cla()`, +or to clear an entire figure use :meth:`~.figure.Figure.clf()`. + + +Removal of deprecated backends +`````````````````````````````` + +Deprecated backends have been removed: + +- GTKAgg +- GTKCairo +- GTK +- GDK + + +Deprecated APIs +``````````````` + +The following deprecated API elements have been removed: + +- The deprecated methods ``knownfailureif`` and ``remove_text`` have been removed + from :mod:`matplotlib.testing.decorators`. +- The entire contents of ``testing.noseclasses`` have also been removed. +- ``matplotlib.checkdep_tex``, ``matplotlib.checkdep_xmllint`` +- ``backend_bases.IdleEvent`` +- ``cbook.converter``, ``cbook.tostr``, ``cbook.todatetime``, ``cbook.todate``, + ``cbook.tofloat``, ``cbook.toint``, ``cbook.unique``, + ``cbook.is_string_like``, ``cbook.is_sequence_of_strings``, + ``cbook.is_scalar``, ``cbook.soundex``, ``cbook.dict_delall``, + ``cbook.get_split_ind``, ``cbook.wrap``, ``cbook.get_recursive_filelist``, + ``cbook.pieces``, ``cbook.exception_to_str``, ``cbook.allequal``, + ``cbook.alltrue``, ``cbook.onetrue``, ``cbook.allpairs``, ``cbook.finddir``, + ``cbook.reverse_dict``, ``cbook.restrict_dict``, ``cbook.issubclass_safe``, + ``cbook.recursive_remove``, ``cbook.unmasked_index_ranges``, + ``cbook.Null``, ``cbook.RingBuffer``, ``cbook.Sorter``, ``cbook.Xlator``, +- ``font_manager.weight_as_number``, ``font_manager.ttfdict_to_fnames`` +- ``pyplot.colors``, ``pyplot.spectral`` +- ``rcsetup.validate_negative_linestyle``, + ``rcsetup.validate_negative_linestyle_legacy``, +- ``testing.compare.verifiers``, ``testing.compare.verify`` +- ``testing.decorators.knownfailureif``, + ``testing.decorators.ImageComparisonTest.remove_text`` +- ``tests.assert_str_equal``, ``tests.test_tinypages.file_same`` +- ``texmanager.dvipng_hack_alpha``, +- ``_AxesBase.axesPatch``, ``_AxesBase.set_color_cycle``, + ``_AxesBase.get_cursor_props``, ``_AxesBase.set_cursor_props`` +- ``_ImageBase.iterpnames`` +- ``FigureCanvasBase.start_event_loop_default``; +- ``FigureCanvasBase.stop_event_loop_default``; +- ``Figure.figurePatch``, +- ``FigureCanvasBase.dynamic_update``, ``FigureCanvasBase.idle_event``, + ``FigureCanvasBase.get_linestyle``, ``FigureCanvasBase.set_linestyle`` +- ``FigureCanvasQTAggBase`` +- ``FigureCanvasQTAgg.blitbox`` +- ``FigureCanvasTk.show`` (alternative: ``FigureCanvasTk.draw``) +- ``FigureManagerTkAgg`` (alternative: ``FigureManagerTk``) +- ``NavigationToolbar2TkAgg`` (alternative: ``NavigationToolbar2Tk``) +- ``backend_wxagg.Toolbar`` (alternative: ``backend_wxagg.NavigationToolbar2WxAgg``) +- ``RendererAgg.debug()`` +- passing non-numbers to ``EngFormatter.format_eng`` +- passing ``frac`` to ``PolarAxes.set_theta_grids`` +- any mention of idle events + +The following API elements have been removed: + +- ``backend_cairo.HAS_CAIRO_CFFI`` +- ``sphinxext.sphinx_version`` + + +Proprietary sphinx directives +````````````````````````````` + +The matplotlib documentation used the proprietary sphinx directives +`.. htmlonly::`, and `.. latexonly::`. These have been replaced with the +standard sphinx directives `.. only:: html` and `.. only:: latex`. This +change will not affect any users. Only downstream package maintainers, who +have used the proprietary directives in their docs, will have to switch to the +sphinx directives. + + +lib/mpl_examples symlink +```````````````````````` + +The symlink from lib/mpl_examples to ../examples has been removed. +This is not installed as an importable package and should not affect +end users, however this may require down-stream packagers to adjust. +The content is still available top-level examples directory. diff --git a/doc/api/next_api_changes/2018-02-09-ES.rst b/doc/api/next_api_changes/2018-02-09-ES.rst deleted file mode 100644 index c4c7ccd40da4..000000000000 --- a/doc/api/next_api_changes/2018-02-09-ES.rst +++ /dev/null @@ -1,19 +0,0 @@ -Deprecation of ``LocatableAxes`` in toolkits --------------------------------------------- - -The ``LocatableAxes`` classes in toolkits have been deprecated. The base `Axes` -classes provide the same functionality to all subclasses, thus these mixins are -no longer necessary. Related functions have also been deprecated. Specifically: - -* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxesBase``: no specific - replacement; use any other ``Axes``-derived class directly instead. -* ``mpl_toolkits.axes_grid1.axes_divider.locatable_axes_factory``: no specific - replacement; use any other ``Axes``-derived class directly instead. -* ``mpl_toolkits.axes_grid1.axes_divider.Axes``: use - `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly. -* ``mpl_toolkits.axes_grid1.axes_divider.LocatableAxes``: use - `mpl_toolkits.axes_grid1.mpl_axes.Axes` directly. -* ``mpl_toolkits.axisartist.axes_divider.Axes``: use - `mpl_toolkits.axisartist.axislines.Axes` directly. -* ``mpl_toolkits.axisartist.axes_divider.LocatableAxes``: use - `mpl_toolkits.axisartist.axislines.Axes` directly. diff --git a/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst b/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst deleted file mode 100644 index e2c9e3fb693c..000000000000 --- a/doc/api/next_api_changes/2018-02-15-AL-deprecations.rst +++ /dev/null @@ -1,59 +0,0 @@ -Deprecations ------------- -The following modules are deprecated: - -- :mod:`matplotlib.compat.subprocess`. This was a python 2 workaround, but all - the functionality can now be found in the python 3 standard library - :mod:`subprocess`. -- :mod:`matplotlib.backends.wx_compat`. Python 3 is only compatible with - wxPython 4, so support for wxPython 3 or earlier can be dropped. - -The following classes, methods, functions, and attributes are deprecated: - -- ``RcParams.msg_depr``, ``RcParams.msg_depr_ignore``, - ``RcParams.msg_depr_set``, ``RcParams.msg_obsolete``, - ``RcParams.msg_backend_obsolete``, -- ``afm.parse_afm``, -- ``backend_pdf.PdfFile.texFontMap``, -- ``backend_pgf.get_texcommand``, -- ``backend_ps.get_bbox``, -- ``backend_qt5.FigureCanvasQT.keyAutoRepeat`` (directly check - ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to - handle autorepeated key presses). -- ``backend_qt5.error_msg_qt``, ``backend_qt5.exception_handler``, -- ``backend_wx.FigureCanvasWx.macros``, -- ``backends.pylab_setup``, -- ``cbook.GetRealpathAndStat``, ``cbook.Locked``, -- ``cbook.is_numlike`` (use ``isinstance(..., numbers.Number)`` instead), - ``cbook.listFiles``, ``cbook.unicode_safe``, -- ``container.Container.set_remove_method``, -- ``contour.ContourLabeler.cl``, ``.cl_xy``, and ``.cl_cvalues``, -- ``dates.DateFormatter.strftime_pre_1900``, ``dates.DateFormatter.strftime``, -- ``font_manager.TempCache``, -- ``image._ImageBase.iterpnames``, use the ``interpolation_names`` property - instead. (this affects classes that inherit from ``_ImageBase`` including - :class:`FigureImage`, :class:`BboxImage`, and :class:`AxesImage`), -- ``mathtext.unichr_safe`` (use ``chr`` instead), -- ``patches.Polygon.xy``, -- ``table.Table.get_child_artists`` (use ``get_children`` instead), -- ``testing.compare.ImageComparisonTest``, ``testing.compare.compare_float``, -- ``testing.decorators.CleanupTest``, - ``testing.decorators.skip_if_command_unavailable``, -- ``FigureCanvasQT.keyAutoRepeat`` (directly check - ``event.guiEvent.isAutoRepeat()`` in the event handler to decide whether to - handle autorepeated key presses). -- ``texmanager.dvipng_hack_alpha``, -- ``text.Annotation.arrow``, -- ``textpath.TextToPath.tex_font_map``, - -The following rcParams are deprecated: -- ``examples.directory`` (use ``datapath`` instead), -- ``pgf.debug`` (the pgf backend relies on logging), -- ``text.latex.unicode``, - -The following keyword arguments are deprecated: -- passing ``verts`` to ``Axes.scatter`` (use ``marker`` instead), -- passing ``obj_type`` to ``cbook.deprecated``, - -The following call signatures are deprecated: -- passing a ``wx.EvtHandler`` as first argument to ``backend_wx.TimerWx``, diff --git a/doc/api/next_api_changes/2018-04-29-JMK.rst b/doc/api/next_api_changes/2018-04-29-JMK.rst deleted file mode 100644 index d25c74062c16..000000000000 --- a/doc/api/next_api_changes/2018-04-29-JMK.rst +++ /dev/null @@ -1,20 +0,0 @@ -`.matplotlib.Axes.get_tightbbox` now includes all artists ---------------------------------------------------------- - -Layout tools like `.Figure.tight_layout`, ``constrained_layout``, -and ``fig.savefig('fname.png', bbox_inches="tight")`` use -`.matplotlib.Axes.get_tightbbox` to determine the bounds of each axes on -a figure and adjust spacing between axes. - -In Matplotlib 2.2 ``get_tightbbox`` started to include legends made on the -axes, but still excluded some other artists, like text that may overspill an -axes. For Matplotlib 3.0, *all* artists are now included in the bounding box. - -This new default may be overridden in either of two ways: - -1. Make the artist to be excluded a child of the figure, not the axes. E.g., - call ``fig.legend()`` instead of ``ax.legend()`` (perhaps using - `~.matplotlib.Axes.get_legend_handles_labels` to gather handles and labels - from the parent axes). -2. If the artist is a child of the axes, set the artist property - ``artist.set_in_layout(False)``. diff --git a/doc/api/next_api_changes/2018-05-06-AL-callbackregistry.rst b/doc/api/next_api_changes/2018-05-06-AL-callbackregistry.rst deleted file mode 100644 index afbbb76b309f..000000000000 --- a/doc/api/next_api_changes/2018-05-06-AL-callbackregistry.rst +++ /dev/null @@ -1,6 +0,0 @@ -`CallbackRegistry` now stores callbacks using stdlib's `WeakMethod`\s -````````````````````````````````````````````````````````````````````` - -In particular, this implies that ``CallbackRegistry.callbacks[signal]`` is now -a mapping of callback ids to `WeakMethod`\s (i.e., they need to be first called -with no arguments to retrieve the method itself). diff --git a/doc/api/next_api_changes/2018-05-15-AL.rst b/doc/api/next_api_changes/2018-05-15-AL.rst deleted file mode 100644 index 82422ec5500e..000000000000 --- a/doc/api/next_api_changes/2018-05-15-AL.rst +++ /dev/null @@ -1,8 +0,0 @@ -Changes regarding the text.latex.unicode rcParam -```````````````````````````````````````````````` - -The rcParam now defaults to True and is deprecated (i.e., in future versions -of Maplotlib, unicode input will always be supported). - -Moreover, the underlying implementation now uses ``\usepackage[utf8]{inputenc}`` -instead of ``\usepackage{ucs}\usepackage[utf8x]{inputenc}``. diff --git a/doc/api/next_api_changes/2018-06-01-PG-pytz-ectomy.rst b/doc/api/next_api_changes/2018-06-01-PG-pytz-ectomy.rst deleted file mode 100644 index ebaa2f620648..000000000000 --- a/doc/api/next_api_changes/2018-06-01-PG-pytz-ectomy.rst +++ /dev/null @@ -1,4 +0,0 @@ -Removed ``pytz`` as a dependency --------------------------------- - -Since ``dateutil`` and ``pytz`` both provide time zones, and matplotlib already depends on ``dateutil``, matplotlib will now use ``dateutil`` time zones internally and drop the redundant dependency on ``pytz``. While ``dateutil`` time zones are preferred (and currently recommended in the Python documentation), the explicit use of ``pytz`` zones is still supported. diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst index 2c130030dded..b94db9de442c 100644 --- a/doc/users/whats_new.rst +++ b/doc/users/whats_new.rst @@ -22,6 +22,27 @@ revision, see the :ref:`github-stats`. next_whats_new/* +Improved default backend selection +---------------------------------- + +The default backend no longer must be set as part of the build +process. Instead, at run time, the builtin backends are tried in +sequence until one of them imports. + +Headless linux servers (identified by the DISPLAY env not being defined) +will not select a GUI backend. + +Cyclic colormaps +---------------- + +Two new colormaps named 'twilight' and 'twilight_shifted' have been +added. These colormaps start and end on the same color, and have two +symmetric halves with equal lightness, but diverging color. Since they +wrap around, they are a good choice for cyclic data such as phase +angles, compass directions, or time of day. Like *viridis* and +*cividis*, *twilight* is perceptually uniform and colorblind friendly. + + Ability to scale axis by a fixed order of magnitude --------------------------------------------------- @@ -76,16 +97,6 @@ This has been changed so that the number of ticks is now responsive to how large the colorbar is. -Cyclic colormaps ----------------- - -Two new colormaps named 'twilight' and 'twilight_shifted' have been added. -These colormaps start and end on the same color, and have two -symmetric halves with equal lightness, but diverging color. Since they -wrap around, they are a good choice for cyclic data such as phase -angles, compass directions, or time of day. Like *viridis*, *twilight* is -perceptually uniform and colorblind friendly. - Don't automatically rename duplicate file names ----------------------------------------------- @@ -228,15 +239,6 @@ This new method may be useful for adding artists to figures without axes or to easily position static elements in figure coordinates. -Improved default backend selection ----------------------------------- - -The default backend no longer must be set as part of the build -process. Instead, at run time, the builtin backends are tried in -sequence until one of them imports. - -Headless linux servers (identified by the DISPLAY env not being defined) -will not select a GUI backend. Return type of ArtistInspector.get_aliases changed