MAINT: deprecate validCap, validJoin

brunobeltran · brunobeltran · commit 4f55d60eaffb · 2020-10-27T20:39:34.000-07:00
diff --git a/doc/api/next_api_changes/18817-BGB.rst b/doc/api/next_api_changes/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/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py
@@ -16,6 +16,40 @@
 import warnings
 
 
+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 +235,15 @@ 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:
                         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
@@ -11,6 +11,7 @@
 
 import matplotlib as mpl
 from . import _api, artist, cbook, colors as mcolors, docstring, rcParams
+from ._api.deprecation import deprecated, _classproperty
 from .artist import Artist, allow_rasterization
 from .cbook import (
     _to_unmasked_float_array, ls_mapper, ls_mapper_r, STEP_LOOKUP_MAP)
@@ -251,8 +252,16 @@ class Line2D(Artist):
     fillStyles = MarkerStyle.fillstyles
 
     zorder = 2
-    validCap = ('butt', 'round', 'projecting')
-    validJoin = ('miter', 'round', 'bevel')
+
+    @deprecated("3.4")
+    @_classproperty
+    def validCap(cls):
+        return ('butt', 'round', 'projecting')
+
+    @deprecated("3.4")
+    @_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,12 +5,14 @@
 from numbers import Number
 import textwrap
 from collections import namedtuple
+import warnings
 
 import numpy as np
 
 import matplotlib as mpl
 from . import (_api, artist, cbook, colors, docstring, hatch as mhatch,
                lines as mlines, transforms)
+from ._api.deprecation import deprecated, _classproperty
 from .bezier import (
     NonIntersectingPathException, get_cos_sin, get_intersection,
     get_parallels, inside_circle, make_wedged_bezier2,
@@ -33,8 +35,20 @@ class Patch(artist.Artist):
     are *None*, they default to their rc params setting.
     """
     zorder = 1
-    validCap = mlines.Line2D.validCap
-    validJoin = mlines.Line2D.validJoin
+
+    @deprecated("3.4")
+    @_classproperty
+    def validCap(cls):
+        with warnings.catch_warnings():
+            cbook._suppress_matplotlib_deprecation_warning()
+            return mlines.Line2D.validCap
+
+    @deprecated("3.4")
+    @_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``.