8000 MNT: Error out if plt.polar() is called with an existing non-polar Axes · matplotlib/matplotlib@c2be3e8 · GitHub
[go: up one dir, main page]

Skip to content

Commit c2be3e8

Browse files
committed
MNT: Error out if plt.polar() is called with an existing non-polar Axes
Before, we only issued a warning. But we clearly cannot fulfill the intention of a polar plot and therefore we should error out instead of just warn. Also document that `polar()` should typically be called first to prevent having a non-polar Axes already created.
1 parent 60458da commit c2be3e8

File tree

1 file changed

+17
-6
lines changed

1 file changed

+17
-6
lines changed

lib/matplotlib/pyplot.py

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2686,17 +2686,28 @@ def polar(*args, **kwargs) -> list[Line2D]:
26862686
26872687
call signature::
26882688
2689-
polar(theta, r, **kwargs)
2690-
2691-
Multiple *theta*, *r* arguments are supported, with format strings, as in
2692-
`plot`.
2689+
polar(theta, r, [fmt], **kwargs)
2690+
2691+
This is a convenience wrapper around `.pyplot.plot`. It ensures that the
2692+
current Axes is polar (or creates one if needed) and then passes all parameters
2693+
to ``.pyplot.plot``.
2694+
2695+
.. note::
2696+
When making polar plots using the :ref:`pyplot API <pyplot_interface>`,
2697+
``polar()`` should typically be the first command because that makes sure
2698+
a polar Axes is created. Using other commands such as ``plt.title()``
2699+
before can lead to the implicit creation of a rectangular Axes, in which
2700+
case a subsequent ``polar()`` call will fail.
26932701
"""
26942702
# If an axis already exists, check if it has a polar projection
26952703
if gcf().get_axes():
26962704
ax = gca()
26972705
if not isinstance(ax, PolarAxes):
2698-
_api.warn_external('Trying to create polar plot on an Axes '
2699-
'that does not have a polar projection.')
2706+
raise RuntimeError(
2707+
"There exists a non-polar current Axes. 'polar()' cannot plot "
2708+
"into this. You likely should call 'polar()' before any other "
2709+
"plotting commands."
2710+
)
27002711
else:
27012712
ax = axes(projection="polar")
27022713
return ax.plot(*args, **kwargs)

0 commit comments

Comments
 (0)
0