MAINT: deprecate validCap, validJoin

brunobeltran · brunobeltran · commit aed162fd751d · 2020-11-04T17:16:42.000-08:00
diff --git a/doc/api/next_api_changes/deprecations/18817-BGB.rst b/doc/api/next_api_changes/deprecations/18817-BGB.rst
@@ -0,0 +1,3 @@
+Line2D and Patch no longer duplicate ``validJoin`` and ``validCap``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Validation of joinstyle and capstyles is now centralized in ``rcsetup``.
diff --git a/doc/conf.py b/doc/conf.py
@@ -13,8 +13,10 @@
 import shutil
 import subprocess
 import sys
+import warnings
 
 import matplotlib
+from matplotlib._api.deprecation import MatplotlibDeprecationWarning
 import sphinx
 
 from datetime import datetime
@@ -109,6 +111,11 @@ def _check_dependencies():
 autodoc_docstring_signature = True
 autodoc_default_options = {'members': None, 'undoc-members': None}
 
+# make sure to ignore warnings that stem from simply inspecting deprecated
+# class-level attributes
+warnings.filterwarnings('ignore', category=MatplotlibDeprecationWarning,
+                        module='sphinx.util.inspect')
+
 # missing-references names matches sphinx>=3 behavior, so we can't be nitpicky
 # for older sphinxes.
 nitpicky = sphinx.version_info >= (3,)
diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py
@@ -16,6 +16,42 @@
 import warnings
 
 
+# has to be here (instead of cbook) to prevent circular import, since
+# deprecation.deprecated is *used* during cbook's import
+class _classproperty:
+    """
+    Like `property`, but also triggers on access via the class, and it is the
+    *class* that's passed as argument.
+
+    Examples
+    --------
+    ::
+
+        class C:
+            @_classproperty
+            def foo(cls):
+                return cls.__name__
+
+        assert C.foo == "C"
+    """
+
+    def __init__(self, fget, fset=None, fdel=None, doc=None):
+        self._fget = fget
+        if fset is not None or fdel is not None:
+            raise ValueError('_classproperty only implements fget.')
+        self.fset = fset
+        self.fdel = fdel
+        # docs are ignored for now
+        self._doc = doc
+
+    def __get__(self, instance, owner):
+        return self._fget(owner)
+
+    @property
+    def fget(self):
+        return self._fget
+
+
 class MatplotlibDeprecationWarning(UserWarning):
     """
     A class for issuing deprecation warnings for Matplotlib users.
@@ -201,15 +237,16 @@ def finalize(wrapper, new_doc):
                 obj.__init__ = functools.wraps(obj.__init__)(wrapper)
                 return obj
 
-        elif isinstance(obj, property):
+        elif isinstance(obj, (property, _classproperty)):
             obj_type = "attribute"
             func = None
             name = name or obj.fget.__name__
             old_doc = obj.__doc__
 
-            class _deprecated_property(property):
+            class _deprecated_property(type(obj)):
                 def __get__(self, instance, owner):
-                    if instance is not None:
+                    if instance is not None or owner is not None \
+                            and isinstance(self, _classproperty):
                         emit_warning()
                     return super().__get__(instance, owner)
 
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -35,7 +35,7 @@
     _rename_parameter, _delete_parameter, _make_keyword_only,
     _deprecate_method_override, _deprecate_privatize_attribute,
     _suppress_matplotlib_deprecation_warning,
-    MatplotlibDeprecationWarning, mplDeprecation)
+    MatplotlibDeprecationWarning, mplDeprecation, _classproperty)
 
 
 def _get_running_interactive_framework():
@@ -2262,30 +2262,6 @@ def type_name(tp):
                     type_name(type(v))))
 
 
-class _classproperty:
-    """
-    Like `property`, but also triggers on access via the class, and it is the
-    *class* that's passed as argument.
-
-    Examples
-    --------
-    ::
-
-        class C:
-            @classproperty
-            def foo(cls):
-                return cls.__name__
-
-        assert C.foo == "C"
-    """
-
-    def __init__(self, fget):
-        self._fget = fget
-
-    def __get__(self, instance, owner):
-        return self._fget(owner)
-
-
 def _backend_module_name(name):
     """
     Convert a backend name (either a standard backend -- "Agg", "TkAgg", ... --
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -3,7 +3,6 @@
 colors.
 """
 
-# TODO: expose cap and join style attrs
 from numbers import Integral, Number, Real
 import logging
 
@@ -251,8 +250,16 @@ class Line2D(Artist):
     fillStyles = MarkerStyle.fillstyles
 
     zorder = 2
-    validCap = ('butt', 'round', 'projecting')
-    validJoin = ('miter', 'round', 'bevel')
+
+    @_api.deprecated("3.4")
+    @_api._classproperty
+    def validCap(cls):
+        return ('butt', 'round', 'projecting')
+
+    @_api.deprecated("3.4")
+    @_api._classproperty
+    def validJoin(cls):
+        return ('miter', 'round', 'bevel')
 
     def __str__(self):
         if self._label != "":
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -5,6 +5,7 @@
 from numbers import Number
 import textwrap
 from collections import namedtuple
+import warnings
 
 import numpy as np
 
@@ -33,8 +34,20 @@ class Patch(artist.Artist):
     are *None*, they default to their rc params setting.
     """
     zorder = 1
-    validCap = mlines.Line2D.validCap
-    validJoin = mlines.Line2D.validJoin
+
+    @_api.deprecated("3.4")
+    @_api._classproperty
+    def validCap(cls):
+        with warnings.catch_warnings():
+            cbook._suppress_matplotlib_deprecation_warning()
+            return mlines.Line2D.validCap
+
+    @_api.deprecated("3.4")
+    @_api._classproperty
+    def validJoin(cls):
+        with warnings.catch_warnings():
+            cbook._suppress_matplotlib_deprecation_warning()
+            return mlines.Line2D.validJoin
 
     # Whether to draw an edge by default.  Set on a
     # subclass-by-subclass basis.
diff --git a/lib/matplotlib/tests/test_api.py b/lib/matplotlib/tests/test_api.py
@@ -4,6 +4,9 @@
 import pytest
 
 from matplotlib import _api
+from matplotlib.cbook import (
+    _classproperty, MatplotlibDeprecationWarning)
+from matplotlib._api.deprecation import deprecated
 
 
 @pytest.mark.parametrize('target,test_shape',
@@ -19,3 +22,16 @@ def test_check_shape(target, test_shape):
     data = np.zeros(test_shape)
     with pytest.raises(ValueError, match=error_pattern):
         _api.check_shape(target, aardvark=data)
+
+
+def test_classproperty_deprecation():
+    class A:
+        @deprecated("0.0.0")
+        @_classproperty
+        def f(cls):
+            pass
+    with pytest.warns(MatplotlibDeprecationWarning):
+        A.f
+    with pytest.warns(MatplotlibDeprecationWarning):
+        a = A()
+        a.f

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+Line2D and Patch no longer duplicate ``validJoin`` and ``validCap``
	`2`	`+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
	`3`	+Validation of joinstyle and capstyles is now centralized in ``rcsetup``.