Merge pull request #2036 from pygame-community/sprite-deprecations

Undocument and deprecate redundant sprite group classes

Author: oddbookworm

docs/reST/ref/sprite.rst

@@ -203,7 +203,8 @@ Sprites are not thread safe. So lock them yourself if using threads.
 
    A simple container for Sprite objects. This class can be inherited to create
    containers with more specific behaviors. The constructor takes any number of
-   Sprite arguments to add to the Group. The group supports the following
+   Sprite arguments to add to the Group. All sprites in groups are stored in the
+   order they were added to the group. The group supports the following
    standard Python operations:
 
    ::
@@ -297,8 +298,7 @@ Sprites are not thread safe. So lock them yourself if using threads.
       ``Sprite.image`` attribute for the source surface, and ``Sprite.rect``
       for the position.
 
-      The Group does not keep sprites in any order, so the draw order is
-      arbitrary.
+      The Group keeps sprites in the order they were added, they will be drawn in this order.
 
       .. ## Group.draw ##
 
@@ -337,22 +337,6 @@ Sprites are not thread safe. So lock them yourself if using threads.
 
    .. ## pygame.sprite.Group ##
 
-.. class:: RenderPlain
-
-   | :sl:`Same as pygame.sprite.Group`
-
-   This class is an alias to ``pygame.sprite.Group()``. It has no additional functionality.
-
-   .. ## pygame.sprite.RenderClear ##
-
-.. class:: RenderClear
-
-   | :sl:`Same as pygame.sprite.Group`
-
-   This class is an alias to ``pygame.sprite.Group()``. It has no additional functionality.
-
-   .. ## pygame.sprite.RenderClear ##
-
 .. class:: RenderUpdates
 
    | :sl:`Group sub-class that tracks dirty updates.`
@@ -380,18 +364,6 @@ Sprites are not thread safe. So lock them yourself if using threads.
 
    .. ## pygame.sprite.RenderUpdates ##
 
-.. function:: OrderedUpdates
-
-   | :sl:`RenderUpdates sub-class that draws Sprites in order of addition.`
-   | :sg:`OrderedUpdates(*sprites) -> OrderedUpdates`
-
-   This class derives from ``pygame.sprite.RenderUpdates()``. It maintains the
-   order in which the Sprites were added to the Group for rendering. This makes
-   adding and removing Sprites from the Group a little slower than regular
-   Groups.
-
-   .. ## pygame.sprite.OrderedUpdates ##
-
 .. class:: LayeredUpdates
 
    | :sl:`LayeredUpdates is a sprite group that handles layers and draws like OrderedUpdates.`

src_c/doc/sprite_doc.h

@@ -18,11 +18,8 @@
 #define DOC_SPRITE_GROUP_DRAW "draw(Surface) -> List[Rect]\nblit the Sprite images"
 #define DOC_SPRITE_GROUP_CLEAR "clear(Surface_dest, background) -> None\ndraw a background over the Sprites"
 #define DOC_SPRITE_GROUP_EMPTY "empty() -> None\nremove all Sprites"
-#define DOC_SPRITE_RENDERPLAIN "Same as pygame.sprite.Group"
-#define DOC_SPRITE_RENDERCLEAR "Same as pygame.sprite.Group"
 #define DOC_SPRITE_RENDERUPDATES "RenderUpdates(*sprites) -> RenderUpdates\nGroup sub-class that tracks dirty updates."
 #define DOC_SPRITE_RENDERUPDATES_DRAW "draw(surface) -> Rect_list\nblit the Sprite images and track changed areas"
-#define DOC_SPRITE_ORDEREDUPDATES "OrderedUpdates(*sprites) -> OrderedUpdates\nRenderUpdates sub-class that draws Sprites in order of addition."
 #define DOC_SPRITE_LAYEREDUPDATES "LayeredUpdates(*sprites, **kwargs) -> LayeredUpdates\nLayeredUpdates is a sprite group that handles layers and draws like OrderedUpdates."
 #define DOC_SPRITE_LAYEREDUPDATES_ADD "add(*sprites, **kwargs) -> None\nadd a sprite or sequence of sprites to a group"
 #define DOC_SPRITE_LAYEREDUPDATES_SPRITES "sprites() -> sprites\nreturns a ordered list of sprites (first back, last top)."

src_py/sprite.py

@@ -655,8 +655,24 @@ def __init__(self, *sprites):
         self.add(*sprites)
 
 
-RenderPlain = Group
-RenderClear = Group
+class RenderPlain(Group):
+    def __init__(self, *sprites):
+        super().__init__(*sprites)
+        warn(
+            "This class will be removed in version 2.4.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+
+class RenderClear(Group):
+    def __init__(self, *sprites):
+        super().__init__(*sprites)
+        warn(
+            "This class will be removed in version 2.4.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
 
 class RenderUpdates(Group):
@@ -690,31 +706,15 @@ def draw(self, surface):
 
 
 class OrderedUpdates(RenderUpdates):
-    """RenderUpdates class that draws Sprites in order of addition
-
-    pygame.sprite.OrderedUpdates(*sprites): return OrderedUpdates
-
-    This class derives from pygame.sprite.RenderUpdates().  It maintains
-    the order in which the Sprites were added to the Group for rendering.
-    This makes adding and removing Sprites from the Group a little
-    slower than regular Groups.
-
-    """
-
     def __init__(self, *sprites):
-        self._spritelist = []
-        RenderUpdates.__init__(self, *sprites)
-
-    def sprites(self):
-        return self._spritelist.copy()
-
-    def add_internal(self, sprite, layer=None):
-        RenderUpdates.add_internal(self, sprite)
-        self._spritelist.append(sprite)
-
-    def remove_internal(self, sprite):
-        RenderUpdates.remove_internal(self, sprite)
-        self._spritelist.remove(sprite)
+        super().__init__(*sprites)
+        warn(
+            "OrderedUpdates is now just an alias to RenderUpdates, order of "
+            "sprites is now maintained in all sprite Group classes. This "
+            "class will be removed in version 2.4.0",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
 
 class LayeredUpdates(AbstractGroup):