Merge pull request #3165 from damusss/use-ColorLike-docs

Improve color notation in the docs

docs/reST/ref/draw.rst

@@ -20,13 +20,8 @@ constrained to that area. The functions return a rectangle representing the
 bounding area of changed pixels. This bounding rectangle is the 'minimum'
 bounding box that encloses the affected area.
 
-All the drawing functions accept a color argument that can be one of the
-following formats:
-
-   - a :mod:`pygame.Color` object, or a type (apart from ``int``) that can be passed to
-     its constructor
-   - an ``int`` value which must be mapped to the pixel format of the surface
-     (see :func:`pygame.Surface.map_rgb` and :func:`pygame.Surface.unmap_rgb`)
+All the drawing functions accept a color argument that is compatible with
+:data:`pygame.typing.ColorLike`.
 
 A color's alpha value will be written directly into the surface (if the
 surface contains pixel alphas), but the draw function will not draw
@@ -52,7 +47,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param Rect rect: rectangle to draw, position and dimensions
    :param int width: (optional) used for line thickness or to indicate that
       the rectangle is to be filled (not to be confused with the width value
@@ -110,7 +105,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param points: a sequence of 3 or more (x, y) coordinates that make up the
       vertices of the polygon, each point in the sequence must be a
       tuple/list/:class:`pygame.math.Vector2` of 2 ints/floats,
@@ -158,7 +153,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param center: center point of the circle as a sequence of 2 ints/floats,
       e.g. ``(x, y)``
    :type center: tuple(int or float, int or float) or
@@ -219,7 +214,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param center: center point of the circle as a sequence of 2 ints/floats,
       e.g. ``(x, y)``
    :type center: tuple(int or float, int or float) or
@@ -273,7 +268,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param Rect rect: rectangle to indicate the position and dimensions of the
       ellipse, the ellipse will be centered inside the rectangle and bounded
       by it
@@ -314,7 +309,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param Rect rect: rectangle to indicate the position and dimensions of the
       ellipse which the arc will be based on, the ellipse will be centered
       inside the rectangle
@@ -364,7 +359,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param start_pos: start position of the line, (x, y)
    :type start_pos: tuple(int or float, int or float) or
       list(int or float, int or float) or Vector2(int or float, int or float)
@@ -416,7 +411,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param bool closed: if ``True`` an additional line segment is drawn between
       the first and last points in the ``points`` sequence
    :param points: a sequence of 2 or more (x, y) coordinates, where each
@@ -474,7 +469,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param start_pos: start position of the line, (x, y)
    :type start_pos: tuple(int or float, int or float) or
       list(int or float, int or float) or Vector2(int or float, int or float)
@@ -513,7 +508,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :type color: :data:`pygame.typing.ColorLike`
    :param bool closed: if ``True`` an additional line segment is drawn between
       the first and last points in the ``points`` sequence
    :param points: a sequence of 2 or more (x, y) coordinates, where each

docs/reST/ref/mask.rst

@@ -593,14 +593,12 @@ to store which parts collide.
          ``(255, 255, 255, 255)``, white), use ``None`` to skip drawing the set
          bits, the ``setsurface`` parameter (if set) will takes precedence over
          this parameter
-      :type setcolor: Color or str or int or tuple(int, int, int, [int]) or
-         list(int, int, int, [int]) or None
+      :type setcolor: :data:`pygame.typing.ColorLike` or ``None``
       :param unsetcolor: (optional) color to draw unset bits (default is
          ``(0, 0, 0, 255)``, black), use ``None`` to skip drawing the unset
          bits, the ``unsetsurface`` parameter (if set) will takes precedence
          over this parameter
-      :type unsetcolor: Color or str or int or tuple(int, int, int, [int]) or
-         list(int, int, int, [int]) or None
+      :type unsetcolor: :data:`pygame.typing.ColorLike` or ``None``
       :param dest: (optional) surface destination of where to position the
          topleft corner of the mask being drawn (default is ``(0, 0)``), if a
          Rect is used as the ``dest`` parameter, its ``x`` and ``y`` attributes

docs/reST/ref/surface.rst

@@ -298,10 +298,9 @@
       entire Surface will be filled. The rect argument will limit the fill to a
       specific area. The fill will also be contained by the Surface clip area.
 
-      The color argument can be an ``RGB`` sequence, an ``RGBA`` sequence,
-      a string (for :doc:`color_list`), or a mapped color index. If using ``RGBA``,
-      the Alpha (A part of ``RGBA``) is ignored unless the surface uses per pixel
-      alpha (Surface has the ``SRCALPHA`` flag).
+      The color argument should be compatible with :data:`pygame.typing.ColorLike`.
+      If using ``RGBA``, the Alpha (A part of ``RGBA``) is ignored unless the surface
+      uses per pixel alpha (Surface has the ``SRCALPHA`` flag).
 
       The special_flags argument controls how the colors are combined. See :doc:`special_flags_list`
       for a list of possible values.
