Refactors sprites.BaseSprite

ppb/__init__.py

@@ -1,22 +1,41 @@
 import logging
+import warnings
 from typing import Callable
 
 from ppb import events
 from ppb_vector import Vector
 from ppb.engine import GameEngine
 from ppb.scenes import BaseScene
-from ppb.sprites import BaseSprite
+from ppb.sprites import Sprite
 from ppb.systems import Image
 from ppb.systems import Sound
 
 __all__ = (
     # Shortcuts
-    'Vector', 'BaseScene', 'BaseSprite', 'Image', 'Sound', 'events',
+    'Vector', 'BaseScene', 'BaseSprite', 'Image', 'Sprite', 'Sound',
+    'events',
     # Local stuff
     'run', 'make_engine',
 )
 
 
+class BaseSprite(Sprite):
+    """
+    A stub that raises a deprecation warning when a user uses
+    ``ppb.BaseSprite.``
+    """
+    __warning = """Using ppb.BaseSprite is deprecated.
+
+    You probably want ppb.Sprite. If you're wanting to use BaseSprite and
+    mixins to change what features your sprites have, import
+    ppb.sprites.BaseSprite.
+    """
+
+    def __init__(self, **kwargs):
+        warnings.warn(self.__warning, DeprecationWarning)
+        super().__init__(**kwargs)
+
+
 def _make_kwargs(setup, title, engine_opts):
     kwargs = {
         "resolution": (800, 600),

ppb/sprites.py

@@ -9,6 +9,13 @@
 from ppb.eventlib import EventMixin
 from ppb.utils import FauxFloat
 
+__all__ = (
+    "BaseSprite",
+    "Sprite",
+    "RotatableMixin",
+    "SquareShapeMixin",
+    "RenderableMixin",
+)
 
 TOP = "top"
 BOTTOM = "bottom"
@@ -19,6 +26,113 @@
 side_attribute_error_message = error_message.format
 
 
+class BaseSprite(EventMixin):
+    """
+    The base Sprite class. All sprites should inherit from this (directly or
+    indirectly).
+
+    The things that define a BaseSprite:
+
+    * The __event__ protocol (see ppb.eventlib.EventMixin)
+    * A position vector
+    * A layer
+
+    BaseSprite provides an __init__ method that sets attributes based on kwargs
+    to make rapid prototyping easier.
+    """
+    #: (:py:class:`ppb.Vector`): Location of the sprite
+    position: Vector = Vector(0, 0)
+    #: The layer a sprite exists on.
+    layer: int = 0
+
+    def __init__(self, **kwargs):
+        super().__init__()
+
+        self.position = Vector(self.position)
+
+        # Initialize things
+        for k, v in kwargs.items():
+            # Abbreviations
+            if k == 'pos':
+                k = 'position'
+            # Castings
+            if k == 'position':
+                v = Vector(v)
+            setattr(self, k, v)
+
+
+class RenderableMixin:
+    """
+    A class implementing the API expected by ppb.systems.renderer.Renderer.
+
+    You should include RenderableMixin after BaseSprite in your parent class
+    definitions.
+    """
+    #: (:py:class:`ppb.Image`): The image asset
+    image = None  # TODO: Type hint appropriately
+
+    def __image__(self):
+        """
+        Returns the sprite's image attribute if provided, or sets a default
+        one.
+        """
+        if self.image is None:
+            klass = type(self)
+            prefix = Path(klass.__module__.replace('.', '/'))
+            try:
+                klassfile = getfile(klass)
+            except TypeError:
+                prefix = Path('.')
+            else:
+                if Path(klassfile).name != '__init__.py':
+                    prefix = prefix.parent
+            if prefix == Path('.'):
+                self.image = ppb.Image(f"{klass.__name__.lower()}.png")
+            else:
+                self.image = ppb.Image(f"{prefix!s}/{klass.__name__.lower()}.png")
+        return self.image
+
+
+class RotatableMixin:
+    """
+    A simple rotation mixin. Can be included with sprites.
+    """
+    _rotation = 0
+    # This is necessary to make facing do the thing while also being adjustable.
+    #: The baseline vector, representing the "front" of the sprite
+    basis = Vector(0, -1)
+    # Considered making basis private, the only reason to do so is to
+    # discourage people from relying on it as data.
+
+    @property
+    def facing(self):
+        """
+        The direction the "front" is facing
+        """
+        return Vector(*self.basis).rotate(self.rotation).normalize()
+
+    @facing.setter
+    def facing(self, value):
+        self.rotation = self.basis.angle(value)
+
+    @property
+    def rotation(self):
+        """
+        The amount the sprite is rotated, in degrees
+        """
+        return self._rotation
+
+    @rotation.setter
+    def rotation(self, value):
+        self._rotation = value % 360
+
+    def rotate(self, degrees):
+        """
+        Rotate the sprite by a given angle (in degrees).
+        """
+        self.rotation += degrees
+
+
 class Side(FauxFloat):
     """
     Acts like a float, but also has a variety of accessors.
@@ -30,7 +144,7 @@ class Side(FauxFloat):
         BOTTOM: ('y', -1)
     }
 
-    def __init__(self, parent: 'BaseSprite', side: str):
+    def __init__(self, parent: 'SquareShapeMixin', side: str):
         self.side = side
         self.parent = parent
 
@@ -165,74 +279,20 @@ def _attribute_gate(self, attribute, bad_sides):
             raise AttributeError(message)
 
 
-class Rotatable:
+class SquareShapeMixin:
     """
-    A simple rotation mixin. Can be included with sprites.
-    """
-    _rotation = 0
-    # This is necessary to make facing do the thing while also being adjustable.
-    #: The baseline vector, representing the "front" of the sprite
-    basis = Vector(0, -1)
-    # Considered making basis private, the only reason to do so is to
-    # discourage people from relying on it as data.
-
-    @property
-    def facing(self):
-        """
-        The direction the "front" is facing
-        """
-        return Vector(*self.basis).rotate(self.rotation).normalize()
-
-    @facing.setter
-    def facing(self, value):
-        self.rotation = self.basis.angle(value)
-
-    @property
-    def rotation(self):
-        """
-        The amount the sprite is rotated, in degrees
-        """
-        return self._rotation
-
-    @rotation.setter
-    def rotation(self, value):
-        self._rotation = value % 360
-
-    def rotate(self, degrees):
-        """
-        Rotate the sprite by a given angle (in degrees).
-        """
-        self.rotation += degrees
-
+    A mixin that applies square shapes to sprites.
 
-class BaseSprite(EventMixin, Rotatable):
+    You should include SquareShapeMixin after ppb.sprites.BaseSprite in
+    your parent classes.
     """
-    The base Sprite class. All sprites should inherit from this (directly or
-    indirectly).
-    """
-    #: (:py:class:`ppb.Image`): The image asset
-    image = None
-    #: (:py:class:`ppb.Vector`): Location of the sprite
-    position: Vector = Vector(0, 0)
     #: The width/height of the sprite (sprites are square)
     size: Union[int, float] = 1
-    #: The layer a sprite exists on.
-    layer: int = 0
+    #: Just here for typing and linting purposes. Your sprite should already have a position.
+    position: ppb_vector.Vector
 
     def __init__(self, **kwargs):
-        super().__init__()
-
-        self.position = Vector(self.position)
-
-        # Initialize things
-        for k, v in kwargs.items():
-            # Abbreviations
-            if k == 'pos':
-                k = 'position'
-            # Castings
-            if k == 'position':
-                v = Vector(v)
-            setattr(self, k, v)
+        super().__init__(**kwargs)
 
         # Trigger some calculations
         self.size = self.size
@@ -296,19 +356,17 @@ def bottom(self, value):
     def _offset_value(self):
         return self.size / 2
 
-    def __image__(self):
-        if self.image is None:
-            klass = type(self)
-            prefix = Path(klass.__module__.replace('.', '/'))
-            try:
-                klassfile = getfile(klass)
-            except TypeError:
-                prefix = Path('.')
-            else:
-                if Path(klassfile).name != '__init__.py':
-                    prefix = prefix.parent
-            if prefix == Path('.'):
-                self.image = ppb.Image(f"{klass.__name__.lower()}.png")
-            else:
-                self.image = ppb.Image(f"{prefix!s}/{klass.__name__.lower()}.png")
-        return self.image
+
+class Sprite(BaseSprite, SquareShapeMixin, RenderableMixin, RotatableMixin):
+    """
+    The default Sprite class.
+
+    Sprite includes:
+
+    * BaseSprite
+    * SquareShapeMixin
+    * RenderableMixin
+    * RotatableMixin
+
+    New in 0.7.0: Use this in place of BaseSprite in your games.
+    """

ppb/systems/renderer.py

@@ -15,6 +15,8 @@
 DEFAULT_RESOLUTION = 800, 600
 
 
+# TODO: Move Image out of the renderer so sprites can type hint
+#  appropriately.
 class Image(assets.Asset):
     def background_parse(self, data):
         return pygame.image.load(io.BytesIO(data), self.name).convert_alpha()