Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 05d7d48

Browse files
committed
Finish re-ordering API docs
1 parent 6cbbc85 commit 05d7d48

File tree

1 file changed

+125
-149
lines changed

1 file changed

+125
-149
lines changed

doc/api/prev_api_changes/api_changes_3.1.0.rst

Lines changed: 125 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ API Changes for 3.1.0
88

99
``pgi`` support dropped
1010
-----------------------
11-
1211
Support for ``pgi`` in the GTK3 backends has been dropped. ``pgi`` is
1312
an alternative implementation to ``PyGObject``. ``PyGObject`` should
1413
be used instead.
@@ -46,9 +45,16 @@ instead of ``\usepackage{ucs}\usepackage[utf8x]{inputenc}``.
4645
Behavior changes
4746
----------------
4847

48+
49+
Matplotlib.use
50+
~~~~~~~~~~~~~~
51+
Switching backends via `matplotlib.use` is now allowed by default,
52+
regardless of whether `matplotlib.pyplot` has been imported. If the user
53+
tries to switch from an already-started interactive backend to a different
54+
interactive backend, an ImportError will be raised.
55+
4956
mplot3d auto-registration
5057
~~~~~~~~~~~~~~~~~~~~~~~~~
51-
5258
mplot3d is always registered by default now. It is not necessary to import
5359
mplot3d to create 3d axes with ``fig.add_subplot(111, projection="3d")``.
5460

@@ -86,14 +92,12 @@ nothing; this now is equivalent to calling ``add_subplot(111)`` instead.
8692

8793
`~Axes.bxp` and rcparams
8894
~~~~~~~~~~~~~~~~~~~~~~~~
89-
9095
`~Axes.bxp` now respects :rc:`boxplot.boxprops.linewidth` even when
9196
*patch_artist* is set.
9297
Previously, when the *patch_artist* parameter was set, `~Axes.bxp` would ignore
9398
:rc:`boxplot.boxprops.linewidth`. This was an oversight -- in particular,
9499
`~Axes.boxplot` did not ignore it.
95100

96-
97101
Major/minor tick collisions
98102
~~~~~~~~~~~~~~~~~~~~~~~~~~~
99103
Minor ticks that collide with major ticks are now always hidden.
@@ -317,12 +321,99 @@ standard environment variables ``CFLAGS``/``LDFLAGS`` on Linux or OSX, or
317321

318322
See details in :file:`INSTALL.rst`.
319323

