Deprecate toplevel mpl.text.get_rotation; normalize rotations early.

get_rotation had been made a toplevel function a long time ago to be
used in TextWithDash, which has now been removed, so there isn't much
justification to have it separate.  Also, note that while the toplevel
get_rotation's implementation also supported string-form of floats (see
test_text.test_get_rotation_string), this was not consistent with the
docstring, and, more importantly, it was not possible to set a Text's
rotation to e.g. "15." because Text.set_rotation() would first reject
that anyways.

Also, we can directly normalize angles in Text.set_rotation, rather than
doing it again and again in Text.get_rotation.  Again, this made the old
inconsistency (on supporting string-form floats) clearer.

Author: anntzer

doc/api/next_api_changes/deprecations/22539-AL.rst

@@ -0,0 +1,4 @@
+``matplotlib.text.get_rotation()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated with no replacement.  Copy the original implementation if
+needed.

lib/matplotlib/tests/test_text.py

@@ -345,33 +345,32 @@ def test_non_default_dpi(text):
 
 
 def test_get_rotation_string():
-    assert mpl.text.get_rotation('horizontal') == 0.
-    assert mpl.text.get_rotation('vertical') == 90.
-    assert mpl.text.get_rotation('15.') == 15.
+    assert Text(rotation='horizontal').get_rotation() == 0.
+    assert Text(rotation='vertical').get_rotation() == 90.
 
 
 def test_get_rotation_float():
     for i in [15., 16.70, 77.4]:
-        assert mpl.text.get_rotation(i) == i
+        assert Text(rotation=i).get_rotation() == i
 
 
 def test_get_rotation_int():
     for i in [67, 16, 41]:
-        assert mpl.text.get_rotation(i) == float(i)
+        assert Text(rotation=i).get_rotation() == float(i)
 
 
 def test_get_rotation_raises():
     with pytest.raises(ValueError):
-        mpl.text.get_rotation('hozirontal')
+        Text(rotation='hozirontal')
 
 
 def test_get_rotation_none():
-    assert mpl.text.get_rotation(None) == 0.0
+    assert Text(rotation=None).get_rotation() == 0.0
 
 
 def test_get_rotation_mod360():
     for i, j in zip([360., 377., 720+177.2], [0., 17., 177.2]):
-        assert_almost_equal(mpl.text.get_rotation(i), j)
+        assert_almost_equal(Text(rotation=i).get_rotation(), j)
 
 
 @pytest.mark.parametrize("ha", ["center", "right", "left"])

lib/matplotlib/text.py

@@ -23,7 +23,7 @@
 _log = logging.getLogger(__name__)
 
 
-# Extracted from Text's method to serve as a function
+@_api.deprecated("3.6")
 def get_rotation(rotation):
     """
     Return *rotation* normalized to an angle between 0 and 360 degrees.
@@ -240,13 +240,10 @@ def _get_multialignment(self):
     def get_rotation(self):
         """Return the text angle in degrees between 0 and 360."""
         if self.get_transform_rotates_text():
-            angle = get_rotation(self._rotation)
-            x, y = self.get_unitless_position()
-            angles = [angle, ]
-            pts = [[x, y]]
-            return self.get_transform().transform_angles(angles, pts).item(0)
+            return self.get_transform().transform_angles(
+                [self._rotation], [self.get_unitless_position()]).item(0)
         else:
-            return get_rotation(self._rotation)  # string_or_number -> number
+            return self._rotation
 
     def get_transform_rotates_text(self):
         """
@@ -1176,12 +1173,15 @@ def set_rotation(self, s):
             The rotation angle in degrees in mathematically positive direction
             (counterclockwise). 'horizontal' equals 0, 'vertical' equals 90.
         """
-        if (s is not None and
-                not isinstance(s, numbers.Real) and
-                s not in ['vertical', 'horizontal']):
+        if isinstance(s, numbers.Real):
+            self._rotation = float(s) % 360
+        elif cbook._str_equal(s, 'horizontal') or s is None:
+            self._rotation = 0.
+        elif cbook._str_equal(s, 'vertical'):
+            self._rotation = 90.
+        else:
             raise ValueError("rotation must be 'vertical', 'horizontal' or "
                              f"a number, not {s}")
-        self._rotation = s
         self.stale = True
 
     def set_transform_rotates_text(self, t):