8000 Merge pull request #28946 from timhoffm/mnt-pyplot-polar · matplotlib/matplotlib@bda958a · GitHub
[go: up one dir, main page]

Skip to content

Commit bda958a

Browse files
authored
Merge pull request #28946 from timhoffm/mnt-pyplot-polar
MNT: Deprecate plt.polar() with an existing non-polar Axes
2 parents b77767f + fc85a12 commit bda958a

File tree

2 files changed

+27
-6
lines changed

2 files changed

+27
-6
lines changed
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Calling ``pyplot.polar()`` with an existing non-polar Axes
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
This currently plots the data into the non-polar Axes, ignoring
5+
the "polar" intention. This usage scenario is deprecated and
6+
will raise an error in the future.

lib/matplotlib/pyplot.py

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2681,17 +2681,32 @@ def polar(*args, **kwargs) -> list[Line2D]:
26812681
26822682
call signature::
26832683
2684-
polar(theta, r, **kwargs)
2685-
2686-
Multiple *theta*, *r* arguments are supported, with format strings, as in
2687-
`plot`.
2684+
polar(theta, r, [fmt], **kwargs)
2685+
2686+
This is a convenience wrapper around `.pyplot.plot`. It ensures that the
2687+
current Axes is polar (or creates one if needed) and then passes all parameters
2688+
to ``.pyplot.plot``.
2689+
2690+
.. note::
2691+
When making polar plots using the :ref:`pyplot API <pyplot_interface>`,
2692+
``polar()`` should typically be the first command because that makes sure
2693+
a polar Axes is created. Using other commands such as ``plt.title()``
2694+
before this can lead to the implicit creation of a rectangular Axes, in which
2695+
case a subsequent ``polar()`` call will fail.
26882696
"""
26892697
# If an axis already exists, check if it has a polar projection
26902698
if gcf().get_axes():
26912699
ax = gca()
26922700
if not isinstance(ax, PolarAxes):
2693-
_api.warn_external('Trying to create polar plot on an Axes '
2694-
'that does not have a polar projection.')
2701+
_api.warn_deprecated(
2702+
"3.10",
2703+
message="There exists a non-polar current Axes. Therefore, the "
2704+
"resulting plot from 'polar()' is non-polar. You likely "
2705+
"should call 'polar()' before any other pyplot plotting "
2706+
"commands. "
2707+
"Support for this scenario is deprecated in %(since)s and "
2708+
"will raise an error in %(removal)s"
2709+
)
26952710
else:
26962711
ax = axes(projection="polar")
26972712
return ax.plot(*args, **kwargs)

0 commit comments

Comments
 (0)
0