Deprecate case-insensitive capstyles and joinstyles.

anntzer · anntzer · commit 5a9ea37dbfec · 2019-12-08T17:06:56.000+01:00
Collections have never accepted case-sensitive capstyles/joinstyles
(their setter don't do `s.lower()` first) but AFAIK no one has
complained about it, which suggests their use is rare.

There isn't much of a reason in supporting them, case-insensitive APIs
are not-so pythonic, and unsupporting them makes code map more easily to
cbook._check_in_list.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -47,3 +47,8 @@ PDF and PS character tracking internals
 The ``used_characters`` attribute and ``track_characters`` and
 ``merge_used_characters`` methods of `.RendererPdf`, `.PdfFile`, and
 `.RendererPS` are deprecated.
+
+Case-insensitive capstyles and joinstyles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Please pass capstyles ("miter", "round", "bevel") and joinstyles ("butt",
+"round", "projecting") as lowercase.
diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py
@@ -9,6 +9,7 @@
 
 import numpy as np
 
+import matplotlib as mpl
 from . import artist, cbook, colors as mcolors, docstring, rcParams
 from .artist import Artist, allow_rasterization
 from .cbook import (
@@ -1366,7 +1367,7 @@ def set_dash_joinstyle(self, s):
         s : {'miter', 'round', 'bevel'}
             For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validJoin, s=s)
         if self._dashjoinstyle != s:
             self.stale = True
@@ -1381,7 +1382,7 @@ def set_solid_joinstyle(self, s):
         s : {'miter', 'round', 'bevel'}
             For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validJoin, s=s)
         if self._solidjoinstyle != s:
             self.stale = True
@@ -1412,7 +1413,7 @@ def set_dash_capstyle(self, s):
         s : {'butt', 'round', 'projecting'}
             For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validCap, s=s)
         if self._dashcapstyle != s:
             self.stale = True
@@ -1427,7 +1428,7 @@ def set_solid_capstyle(self, s):
         s : {'butt', 'round', 'projecting'}
             For examples see :doc:`/gallery/lines_bars_and_markers/joinstyle`.
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validCap, s=s)
         if self._solidcapstyle != s:
             self.stale = True
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -32,8 +32,8 @@ class Patch(artist.Artist):
     are *None*, they default to their rc params setting.
     """
     zorder = 1
-    validCap = ('butt', 'round', 'projecting')
-    validJoin = ('miter', 'round', 'bevel')
+    validCap = mlines.Line2D.validCap
+    validJoin = mlines.Line2D.validJoin
 
     # Whether to draw an edge by default.  Set on a
     # subclass-by-subclass basis.
@@ -463,7 +463,7 @@ def set_capstyle(self, s):
         ----------
         s : {'butt', 'round', 'projecting'}
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validCap, capstyle=s)
         self._capstyle = s
         self.stale = True
@@ -479,7 +479,7 @@ def set_joinstyle(self, s):
         ----------
         s : {'miter', 'round', 'bevel'}
         """
-        s = s.lower()
+        s = mpl.rcsetup._deprecate_case_insensitive_join_cap(s)
         cbook._check_in_list(self.validJoin, joinstyle=s)
         self._joinstyle = s
         self.stale = True
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -580,19 +580,41 @@ def _is_iterable_not_string_like(x):
     raise ValueError(f"linestyle {ls!r} is not a valid on-off ink sequence.")
 
 
-validate_joinstyle = ValidateInStrings('joinstyle',
-                                       ['miter', 'round', 'bevel'],
-                                       ignorecase=True)
-validate_joinstylelist = _listify_validator(validate_joinstyle)
+def _deprecate_case_insensitive_join_cap(s):
+    s_low = s.lower()
+    if s != s_low:
+        if s_low in ['miter', 'round', 'bevel']:
+            cbook.warn_deprecated(
+                "3.3", message="Case-insensitive capstyles are deprecated "
+                "since %(since)s and support for them will be removed "
+                "%(removal)s; please pass them in lowercase.")
+        elif s_low in ['butt', 'round', 'projecting']:
+            cbook.warn_deprecated(
+                "3.3", message="Case-insensitive joinstyles are deprecated "
+                "since %(since)s and support for them will be removed "
+                "%(removal)s; please pass them in lowercase.")
+        # Else, error out at the check_in_list stage.
+    return s_low
+
+
+def validate_joinstyle(s):
+    s = _deprecate_case_insensitive_join_cap(s)
+    cbook._check_in_list(['miter', 'round', 'bevel'], joinstyle=s)
+    return s
 
-validate_capstyle = ValidateInStrings('capstyle',
-                                      ['butt', 'round', 'projecting'],
-                                      ignorecase=True)
-validate_capstylelist = _listify_validator(validate_capstyle)
 
-validate_fillstyle = ValidateInStrings('markers.fillstyle',
-                                       ['full', 'left', 'right', 'bottom',
-                                        'top', 'none'])
+def validate_capstyle(s):
+    s = _deprecate_case_insensitive_join_cap(s)
+    cbook._check_in_list(['butt', 'round', 'projecting'], capstyle=s)
+    return s
+
+
+validate_fillstyle = ValidateInStrings(
+    'markers.fillstyle', ['full', 'left', 'right', 'bottom', 'top', 'none'])
+
+
+validate_joinstylelist = _listify_validator(validate_joinstyle)
+validate_capstylelist = _listify_validator(validate_capstyle)
 validate_fillstylelist = _listify_validator(validate_fillstyle)
 
 
