From cec36cdb01d01a26f20da405f848c31796ce1830 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 | 36 +++++++++---------- lib/matplotlib/mathtext.py | 2 ++ tutorials/text/mathtext.py | 7 ++-- 5 files changed, 35 insertions(+), 23 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 43de50858cd5..fb1ce9221010 100644 --- a/lib/matplotlib/cbook/deprecation.py +++ b/lib/matplotlib/cbook/deprecation.py @@ -82,18 +82,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 -------- @@ -156,15 +156,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 -------- @@ -175,16 +179,10 @@ def the_function_to_deprecate(): pass """ - if obj_type is not None: - warn_deprecated( - "3.0", "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" + obj_type = obj_type or "class" func = obj.__init__ name = name or obj.__name__ old_doc = obj.__doc__ @@ -195,7 +193,7 @@ def finalize(wrapper, new_doc): return obj elif isinstance(obj, property): - obj_type = "attribute" + obj_type = obj_type or "attribute" func = None name = name or obj.fget.__name__ old_doc = obj.__doc__ @@ -221,7 +219,7 @@ def finalize(_, new_doc): fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc) else: - obj_type = "function" + obj_type = obj_type or "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 efec64b7b7b8..bbd8184c5ab1 100644 --- a/lib/matplotlib/mathtext.py +++ b/lib/matplotlib/mathtext.py @@ -3182,6 +3182,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 96a523f192cf..2c90c59b04c4 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} \genfrac{}{}{0}{}{3}{4} Fractions can be arbitrarily nested::