Fix average_color docs and stubs to match implementation (#3076)

* Fix average_color docs and stubs to match implementation

* Use RGBATuple for average_color and don't use it when it's not an RGBA tuple.

buildconfig/stubs/pygame/display.pyi

@@ -11,7 +11,6 @@ from pygame.typing import (
     Coordinate,
     IntCoordinate,
     RectLike,
-    RGBATuple,
     SequenceLike,
 )
 
@@ -21,9 +20,9 @@ class _VidInfo:
     video_mem: int
     bitsize: int
     bytesize: int
-    masks: RGBATuple
-    shifts: RGBATuple
-    losses: RGBATuple
+    masks: Tuple[int, int, int, int]
+    shifts: Tuple[int, int, int, int]
+    losses: Tuple[int, int, int, int]
     blit_hw: int
     blit_hw_CC: int
     blit_hw_A: int

buildconfig/stubs/pygame/surface.pyi

@@ -152,13 +152,13 @@ class Surface:
     def get_bytesize(self) -> int: ...
     def get_flags(self) -> int: ...
     def get_pitch(self) -> int: ...
-    def get_masks(self) -> RGBATuple: ...
+    def get_masks(self) -> Tuple[int, int, int, int]: ...
     @deprecated("since 2.0.0. Immutable in SDL2")
     def set_masks(self, color: ColorLike, /) -> None: ...
-    def get_shifts(self) -> RGBATuple: ...
+    def get_shifts(self) -> Tuple[int, int, int, int]: ...
     @deprecated("since 2.0.0. Immutable in SDL2")
     def set_shifts(self, color: ColorLike, /) -> None: ...
-    def get_losses(self) -> RGBATuple: ...
+    def get_losses(self) -> Tuple[int, int, int, int]: ...
     def get_bounding_rect(self, min_alpha: int = 1) -> Rect: ...
     def get_view(self, kind: _ViewKind = "2", /) -> BufferProxy: ...
     def get_buffer(self) -> BufferProxy: ...

buildconfig/stubs/pygame/transform.pyi

@@ -1,9 +1,8 @@
 from typing import Optional, Union, Literal
 
-from pygame.color import Color
 from pygame.surface import Surface
 
-from pygame.typing import ColorLike, Coordinate, RectLike, SequenceLike
+from pygame.typing import ColorLike, Coordinate, RectLike, SequenceLike, RGBATuple
 
 def flip(surface: Surface, flip_x: bool, flip_y: bool) -> Surface: ...
 def scale(
@@ -42,7 +41,7 @@ def average_surfaces(
 ) -> Surface: ...
 def average_color(
     surface: Surface, rect: Optional[RectLike] = None, consider_alpha: bool = False
-) -> Color: ...
+) -> RGBATuple: ...
 def threshold(
     dest_surface: Optional[Surface],
     surface: Surface,

docs/reST/ref/transform.rst

@@ -306,11 +306,12 @@ Instead, always begin with the original image and scale to the desired size.)
 .. function:: average_color
 
    | :sl:`finds the average color of a surface`
-   | :sg:`average_color(surface, rect=None, consider_alpha=False) -> Color`
+   | :sg:`average_color(surface, rect=None, consider_alpha=False) -> tuple`
 
    Finds the average color of a Surface or a region of a surface specified by a
-   Rect, and returns it as a Color. If consider_alpha is set to True, then alpha is
-   taken into account (removing the black artifacts).
+   Rect, and returns it as a tuple of integers red, green, blue, and alpha.
+   If consider_alpha is set to True, then alpha is taken into account
+   (removing the black artifacts).
 
    .. versionaddedold:: 2.1.2 ``consider_alpha`` argument
 

src_c/doc/transform_doc.h

@@ -15,7 +15,7 @@
 #define DOC_TRANSFORM_BOXBLUR "box_blur(surface, radius, repeat_edge_pixels=True, dest_surface=None) -> Surface\nblur a surface using box blur"
 #define DOC_TRANSFORM_GAUSSIANBLUR "gaussian_blur(surface, radius, repeat_edge_pixels=True, dest_surface=None) -> Surface\nblur a surface using gaussian blur"
 #define DOC_TRANSFORM_AVERAGESURFACES "average_surfaces(surfaces, dest_surface=None, palette_colors=1) -> Surface\nfind the average surface from many surfaces."
-#define DOC_TRANSFORM_AVERAGECOLOR "average_color(surface, rect=None, consider_alpha=False) -> Color\nfinds the average color of a surface"
+#define DOC_TRANSFORM_AVERAGECOLOR "average_color(surface, rect=None, consider_alpha=False) -> tuple\nfinds the average color of a surface"
 #define DOC_TRANSFORM_INVERT "invert(surface, dest_surface=None) -> Surface\ninverts the RGB elements of a surface"
 #define DOC_TRANSFORM_GRAYSCALE "grayscale(surface, dest_surface=None) -> Surface\ngrayscale a surface"
 #define DOC_TRANSFORM_THRESHOLD "threshold(dest_surface, surface, search_color, threshold=(0,0,0,0), set_color=(0,0,0,0), set_behavior=1, search_surf=None, inverse_set=False) -> num_threshold_pixels\nfinds which, and how many pixels in a surface are within a threshold of a 'search_color' or a 'search_surf'."