matplotlib · tacaswell · Mar 31, 2019 · Mar 25, 2019
diff --git a/doc/api/next_api_changes/2019-03-27-AL.rst b/doc/api/next_api_changes/2019-03-27-AL.rst
@@ -0,0 +1,8 @@
+Deprecations
+````````````
+
+The `\mathcircled` mathtext command (which is not a real TeX command)
+is deprecated.  Directly use unicode characters (e.g.
+``"\N{CIRCLED LATIN CAPITAL LETTER A}"`` or ``"\u24b6"``) instead.
+
+Support for setting :rc:`mathtext.default` to circled is deprecated.
diff --git a/examples/text_labels_and_annotations/stix_fonts_demo.py b/examples/text_labels_and_annotations/stix_fonts_demo.py
@@ -8,9 +8,11 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
+
+circle123 = "\N{CIRCLED DIGIT ONE}\N{CIRCLED DIGIT TWO}\N{CIRCLED DIGIT THREE}"
+
 tests = [
-    r'$\mathcircled{123} \mathrm{\mathcircled{123}}'
-    r' \mathbf{\mathcircled{123}}$',
+    r'$%s \mathrm{%s} \mathbf{%s}$' % ((circle123,) * 3),
     r'$\mathsf{Sans \Omega} \mathrm{\mathsf{Sans \Omega}}'
     r' \mathbf{\mathsf{Sans \Omega}}$',
     r'$\mathtt{Monospace}$',
@@ -19,14 +21,12 @@
     r'$\mathrm{\mathbb{Blackboard \pi}}$',
     r'$\mathbf{\mathbb{Blackboard \pi}}$',
     r'$\mathfrak{Fraktur} \mathbf{\mathfrak{Fraktur}}$',
-    r'$\mathscr{Script}$']
+    r'$\mathscr{Script}$',
+]
 
 
-plt.figure(figsize=(8, (len(tests) * 1) + 2))
-plt.plot([0, 0], 'r')
-plt.axis([0, 3, -len(tests), 0])
-plt.yticks(-np.arange(len(tests)))
-for i, s in enumerate(tests):
-    plt.text(0.1, -i, s, fontsize=32)
+fig = plt.figure(figsize=(8, (len(tests) * 1) + 2))
+for i, s in enumerate(tests[::-1]):
+    fig.text(0, (i + .5) / len(tests), s, fontsize=32)
 
 plt.show()
diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py
@@ -2638,6 +2638,11 @@ def font(self):
 
         @font.setter
         def font(self, name):
+            if name == "circled":
+                cbook.warn_deprecated(
+                    "3.1", name="\\mathcircled", obj_type="mathtext command",
+                    alternative="unicode characters (e.g. '\\N{CIRCLED LATIN "
+                    "CAPITAL LETTER A}' or '\\u24b6')")
             if name in ('rm', 'it', 'bf'):
                 self.font_class = name
             self._font = name

diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -469,9 +469,19 @@ def validate_font_properties(s):
 validate_fontset = ValidateInStrings(
     'fontset',
     ['dejavusans', 'dejavuserif', 'cm', 'stix', 'stixsans', 'custom'])
-validate_mathtext_default = ValidateInStrings(
-    'default',
-    "rm cal it tt sf bf default bb frak circled scr regular".split())
+
+
+def validate_mathtext_default(s):
+    if s == "circled":
+        cbook.warn_deprecated(
+            "3.1", message="Support for setting the mathtext.default rcParam "
+            "to 'circled' is deprecated since %(since)s and will be removed "
+            "%(removal)s.")
+    return ValidateInStrings(
+        'default',
+        "rm cal it tt sf bf default bb frak circled scr regular".split())(s)
+
+
 _validate_alignment = ValidateInStrings(
     'alignment',
     ['center', 'top', 'bottom', 'baseline',

diff --git a/lib/matplotlib/tests/test_mathtext.py b/lib/matplotlib/tests/test_mathtext.py
@@ -163,14 +163,18 @@ def baseline_images(request, fontset, index):
     return ['%s_%s_%02d' % (request.param, fontset, index)]
 
 
+# In the following two tests, use recwarn to suppress warnings regarding the
+# deprecation of \stackrel and \mathcircled.
+
+
 @pytest.mark.parametrize('index, test', enumerate(math_tests),
                          ids=[str(index) for index in range(len(math_tests))])
 @pytest.mark.parametrize('fontset',
                          ['cm', 'stix', 'stixsans', 'dejavusans',
                           'dejavuserif'])
 @pytest.mark.parametrize('baseline_images', ['mathtext'], indirect=True)
 @image_comparison(baseline_images=None)
-def test_mathtext_rendering(baseline_images, fontset, index, test):
+def test_mathtext_rendering(baseline_images, fontset, index, test, recwarn):
     matplotlib.rcParams['mathtext.fontset'] = fontset
     fig = plt.figure(figsize=(5.25, 0.75))
     fig.text(0.5, 0.5, test,
@@ -184,7 +188,7 @@ def test_mathtext_rendering(baseline_images, fontset, index, test):
                           'dejavuserif'])
 @pytest.mark.parametrize('baseline_images', ['mathfont'], indirect=True)
 @image_comparison(baseline_images=None, extensions=['png'])
-def test_mathfont_rendering(baseline_images, fontset, index, test):
+def test_mathfont_rendering(baseline_images, fontset, index, test, recwarn):
     matplotlib.rcParams['mathtext.fontset'] = fontset
     fig = plt.figure(figsize=(5.25, 0.75))
     fig.text(0.5, 0.5, test,