From df56b7edcf25e1ae55f858092638ee42e90598f8 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 18 Sep 2018 11:15:05 +0200 Subject: [PATCH] Deprecate \stackrel. Mathtext's \stackrel{a}{b} behaves subtly differently from latex's \stackrel{a}{b}: mathtext makes `a` and `b` equal-sized whereas latex makes `a` smaller than `b` (`a` is an "annotation" over `b`). Given that we can already stack expressions using the (admittedly less practical, but standard) \genfrac, just deprecate \stackrel instead of maintaining our own latex-like dialect. Also undeprecate passing obj_type to the cbook.deprecated decorator(!), given that this PR has a good reason to use it... and while we're at it, reorder the kwargs docs for cbook.deprecated and cbook.warn_deprecated to match the order in the signature. --- .../2018-08-19-AL-deprecations.rst | 11 ++++++ .../mathtext_examples.py | 2 +- lib/matplotlib/cbook/deprecation.py | 37 ++++++++++--------- lib/matplotlib/mathtext.py | 2 + tutorials/text/mathtext.py | 7 ++-- 5 files changed, 37 insertions(+), 22 deletions(-) create mode 100644 doc/api/next_api_changes/2018-08-19-AL-deprecations.rst diff --git a/doc/api/next_api_changes/2018-08-19-AL-deprecations.rst b/doc/api/next_api_changes/2018-08-19-AL-deprecations.rst new file mode 100644 index 000000000000..cc2b13bf3d49 --- /dev/null +++ b/doc/api/next_api_changes/2018-08-19-AL-deprecations.rst @@ -0,0 +1,11 @@ +Deprecations +```````````` + +The ``\stackrel`` mathtext command is deprecated (it behaved differently +from LaTeX's ``\stackrel``. To stack two mathtext expressions, use +``\genfrac{left-delim}{right-delim}{fraction-bar-thickness}{}{top}{bottom}``. + +Undeprecations +`````````````` + +The ``obj_type`` kwarg to the ``cbook.deprecated`` decorator is undeprecated. diff --git a/examples/text_labels_and_annotations/mathtext_examples.py b/examples/text_labels_and_annotations/mathtext_examples.py index 6272099819f5..22faf370c0e0 100644 --- a/examples/text_labels_and_annotations/mathtext_examples.py +++ b/examples/text_labels_and_annotations/mathtext_examples.py @@ -34,7 +34,7 @@ r"\alpha_{i+1}^j = {\rm sin}(2\pi f_j t_i) e^{-5 t_i/\tau},\ " r"\ldots$", - 2: r"$\frac{3}{4},\ \binom{3}{4},\ \stackrel{3}{4},\ " + 2: r"$\frac{3}{4},\ \binom{3}{4},\ \genfrac{}{}{0}{}{3}{4},\ " r"\left(\frac{5 - \frac{1}{x}}{4}\right),\ \ldots$", 3: r"$\sqrt{2},\ \sqrt[3]{x},\ \ldots$", diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py index 05088b2414ba..22da5634f846 100644 --- a/lib/matplotlib/cbook/deprecation.py +++ b/lib/matplotlib/cbook/deprecation.py @@ -86,18 +86,18 @@ def warn_deprecated( If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. - removal : str, optional - The expected removal version. With the default (an empty string), a - removal version is automatically computed from *since*. Set to other - Falsy values to not schedule a removal date. Cannot be used together - with *pending*. - obj_type : str, optional The object type being deprecated. addendum : str, optional Additional text appended directly to the final message. + removal : str, optional + The expected removal version. With the default (an empty string), a + removal version is automatically computed from *since*. Set to other + Falsy values to not schedule a removal date. Cannot be used together + with *pending*. + Examples -------- @@ -157,15 +157,19 @@ def new_function(): If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. + obj_type : str, optional + The object type being deprecated; by default, 'function' if decorating + a function and 'class' if decorating a class. + + addendum : str, optional + Additional text appended directly to the final message. + removal : str, optional The expected removal version. With the default (an empty string), a removal version is automatically computed from *since*. Set to other Falsy values to not schedule a removal date. Cannot be used together with *pending*. - addendum : str, optional - Additional text appended directly to the final message. - Examples -------- @@ -176,16 +180,12 @@ def the_function_to_deprecate(): pass """ - if obj_type is not None: - warn_deprecated( - "3.0", message="Passing 'obj_type' to the 'deprecated' decorator " - "has no effect, and is deprecated since Matplotlib %(since)s; " - "support for it will be removed %(removal)s.") - def deprecate(obj, message=message, name=name, alternative=alternative, - pending=pending, addendum=addendum): + pending=pending, obj_type=obj_type, addendum=addendum): + if isinstance(obj, type): - obj_type = "class" + if obj_type is None: + obj_type = "class" func = obj.__init__ name = name or obj.__name__ old_doc = obj.__doc__ @@ -225,7 +225,8 @@ def finalize(_, new_doc): fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc) else: - obj_type = "function" + if obj_type is None: + obj_type = "function" func = obj name = name or obj.__name__ old_doc = func.__doc__ diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py index 909d313be628..6d83d9d8a330 100644 --- a/lib/matplotlib/mathtext.py +++ b/lib/matplotlib/mathtext.py @@ -3183,6 +3183,8 @@ def dfrac(self, s, loc, toks): return self._genfrac('', '', thickness, self._math_style_dict['displaystyle'], num, den) + @cbook.deprecated("3.1", obj_type="mathtext command", + alternative=r"\genfrac") def stackrel(self, s, loc, toks): assert len(toks) == 1 assert len(toks[0]) == 2 diff --git a/tutorials/text/mathtext.py b/tutorials/text/mathtext.py index 437a27456e33..f696138de2af 100644 --- a/tutorials/text/mathtext.py +++ b/tutorials/text/mathtext.py @@ -80,15 +80,16 @@ ----------------------------------------- Fractions, binomials, and stacked numbers can be created with the -``\frac{}{}``, ``\binom{}{}`` and ``\stackrel{}{}`` commands, respectively:: +``\frac{}{}``, ``\binom{}{}`` and ``\genfrac{}{}{}{}{}{}`` commands, +respectively:: - r'$\frac{3}{4} \binom{3}{4} \stackrel{3}{4}$' + r'$\frac{3}{4} \binom{3}{4} \genfrac{}{}{0}{}{3}{4}$' produces .. math:: - \frac{3}{4} \binom{3}{4} \stackrel{3}{4} + \frac{3}{4} \binom{3}{4} \stackrel{}{}{0}{}{3}{4} Fractions can be arbitrarily nested::