Merge pull request #13376 from anntzer/case-insensitive-colors

timhoffm · web-flow · commit fc1f272ce2ab · 2019-02-07T00:43:31.000+01:00
Undeprecate case-insensitive "long" colornames.
diff --git a/doc/api/next_api_changes/2019-01-19-AL.rst b/doc/api/next_api_changes/2019-01-19-AL.rst
@@ -1,8 +1,9 @@
 Deprecations
 ````````````
 
-Support for passing colors as UPPERCASE strings is deprecated; color names will
-become case-sensitive (all-lowercase) after the deprecation period has passed.
+Support for passing single-letter colors (one of "rgbcmykw") as UPPERCASE
+characters is deprecated; these colors will become case-sensitive (lowercase)
+after the deprecation period has passed.
 
 The goal is to decrease the number of ambiguous cases when using the ``data``
 keyword to plotting methods; e.g. ``plot("X", "Y", data={"X": ..., "Y": ...})``
diff --git a/examples/statistics/barchart_demo.py b/examples/statistics/barchart_demo.py
@@ -28,9 +28,9 @@
 
 fig, ax = plt.subplots()
 rects1 = ax.bar(ind - width/2, men_means, width, yerr=men_std,
-                color='skyblue', label='Men')
+                color='SkyBlue', label='Men')
 rects2 = ax.bar(ind + width/2, women_means, width, yerr=women_std,
-                color='indianred', label='Women')
+                color='IndianRed', label='Women')
 
 # Add some text for labels, title and custom x-axis tick labels, etc.
 ax.set_ylabel('Scores')
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1,5 +1,5 @@
 """
-A module for converting numbers or color arguments to *RGB* or *RGBA*
+A module for converting numbers or color arguments to *RGB* or *RGBA*.
 
 *RGB* and *RGBA* are sequences of, respectively, 3 or 4 floats in the
 range 0-1.
@@ -26,7 +26,7 @@
   :doc:`/tutorials/colors/colormapnorms` for more details about data
   normalization
 
-  More colormaps are available at palettable_
+  More colormaps are available at palettable_.
 
 The module also provides functions for checking whether an object can be
 interpreted as a color (:func:`is_color_like`), for converting such an object
@@ -37,27 +37,26 @@
 Matplotlib recognizes the following formats to specify a color:
 
 * an RGB or RGBA tuple of float values in ``[0, 1]`` (e.g., ``(0.1, 0.2, 0.5)``
-  or  ``(0.1, 0.2, 0.5, 0.3)``);
-* a hex RGB or RGBA string (e.g., ``'#0F0F0F'`` or ``'#0F0F0F0F'``);
+  or ``(0.1, 0.2, 0.5, 0.3)``);
+* a hex RGB or RGBA string (e.g., ``'#0f0f0f'`` or ``'#0f0f0f80'``;
+  case-insensitive);
 * a string representation of a float value in ``[0, 1]`` inclusive for gray
   level (e.g., ``'0.5'``);
 * one of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``;
-* a X11/CSS4 color name;
-* a name from the `xkcd color survey <https://xkcd.com/color/rgb/>`__;
-  prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``);
-* one of ``{'tab:blue', 'tab:orange', 'tab:green',
-  'tab:red', 'tab:purple', 'tab:brown', 'tab:pink',
-  'tab:gray', 'tab:olive', 'tab:cyan'}`` which are the Tableau Colors from the
-  'T10' categorical palette (which is the default color cycle);
+* a X11/CSS4 color name (case-insensitive);
+* a name from the `xkcd color survey`_, prefixed with ``'xkcd:'`` (e.g.,
+  ``'xkcd:sky blue'``; case insensitive);
+* one of the Tableau Colors from the 'T10' categorical palette (the default
+  color cycle): ``{'tab:blue', 'tab:orange', 'tab:green', 'tab:red',
+  'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'}``
+  (case-insensitive);
 * a "CN" color spec, i.e. `'C'` followed by a number, which is an index into
   the default property cycle (``matplotlib.rcParams['axes.prop_cycle']``); the
   indexing is intended to occur at rendering time, and defaults to black if the
   cycle does not include color.
 
-All string specifications of color, other than "CN", are case-insensitive.
-
 .. _palettable: https://jiffyclub.github.io/palettable/
-
+.. _xkcd color survey: https://xkcd.com/color/rgb/
 """
 
 from collections.abc import Sized
