From fc85a127209e15d4f0afda1d0ff3a0b1a347fc11 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 7 Oct 2024 13:37:16 +0200
Subject: [PATCH] MNT: Deprecate plt.polar() 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.
---
 .../deprecations/28946-TH.rst                 |  6 +++++
 lib/matplotlib/pyplot.py                      | 27 ++++++++++++++-----
 2 files changed, 27 insertions(+), 6 deletions(-)
 create mode 100644 doc/api/next_api_changes/deprecations/28946-TH.rst

diff --git a/doc/api/next_api_changes/deprecations/28946-TH.rst b/doc/api/next_api_changes/deprecations/28946-TH.rst
new file mode 100644
index 000000000000..6a2f09108686
--- /dev/null
+++ b/doc/api/next_api_changes/deprecations/28946-TH.rst
@@ -0,0 +1,6 @@
+Calling ``pyplot.polar()`` with an existing non-polar Axes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This currently plots the data into the non-polar Axes, ignoring
+the "polar" intention. This usage scenario is deprecated and
+will raise an error in the future.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index 744eee0e4b9f..cacdaf04c1ec 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -2686,17 +2686,32 @@ def polar(*args, **kwargs) -> list[Line2D]:
 
     call signature::
 
-      polar(theta, r, **kwargs)
-
-    Multiple *theta*, *r* arguments are supported, with format strings, as in
-    `plot`.
+      polar(theta, r, [fmt], **kwargs)
+
+    This is a convenience wrapper around `.pyplot.plot`. It ensures that the
+    current Axes is polar (or creates one if needed) and then passes all parameters
+    to ``.pyplot.plot``.
+
+    .. note::
+        When making polar plots using the :ref:`pyplot API <pyplot_interface>`,
+        ``polar()`` should typically be the first command because that makes sure
+        a polar Axes is created. Using other commands such as ``plt.title()``
+        before this can lead to the implicit creation of a rectangular Axes, in which
+        case a subsequent ``polar()`` call will fail.
     """
     # If an axis already exists, check if it has a polar projection
     if gcf().get_axes():
         ax = gca()
         if not isinstance(ax, PolarAxes):
-            _api.warn_external('Trying to create polar plot on an Axes '
-                               'that does not have a polar projection.')
+            _api.warn_deprecated(
+                "3.10",
+                message="There exists a non-polar current Axes. Therefore, the "
+                        "resulting plot from 'polar()' is non-polar. You likely "
+                        "should call 'polar()' before any other pyplot plotting "
+                        "commands. "
+                        "Support for this scenario is deprecated in %(since)s and "
+                        "will raise an error in %(removal)s"
+            )
     else:
         ax = axes(projection="polar")
     return ax.plot(*args, **kwargs)