@@ -338,9 +337,8 @@
 
       Set the current color key for the Surface. When blitting this Surface
       onto a destination, any pixels that have the same color as the colorkey
-      will be transparent. The color can be an ``RGB`` color, a string
-      (for :doc:`color_list`), or a mapped color integer. If ``None`` is passed,
-      the colorkey will be unset.
+      will be transparent. The color should be compatible with :data:`pygame.typing.ColorLike`.
+      If ``None`` is passed, the colorkey will be unset.
 
       The colorkey will be ignored if the Surface is formatted to use per pixel
       alpha values. The colorkey can be mixed with the full Surface alpha
@@ -355,7 +353,7 @@
    .. method:: get_colorkey
 
       | :sl:`get the current transparent colorkey`
-      | :sg:`get_colorkey() -> RGB or None`
+      | :sg:`get_colorkey() -> RGBA or None`
 
       Return the current colorkey value for the Surface. If the colorkey is not
       set then ``None`` is returned.
@@ -510,10 +508,10 @@
       | :sl:`set the color value for a single pixel`
       | :sg:`set_at((x, y), color, /) -> None`
 
-      Set the color of a single pixel at the specified coordinates to be an ``RGB``,
-      ``RGBA``, string (for :doc:`color_list`), or mapped integer color value. If the Surface
-      does not have per pixel alphas, the alpha value is ignored. Setting pixels outside the
-      Surface area or outside the Surface clipping will have no effect.
+      Set the color of a single pixel at the specified coordinates to be a
+      :data:`pygame.typing.ColorLike` value. If the Surface does not have per pixel alphas,
+      the alpha value is ignored. Setting pixels outside the Surface area or outside
+      the Surface clipping will have no effect.
 
       Getting and setting pixels one at a time is generally too slow to be used
       in a game or realtime situation.
@@ -550,7 +548,7 @@
    .. method:: get_palette
 
       | :sl:`get the color index palette for an 8-bit Surface`
-      | :sg:`get_palette() -> [RGB, RGB, RGB, ...]`
+      | :sg:`get_palette() -> [Color, Color, Color, ...]`
 
       Return a list of up to 256 color elements that represent the indexed
       colors used in an 8-bit Surface. The returned list is a copy of the
@@ -565,7 +563,7 @@
    .. method:: get_palette_at
 
       | :sl:`get the color for a single entry in a palette`
-      | :sg:`get_palette_at(index, /) -> RGB`
+      | :sg:`get_palette_at(index, /) -> Color`
 
       Returns the red, green, and blue color values for a single index in a
       Surface palette. The index should be a value from 0 to 255.
@@ -578,7 +576,7 @@
    .. method:: set_palette
 
       | :sl:`set the color palette for an 8-bit Surface`
-      | :sg:`set_palette([RGB, RGB, RGB, ...], /) -> None`
+      | :sg:`set_palette([color, color, color, ...], /) -> None`
 
       Set the full palette for an 8-bit Surface. This will replace the colors in
       the existing palette. A partial palette can be passed and only the first
@@ -591,7 +589,7 @@
    .. method:: set_palette_at
 
       | :sl:`set the color for a single index in an 8-bit Surface palette`
-      | :sg:`set_palette_at(index, RGB, /) -> None`
+      | :sg:`set_palette_at(index, color, /) -> None`
 
       Set the palette value for a single entry in a Surface palette. The index
       should be a value from 0 to 255.
@@ -605,10 +603,10 @@
       | :sl:`convert a color into a mapped color value`
       | :sg:`map_rgb(color, /) -> mapped_int`
 
-      Convert an ``RGBA`` color into the mapped integer value for this Surface.
-      The returned integer will contain no more bits than the bit depth of the
-      Surface. Mapped color values are not often used inside pygame, but can be
-      passed to most functions that require a Surface and a color.
+      Convert a :data:`pygame.typing.ColorLike` into the mapped integer value
+      for this Surface. The returned integer will contain no more bits than the
+      bit depth of the Surface. Mapped color values are not often used inside pygame,
+      but can be passed to most functions that require a Surface and a color.
 
       See the Surface object documentation for more information about colors
       and pixel formats.

docs/reST/ref/transform.rst

@@ -364,7 +364,8 @@ Instead, always begin with the original image and scale to the desired size.)
 
    :param pygame.Surface surface: The target surface.
 