@@ -201,10 +200,12 @@ def _to_rgba_no_colorcycle(c, alpha=None):
             except KeyError:
                 pass
             else:
-                cbook.warn_deprecated(
-                    "3.1", message="Support for case-insensitive colors is "
-                    "deprecated since Matplotlib %(since)s and will be "
-                    "removed %(removal)s.")
+                if len(orig_c) == 1:
+                    cbook.warn_deprecated(
+                        "3.1", message="Support for uppercase "
+                        "single-letter colors is deprecated since Matplotlib "
+                        "%(since)s and will be removed %(removal)s; please "
+                        "use lowercase instead.")
     if isinstance(c, str):
         # hex color with no alpha.
         match = re.match(r"\A#[a-fA-F0-9]{6}\Z", c)
diff --git a/tutorials/colors/colors.py b/tutorials/colors/colors.py
@@ -5,25 +5,28 @@
 
 Matplotlib recognizes the following formats to specify a color:
 
-* an RGB or RGBA tuple of float values in ``[0, 1]`` (e.g., ``(0.1, 0.2, 0.5)``
-  or  ``(0.1, 0.2, 0.5, 0.3)``).  RGBA is short for Red, Green, Blue, Alpha;
-* a hex RGB or RGBA string (e.g., ``'#0F0F0F'`` or ``'#0F0F0F0F'``);
+* an RGB or RGBA (red, green, blue, alpha) tuple of float values in ``[0, 1]``
+  (e.g., ``(0.1, 0.2, 0.5)`` or ``(0.1, 0.2, 0.5, 0.3)``);
+* a hex RGB or RGBA string (e.g., ``'#0f0f0f'`` or ``'#0f0f0f80'``;
+  case-insensitive);
 * a string representation of a float value in ``[0, 1]`` inclusive for gray
   level (e.g., ``'0.5'``);
 * one of ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``;
-* a X11/CSS4 color name;
-* a name from the `xkcd color survey <https://xkcd.com/color/rgb/>`__;
-  prefixed with ``'xkcd:'`` (e.g., ``'xkcd:sky blue'``);
-* one of ``{'tab:blue', 'tab:orange', 'tab:green',
-  'tab:red', 'tab:purple', 'tab:brown', 'tab:pink',
-  'tab:gray', 'tab:olive', 'tab:cyan'}`` which are the Tableau Colors from the
-  'T10' categorical palette (which is the default color cycle);
+* a X11/CSS4 color name (case-insensitive);
+* a name from the `xkcd color survey`_, prefixed with ``'xkcd:'`` (e.g.,
+  ``'xkcd:sky blue'``; case insensitive);
+* one of the Tableau Colors from the 'T10' categorical palette (the default
+  color cycle): ``{'tab:blue', 'tab:orange', 'tab:green', 'tab:red',
+  'tab:purple', 'tab:brown', 'tab:pink', 'tab:gray', 'tab:olive', 'tab:cyan'}``
+  (case-insensitive);
 * a "CN" color spec, i.e. `'C'` followed by a number, which is an index into
   the default property cycle (``matplotlib.rcParams['axes.prop_cycle']``); the
   indexing is intended to occur at rendering time, and defaults to black if the
   cycle does not include color.
 
-"Red", "Green" and "Blue", are the intensities of those colors, the combination
+.. _xkcd color survey: https://xkcd.com/color/rgb/
+
+"Red", "Green", and "Blue" are the intensities of those colors, the combination
 of which span the colorspace.
 
 How "Alpha" behaves depends on the ``zorder`` of the Artist.  Higher
@@ -36,8 +39,6 @@
 of 1 means the old color is completely covered by the new Artist, Alpha of 0
 means that pixel of the Artist is transparent.
 
-All string specifications of color, other than "CN", are case-insensitive.
-
 For more information on colors in matplotlib see
 
 * the :doc:`/gallery/color/color_demo` example;
