Added "Colors" to concepts (#9067)

Author: hugovk

docs/handbook/concepts.rst

@@ -101,6 +101,28 @@ Palette
 The palette mode (``P``) uses a color palette to define the actual color for
 each pixel.
 
+.. _colors:
+
+Colors
+------
+
+To specify colors, you can use tuples with a value for each channel in the image, e.g.
+``Image.new("RGB", (1, 1), (255, 0, 0))``.
+
+If an image has a single channel, you can use a single number instead, e.g.
+``Image.new("L", (1, 1), 255)``. For "F" mode images, floating point values are also
+accepted. In the case of "P" mode images, these will be indexes for the color palette.
+
+If a single value is used for an image with more than one channel, it will still be
+parsed::
+
+    >>> from PIL import Image
+    >>> im = Image.new("RGBA", (1, 1), 0x04030201)
+    >>> im.getpixel((0, 0))
+    (1, 2, 3, 4)
+
+Some methods accept other forms, such as color names. See :ref:`color-names`.
+
 Info
 ----
 

docs/reference/ImageDraw.rst

@@ -45,9 +45,7 @@ Colors
 ^^^^^^
 
 To specify colors, you can use numbers or tuples just as you would use with
-:py:meth:`PIL.Image.new` or :py:meth:`PIL.Image.Image.putpixel`. For “1”,
-“L”, and “I” images, use integers. For “RGB” images, use a 3-tuple containing
-integer values. For “F” images, use integer or floating point values.
+:py:meth:`PIL.Image.new`. See :ref:`colors` for more information.
 
 For palette images (mode “P”), use integers as color indexes. In 1.1.4 and
 later, you can also use RGB 3-tuples or color names (see below). The drawing

docs/reference/PixelAccess.rst

@@ -59,7 +59,7 @@ Access using negative indexes is also possible. ::
 
         Modifies the pixel at x,y. The color is given as a single
         numerical value for single band images, and a tuple for
-        multi-band images.
+        multi-band images. See :ref:`colors` for more information.
 
         :param xy: The pixel coordinate, given as (x, y).
         :param color: The pixel value according to its mode,

src/PIL/Image.py

@@ -1730,9 +1730,10 @@ def paste(
         details).
 
         Instead of an image, the source can be a integer or tuple
-        containing pixel values.  The method then fills the region
-        with the given color.  When creating RGB images, you can
-        also use color strings as supported by the ImageColor module.
+        containing pixel values. The method then fills the region
+        with the given color. When creating RGB images, you can
+        also use color strings as supported by the ImageColor module. See
+        :ref:`colors` for more information.
 
         If a mask is given, this method updates only the regions
         indicated by the mask. You can use either "1", "L", "LA", "RGBA"
@@ -1988,7 +1989,8 @@ def putdata(
         sequence ends. The scale and offset values are used to adjust the
         sequence values: **pixel = value*scale + offset**.
 
-        :param data: A flattened sequence object.
+        :param data: A flattened sequence object. See :ref:`colors` for more
+            information about values.
         :param scale: An optional scale value.  The default is 1.0.
         :param offset: An optional offset value.  The default is 0.0.
         """
@@ -2047,7 +2049,7 @@ def putpixel(
         Modifies the pixel at the given position. The color is given as
         a single numerical value for single-band images, and a tuple for
         multi-band images. In addition to this, RGB and RGBA tuples are
-        accepted for P and PA images.
+        accepted for P and PA images. See :ref:`colors` for more information.
 
         Note that this method is relatively slow.  For more extensive changes,
         use :py:meth:`~PIL.Image.Image.paste` or the :py:mod:`~PIL.ImageDraw`
@@ -3055,12 +3057,12 @@ def new(
     :param mode: The mode to use for the new image. See:
        :ref:`concept-modes`.
     :param size: A 2-tuple, containing (width, height) in pixels.
-    :param color: What color to use for the image.  Default is black.
-       If given, this should be a single integer or floating point value
-       for single-band modes, and a tuple for multi-band modes (one value
-       per band).  When creating RGB or HSV images, you can also use color
-       strings as supported by the ImageColor module.  If the color is
-       None, the image is not initialised.
+    :param color: What color to use for the image. Default is black. If given,
+       this should be a single integer or floating point value for single-band
+       modes, and a tuple for multi-band modes (one value per band). When
+       creating RGB or HSV images, you can also use color strings as supported
+       by the ImageColor module. See :ref:`colors` for more information. If the
+       color is None, the image is not initialised.
     :returns: An :py:class:`~PIL.Image.Image` object.
     """