@@ -2681,17 +2681,32 @@ def polar(*args, **kwargs) -> list[Line2D]:
2681
2681
2682
2682
call signature::
2683
2683
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.
2688
2696
"""
2689
2697
# If an axis already exists, check if it has a polar projection
2690
2698
if gcf ().get_axes ():
2691
2699
ax = gca ()
2692
2700
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
+ )
2695
2710
else :
2696
2711
ax = axes (projection = "polar" )
2697
2712
return ax .plot (* args , ** kwargs )
0 commit comments