324+
Setting artist properties twice or more in the same call
325+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
326+
Setting the same artist property multiple time via aliases is deprecated.
327+
Previously, code such as ``plt.plot([0, 1], c="red", color="blue")`` would
328+
emit a warning indicating that ``c`` and ``color`` are aliases of one another,
329+
and only keep the ``color`` kwarg. This behavior has been deprecated; in a
330+
future version, this will raise a TypeError, similar to Python's behavior when
331+
a keyword argument is passed twice (``plt.plot([0, 1], c="red", c="blue")``).
332+
333+
This warning is raised by `~.cbook.normalize_kwargs`.
334+
335+
Path code types
336+
~~~~~~~~~~~~~~~
337+
Path code types like ``Path.MOVETO`` are now ``np.uint8`` instead of ``int``
338+
``Path.STOP``, ``Path.MOVETO``, ``Path.LINETO``, ``Path.CURVE3``,
339+
``Path.CURVE4`` and ``Path.CLOSEPOLY`` are now of the type ``Path.code_type``
340+
(``np.uint8`` by default) instead of plain ``int``. This makes their type
341+
match the array value type of the ``Path.codes`` array.
342+
343+
LaTeX code in matplotlibrc file
344+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345+
Previously, the rc file keys ``pgf.preamble`` and ``text.latex.preamble`` were
346+
parsed using commmas as separators. This would break valid LaTeX code, such as::
347+
348+
\usepackage[protrusion=true, expansion=false]{microtype}
349+
350+
The parsing has been modified to pass the complete line to the LaTeX system,
351+
keeping all commas. Passing a list of strings from within a Python script still
352+
works as it used to. Passing a list containing non-strings now fails, instead
353+
of coercing the results to strings.
354+
355+
`matplotlib.axes.Axes.spy`
356+
~~~~~~~~~~~~~~~~~~~~~~~~~~
357+
The method `matplotlib.axes.Axes.spy` now raises a TypeError for the keyword
358+
arguments 'interpolation' and 'linestyle' instead of silently ignoring them.
359+
360+
Furthermore, `matplotlib.axes.Axes.spy` spy does now allow for an 'extent'
361+
argument (was silently ignored so far).
362+
363+
A bug with `spy(..., origin='lower') is fixed: So far this flipped the
364+
data but not the y-axis resulting in a mismatch between axes labels and
365+
actual data indices. Now, `origin='lower'` flips both the data and the y-axis
366+
labels.
367+
368+
Boxplot tick methods
369+
~~~~~~~~~~~~~~~~~~~~
370+
The ``manage_xticks`` parameter of `~Axes.boxplot` and `~Axes.bxp` has been
371+
renamed (with a deprecation period) to ``manage_ticks``, to take into account
372+
the fact that it manages either x or y ticks depending on the ``vert``
373+
parameter.
374+
375+
When ``manage_ticks`` is True (the default), these methods now attempt to take
376+
previously drawn boxplots into account when setting the axis limits, ticks, and
377+
tick labels.
378+
379+
MouseEvents
380+
~~~~~~~~~~~
381+
MouseEvents now include the event name in their ``str()``.
382+
Previously they contained the prefix "MPL MouseEvent".
383+
384+
RGBA buffer return type
385+
~~~~~~~~~~~~~~~~~~~~~~~
386+
`FigureCanvasAgg.buffer_rgba` and `RendererAgg.buffer_rgba` now return a memoryview
387+
The ``buffer_rgba`` method now allows direct access to the renderer's
388+
underlying buffer (as a ``(m, n, 4)``-shape memoryview) rather than copying the
389+
data to a new bytestring. This is consistent with the behavior on Py2, where a
390+
buffer object was returned.
391+
392+
393+
matplotlib.font_manager.win32InstalledFonts return type
394+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395+
`matplotlib.font_manager.win32InstalledFonts` returns an empty list instead
396+
of None if no fonts are found.
397+
398+
``Axes.fmt_xdata`` and ``Axes.fmt_ydata`` error handling
399+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
400+
Previously, if the user provided a ``fmt_xdata`` or ``fmt_ydata`` function that
401+
raised a TypeError (or set them to a non-callable), the exception would be
402+
silently ignored and the default formatter be used instead. This is no longer
403+
the case; the exception is now propagated out.
320404

321405
Exception changes
322406
-----------------
323407
- `mpl_toolkits.axes_grid1.axes_size.GetExtentHelper` now raises `ValueError`
324408
for invalid directions instead of `KeyError`.
325409

410+
- Previously, subprocess failures in the animation framework would raise either
411+
in a `RuntimeError` or a `ValueError` depending on when the error occurred.
412+
They now raise a `subprocess.CalledProcessError` with attributes set as
413+
documented by the exception class.
414+
- In certain cases, Axes methods (and pyplot functions) used to raise a
415+
RuntimeError if they were called with a ``data`` kwarg and otherwise mismatched
416+
arguments. They now raise a ``TypeError`` instead.
326417

327418
Removals
328419
--------
@@ -527,7 +618,6 @@ False (which was always broken). Passing True to mean "average" is deprecated.
527618

528619
Testing
529620
-------
530-
531621
The ``--no-network`` flag to ``tests.py`` has been removed (no test requires
532622
internet access anymore). If it is desired to disable internet access both for
533623
old and new versions of Matplotlib, use ``tests.py -m 'not network'`` (which is
@@ -543,12 +633,10 @@ Dependency changes
543633

544634
numpy
545635
~~~~~
546-
547636
Matplotlib 3.1 now requires numpy>=1.11.
548637

549638
ghostscript
550639
~~~~~~~~~~~
551-
552640
Support for ghostscript 8.60 (released in 2007) has been removed. The oldest
553641
supported version of ghostscript is now 9.0 (released in 2010).
554642

@@ -567,8 +655,6 @@ Deprecations
567655
``"\N{CIRCLED LATIN CAPITAL LETTER A}"`` or ``"\u24b6"``) instead.
568656
- Support for setting :rc:`mathtext.default` to circled is deprecated.
569657

570-
571-
572658
Signature deprecations
573659
----------------------
574660
The following signature related behaviours are deprecated:
@@ -622,6 +708,11 @@ Changes in parameter names
622708
--------------------------
623709

624710
- The ``arg`` parameter to `matplotlib.use` has been renamed to ``backend``.
711+
712+
This will only affect cases where that parameter has been set
713+
as a keyword argument. The common usage pattern as a positional argument
714+
``matplotlib.use('Qt5Agg')`` is not affected.
715+
625716
- The ``normed`` parameter to `Axes.hist2d` has been renamed to ``density``.
626717
- The ``s`` parameter to `Annotation` (and indirectly `Axes.annotation`) has
627718
been renamed to ``text``.
@@ -633,12 +724,15 @@ Changes in parameter names
633724
``tolerance``.
634725

635726
In each case, the old parameter name remains supported (it cannot be used
636-
simultaneously with the new name), but suppport for it will be dropped in
727+
simultaneously with the new name), but support for it will be dropped in
637728
Matplotlib 3.3.
638729

639-
640730
Class/method/attribute deprecations
641731
-----------------------------------
732+
Support for custom backends that do not provide a ``set_hatch_color`` method is
733+
deprecated. We suggest that custom backends let their ``GraphicsContext``
734+
class inherit from `GraphicsContextBase`, to at least provide stubs for all
735+
required methods.
642736

643737
- ``Spine.is_frame_like``
644738

@@ -827,6 +921,9 @@ Use ``isinstance(..., collections.abc.Hashable)`` instead.
827921
This has always returned None instead of the requested radius.
828922

829923
- The ``MATPLOTLIBDATA`` environment variable
924+
- ``Axis.iter_ticks``
925+
926+
This only served as a helper to the private ``Axis._update_ticks``
830927

831928
Undeprecations
832929
--------------
@@ -836,89 +933,29 @@ The following API elements have bee un-deprecated:
836933
- xmin, xmax kwargs to ``set_xlim`` and ymin, ymax kwargs to ``set_ylim``
837934

838935

936+
New features
937+
------------
938+
839939
`Text` now has a ``c`` alias for the ``color`` property
840-
-------------------------------------------------------
940+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
841941
For consistency with `Line2D`, the `Text` class has gained the ``c``
842942
alias for the ``color`` property. For example, one can now write
843943
``ax.text(.5, .5, "foo", c="red")``.
844944

845-
Setting the same artist property multiple time via aliases is deprecated
846-
------------------------------------------------------------------------
847-
Previously, code such as ``plt.plot([0, 1], c="red", color="blue")`` would
848-
emit a warning indicating that ``c`` and ``color`` are aliases of one another,
849-
and only keep the ``color`` kwarg. This behavior has been deprecated; in a
850-
future version, this will raise a TypeError, similar to Python's behavior when
851-
a keyword argument is passed twice (``plt.plot([0, 1], c="red", c="blue")``).
852-
853-
This warning is raised by `~.cbook.normalize_kwargs`.
854-
855-
Boxplot tick methods
856-
--------------------
857-
The ``manage_xticks`` parameter of `~Axes.boxplot` and `~Axes.bxp` has been
858-
renamed (with a deprecation period) to ``manage_ticks``, to take into account
859-
the fact that it manages either x or y ticks depending on the ``vert``
860-
parameter.
861-
862-
When ``manage_ticks`` is True (the default), these methods now attempt to take
863-
previously drawn boxplots into account when setting the axis limits, ticks, and
864-
tick labels.
865-
866-
`matplotlib.use` parameter change
867-
---------------------------------
868-
The first parameter of `matplotlib.use` has been renamed from *arg* to
869-
*backend*. This will only affect cases where that parameter has been set
870-
as a keyword argument. The common usage pattern as a positional argument
871-
``matplotlib.use('Qt5Agg')`` is not affected.
872-
873-
874-
Exception on failing animations changed
875-
---------------------------------------
876-
Previously, subprocess failures in the animation framework would raise either
877-
in a `RuntimeError` or a `ValueError` depending on when the error occurred.
878-
They now raise a `subprocess.CalledProcessError` with attributes set as
879-
documented by the exception class.
880-
881-
MouseEvents now include the event name in their ``str()``
882-
---------------------------------------------------------
883-
884-
Previously they contained the prefix "MPL MouseEvent".
885-
886-
Matplotlib.use now has an ImportError for interactive backend
887-
-------------------------------------------------------------
888-
Switching backends via `matplotlib.use` is now allowed by default,
889-
regardless of whether `matplotlib.pyplot` has been imported. If the user
890-
tries to switch from an already-started interactive backend to a different
891-
interactive backend, an ImportError will be raised.
892-
893-
894-
Path code types like ``Path.MOVETO`` are now ``np.uint8`` instead of ``int``
895-
----------------------------------------------------------------------------
896-
``Path.STOP``, ``Path.MOVETO``, ``Path.LINETO``, ``Path.CURVE3``,
897-
``Path.CURVE4`` and ``Path.CLOSEPOLY`` are now of the type ``Path.code_type``
898-
(``np.uint8`` by default) instead of plain ``int``. This makes their type
899-
match the array value type of the ``Path.codes`` array.
900-
901-
Allow "real" LaTeX code for ``pgf.preamble`` and ``text.latex.preamble`` in matplotlib rc file
902-
----------------------------------------------------------------------------------------------
903-
Previously, the rc file keys ``pgf.preamble`` and ``text.latex.preamble`` were parsed using commmas as separators. This would break valid LaTeX code, such as::
904-
905-
\usepackage[protrusion=true, expansion=false]{microtype}
906-
907-
The parsing has been modified to pass the complete line to the LaTeX system,
908-
keeping all commas.
909-
910-
Passing a list of strings from within a Python script still works as it used to.
911-
912-
Passing a list containing non-strings now fails, instead of coercing the results to strings.
913-
914-
matplotlib.font_manager.win32InstalledFonts return value
915-
--------------------------------------------------------
916-
`matplotlib.font_manager.win32InstalledFonts` returns an empty list instead
917-
of None if no fonts are found.
945+
``Cn`` colors now support ``n>=10``
946+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
947+
It is now possible to go beyond the tenth color in the property cycle using
948+
``Cn`` syntax, e.g. ``plt.plot([1, 2], color="C11")`` now uses the 12th color
949+
in the cycle.
918950

951+
Note that previously, a construct such as ``plt.plot([1, 2], "C11")`` would be
952+
interpreted as a request to use color ``C1`` and marker ``1`` (an "inverted Y").
953+
To obtain such a plot, one should now use ``plt.plot([1, 2], "1C1")`` (so that
954+
the first "1" gets correctly interpreted as a marker specification), or, more
955+
explicitly, ``plt.plot([1, 2], marker="1", color="C1")``.
919956

920957
New `Formatter.format_ticks` method
921-
-----------------------------------
958+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
922959
The `Formatter` class gained a new `~Formatter.format_ticks` method, which
923960
takes the list of all tick locations as a single argument and returns the list
924961
of all formatted values. It is called by the axis tick handling code and, by
@@ -933,63 +970,6 @@ updated to use `~Formatter.format_ticks`.
933970
subclasses for which the formatting of a tick value depends on other tick
934971
values, such as `ConciseDateFormatter`.
935972

936-
937-
``Cn`` colors now support ``n>=10``
938-
-----------------------------------
939-
It is now possible to go beyond the tenth color in the property cycle using
940-
``Cn`` syntax, e.g. ``plt.plot([1, 2], color="C11")`` now uses the 12th color
941-
in the cycle.
942-
943-
Note that previously, a construct such as ``plt.plot([1, 2], "C11")`` would be
944-
interpreted as a request to use color ``C1`` and marker ``1`` (an "inverted Y").
945-
To obtain such a plot, one should now use ``plt.plot([1, 2], "1C1")`` (so that
946-
the first "1" gets correctly interpreted as a marker specification), or, more
947-
explicitly, ``plt.plot([1, 2], marker="1", color="C1")``.
948-
949-
950-
Changes to the internal tick handling API
951-
-----------------------------------------
952-
``Axis.iter_ticks`` (which only served as a helper to the private
953-
``Axis._update_ticks``) is deprecated.
954-
955-
The signature of the (private) ``Axis._update_ticks`` has been changed to not
956-
take the renderer as argument anymore (that argument is unused).
957-
958-
Deprecations
959-
------------
960-
Support for custom backends that do not provide a ``set_hatch_color`` method is
961-
deprecated. We suggest that custom backends let their ``GraphicsContext``
962-
class inherit from `GraphicsContextBase`, to at least provide stubs for all
963-
required methods.
964-
965-
The fields ``Artist.aname`` and ``Axes.aname`` are deprecated. Please use
966-
967-
``isinstance()`` or ``__class__.__name__`` checks instead.``Axes.fmt_xdata`` and ``Axes.fmt_ydata`` no longer ignore TypeErrors raised by a user-provided formatter
968-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
969-
Previously, if the user provided a ``fmt_xdata`` or ``fmt_ydata`` function that
970-
raised a TypeError (or set them to a non-callable), the exception would be
971-
silently ignored and the default formatter be used instead. This is no longer
972-
the case; the exception is now propagated out.
973-
974-
Axes methods now raise TypeError instead of RuntimeError on mismatched calls
975-
----------------------------------------------------------------------------
976-
In certain cases, Axes methods (and pyplot functions) used to raise a
977-
RuntimeError if they were called with a ``data`` kwarg and otherwise mismatched
978-
arguments. They now raise a ``TypeError`` instead.
979-
980-
Changes to `matplotlib.axes.Axes.spy`
981-
-------------------------------------
982-
The method `matplotlib.axes.Axes.spy` now raises a TypeError for the keyword
983-
arguments 'interpolation' and 'linestyle' instead of silently ignoring them.
984-
985-
Furthermore, `matplotlib.axes.Axes.spy` spy does now allow for an 'extent'
986-
argument (was silently ignored so far).
987-
988-
A bug with `spy(..., origin='lower') is fixed: So far this flipped the
989-
data but not the y-axis resulting in a mismatch between axes labels and
990-
actual data indices. Now, `origin='lower'` flips both the data and the y-axis
991-
labels.
992-
993973
Invalid inputs
994974
--------------
995975
Passing invalid locations to `legend` and `table` used to fallback on a default
@@ -1003,9 +983,5 @@ behavior is deprecated and will throw an exception in a future version.
1003983
Passing steps less than 1 or greater than 10 to `MaxNLocator` used to result in
1004984
undefined behavior. It now throws a ValueError.
1005985

1006-
`FigureCanvasAgg.buffer_rgba` and `RendererAgg.buffer_rgba` now return a memoryview
1007-
-----------------------------------------------------------------------------------
1008-
The ``buffer_rgba`` method now allows direct access to the renderer's
1009-
underlying buffer (as a ``(m, n, 4)``-shape memoryview) rather than copying the
1010-
data to a new bytestring. This is consistent with the behavior on Py2, where a
1011-
buffer object was returned.
986+
The signature of the (private) ``Axis._update_ticks`` has been changed to not
987+
take the renderer as argument anymore (that argument is unused).

0 commit comments

Comments
 (0)