From 517bccbfb12298af4900e8f504afd7a0a98f1437 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 31 May 2021 21:36:37 +0200 Subject: [PATCH 1/2] Deduplicate color format specification --- lib/matplotlib/colors.py | 30 ++---------------------------- tutorials/colors/colors.py | 23 ++++++++++++----------- 2 files changed, 14 insertions(+), 39 deletions(-) diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index f678a4ffefd5..4f40c9afd40b 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -32,34 +32,8 @@ "#rrggbb" format (`to_hex`), and a sequence of colors to an (n, 4) RGBA array (`to_rgba_array`). Caching is used for efficiency. -Matplotlib recognizes the following formats to specify a color: - -* an RGB or RGBA (red, green, blue, alpha) tuple of float values in closed - interval ``[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 shorthand hex RGB or RGBA string, equivalent to the hex RGB or RGBA - string obtained by duplicating each character, (e.g., ``'#abc'``, equivalent - to ``'#aabbcc'``, or ``'#abcd'``, equivalent to ``'#aabbccdd'``; - case-insensitive); -* a string representation of a float value in ``[0, 1]`` inclusive for gray - level (e.g., ``'0.5'``); -* one of the characters ``{'b', 'g', 'r', 'c', 'm', 'y', 'k', 'w'}``, which - are short-hand notations for shades of blue, green, red, cyan, magenta, - yellow, black, and white. Note that the colors ``'g', 'c', 'm', 'y'`` do not - coincide with the X11/CSS4 colors. Their particular shades were chosen for - better visibility of colored lines against typical backgrounds. -* 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 (:rc:`axes.prop_cycle`); the indexing is intended to - occur at rendering time, and defaults to black if the cycle does not include - color. +Colors that Matplotlib recognizes are listed at +:doc:`/tutorials/colors/colors`. .. _palettable: https://jiffyclub.github.io/palettable/ .. _xkcd color survey: https://xkcd.com/color/rgb/ diff --git a/tutorials/colors/colors.py b/tutorials/colors/colors.py index dac7b800e47a..424ad0cdc091 100644 --- a/tutorials/colors/colors.py +++ b/tutorials/colors/colors.py @@ -3,8 +3,7 @@ Specifying Colors ***************** -Matplotlib recognizes the following formats in the table below to specify a -color. +Matplotlib recognizes the following formats to specify a color. +--------------------------------------+--------------------------------------+ | Format | Example | @@ -20,18 +19,20 @@ | equivalent hex shorthand of | - ``'#fb1'`` as ``'#ffbb11'`` | | duplicated characters. | | +--------------------------------------+--------------------------------------+ -| String representation of float value | - ``'0.8'`` as light gray | -| in closed interval ``[0, 1]`` for | - ``'0'`` as black | -| black and white, respectively. | - ``'1'`` as white | +| String representation of float value | - ``'0'`` as black | +| in closed interval ``[0, 1]`` for | - ``'1'`` as white | +| grayscale values. | - ``'0.8'`` as light gray | +--------------------------------------+--------------------------------------+ | Single character shorthand notation | - ``'b'`` as blue | -| for shades of colors. | - ``'g'`` as green | +| for some basic colors. | - ``'g'`` as green | | | - ``'r'`` as red | -| .. note:: The colors green, cyan, | - ``'c'`` as cyan | -| magenta, and yellow do not | - ``'m'`` as magenta | -| coincide with X11/CSS4 | - ``'y'`` as yellow | -| colors. | - ``'k'`` as black | -| | - ``'w'`` as white | +| .. note:: | - ``'c'`` as cyan | +| The colors green, cyan, magenta, | - ``'m'`` as magenta | +| and yellow do not coincide with | - ``'y'`` as yellow | +| X11/CSS4 colors. Their particular | - ``'k'`` as black | +| shades were chosen for better | - ``'w'`` as white | +| visibility of colored lines | | +| against typical backgrounds. | | +--------------------------------------+--------------------------------------+ | Case-insensitive X11/CSS4 color name | - ``'aquamarine'`` | | with no spaces. | - ``'mediumseagreen'`` | From 1a86a71dbbd80163c4c37460c13d30f923bb351b Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 31 May 2021 21:37:13 +0200 Subject: [PATCH 2/2] Reword note on legend handlers --- lib/matplotlib/legend_handler.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py index 518fa57864d6..817ad13c43d8 100644 --- a/lib/matplotlib/legend_handler.py +++ b/lib/matplotlib/legend_handler.py @@ -3,8 +3,10 @@ .. important:: - It is strongly encouraged to have read the :doc:`legend guide - ` before this documentation. + This is a low-level legend API, which most end users do not need. + + We recommend that you are familiar with the :doc:`legend guide + ` before reading this documentation. Legend handlers are expected to be a callable object with a following signature. ::