-   :param pygame.Color color: Color which all non transparent within the target surface must be set to.
+   :param color: Color which all non transparent within the target surface must be set to.
+   :type color: :data:`pygame.typing.ColorLike`
 
    :param dest_surface: Optional destination surface to which the changes will be applied.
    :type dest_surface: pygame.Surface or None
@@ -400,15 +401,17 @@ Instead, always begin with the original image and scale to the desired size.)
 
    :param pygame.Surface surf: Surface we are looking at.
 
-   :param pygame.Color search_color: Color we are searching for.
+   :param search_color: Color we are searching for.
+   :type color: :data:`pygame.typing.ColorLike`
 
-   :param pygame.Color threshold: Within this distance from search_color (or search_surf).
+   :param threshold: Within this distance from search_color (or search_surf).
      You can use a threshold of (r,g,b,a) where the r,g,b can have different
      thresholds. So you could use an r threshold of 40 and a blue threshold of 2
      if you like.
+   :type color: :data:`pygame.typing.ColorLike`
 
    :param set_color: Color we set in dest_surf.
-   :type set_color: pygame.Color or None
+   :type color: :data:`pygame.typing.ColorLike` or ``None``
 
    :param int set_behavior:
     - set_behavior=1 (default). Pixels in dest_surface will be changed to 'set_color'.

docs/reST/ref/typing.rst

@@ -60,7 +60,8 @@ type aliases for proper typehint annotations.
         * ``(r, g, b)``
         * ``(r, g, b, a)``
         * ``[r, g, b, a]``
-        * ``"green"``
+        * ``"green"`` (:doc:`color_list`)
+        * ``"#rrggbbaa"``
         * ``0`` (mapped color)
 
    .. data:: RectLike

src_c/doc/surface_doc.h

@@ -9,7 +9,7 @@
 #define DOC_SURFACE_FILL "fill(color, rect=None, special_flags=0) -> Rect\nfill Surface with a solid color"
 #define DOC_SURFACE_SCROLL "scroll(dx=0, dy=0, /) -> None\nshift the surface image in place"
 #define DOC_SURFACE_SETCOLORKEY "set_colorkey(color, flags=0, /) -> None\nset_colorkey(None) -> None\nset the transparent colorkey"
-#define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> RGB or None\nget the current transparent colorkey"
+#define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> RGBA or None\nget the current transparent colorkey"
 #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0, /) -> None\nset_alpha(None) -> None\nset the alpha value for the full Surface"
 #define DOC_SURFACE_GETALPHA "get_alpha() -> int_value\nget the current Surface transparency value"
 #define DOC_SURFACE_LOCK "lock() -> None\nlock the Surface memory for pixel access"
@@ -20,10 +20,10 @@
 #define DOC_SURFACE_GETAT "get_at((x, y), /) -> Color\nget the color value at a single pixel"
 #define DOC_SURFACE_SETAT "set_at((x, y), color, /) -> None\nset the color value for a single pixel"
 #define DOC_SURFACE_GETATMAPPED "get_at_mapped((x, y), /) -> Color\nget the mapped color value at a single pixel"
-#define DOC_SURFACE_GETPALETTE "get_palette() -> [RGB, RGB, RGB, ...]\nget the color index palette for an 8-bit Surface"
-#define DOC_SURFACE_GETPALETTEAT "get_palette_at(index, /) -> RGB\nget the color for a single entry in a palette"
-#define DOC_SURFACE_SETPALETTE "set_palette([RGB, RGB, RGB, ...], /) -> None\nset the color palette for an 8-bit Surface"
-#define DOC_SURFACE_SETPALETTEAT "set_palette_at(index, RGB, /) -> None\nset the color for a single index in an 8-bit Surface palette"
+#define DOC_SURFACE_GETPALETTE "get_palette() -> [Color, Color, Color, ...]\nget the color index palette for an 8-bit Surface"
+#define DOC_SURFACE_GETPALETTEAT "get_palette_at(index, /) -> Color\nget the color for a single entry in a palette"
+#define DOC_SURFACE_SETPALETTE "set_palette([color, color, color, ...], /) -> None\nset the color palette for an 8-bit Surface"
+#define DOC_SURFACE_SETPALETTEAT "set_palette_at(index, color, /) -> None\nset the color for a single index in an 8-bit Surface palette"
 #define DOC_SURFACE_MAPRGB "map_rgb(color, /) -> mapped_int\nconvert a color into a mapped color value"
 #define DOC_SURFACE_UNMAPRGB "unmap_rgb(mapped_int, /) -> Color\nconvert a mapped integer color value into a Color"
 #define DOC_SURFACE_SETCLIP "set_clip(rect, /) -> None\nset_clip(None) -> None\nset the current clipping area of the Surface"