Split ext error handling into a separate module

Author: a-hurst

doc/modules/ext/err.rst

@@ -0,0 +1,9 @@
+`sdl2.ext.err` - Handling & Raising SDL Errors
+==============================================
+
+This module defines a Python exception class for representing internal SDL2
+errors, as well as convenience functions for cleanly handling and raising
+SDL errors in Python code.
+
+.. automodule:: sdl2.ext.err
+	:members:

doc/modules/sdl2ext.rst

@@ -49,6 +49,7 @@ objects to Numpy arrays:
 .. toctree::
 	:maxdepth: 1
 
+	ext/err.rst
 	ext/compat.rst
 	ext/array.rst
 	ext/pixelaccess.rst

doc/news.rst

@@ -16,13 +16,20 @@ New Features:
   initialize the audio subsystem as well as the default video subsystem).
   Previously, this function only initailized the video subsystem.
 * Updated to wrap new functions and constants in SDL2 2.24.0 (PR #246).
+* Added the error-handling :func:`sdl2.ext.raise_sdl_err` function to the public
+  API.
 
 Fixed Bugs:
 
 * Fixed broken behaviour (and potential segfaults) with usage of
   :func:`sdl2.SDL_GUIDToString` on Python 3.6 and older (PR #246).
 * Fixed :func:`sdl2.ext.draw` when drawing on 1bpp surfaces (PR #242).
 
+API Changes:
+
+* Moved :class:`sdl2.ext.SDLError` and :func:`sdl2.ext.raise_sdl_err`
+  internally to a new submodule :mod:`sdl2.ext.err`.
+
 
 0.9.13
 ------

sdl2/ext/__init__.py

@@ -11,6 +11,7 @@
 from .events import *
 from .ebs import *
 
+from .err import *
 from .common import *
 from .draw import *
 from .bitmapfont import *

sdl2/ext/bitmapfont.py

@@ -1,5 +1,5 @@
 from .. import surface, rect, pixels
-from .common import SDLError, raise_sdl_err
+from .err import SDLError, raise_sdl_err
 from .sprite import SoftwareSprite
 from .surface import _get_target_surface
 from .image import load_bmp

sdl2/ext/common.py

@@ -4,6 +4,7 @@
     SDL_INIT_VIDEO, SDL_INIT_AUDIO, SDL_INIT_TIMER, SDL_INIT_HAPTIC,
     SDL_INIT_JOYSTICK, SDL_INIT_GAMECONTROLLER, SDL_INIT_SENSOR, SDL_INIT_EVENTS,
 )
+from .err import raise_sdl_err
 
 _HASSDLTTF = True
 try:
@@ -16,7 +17,7 @@
 except ImportError:
     _HASSDLIMAGE = False
 
-__all__ = ["SDLError", "init", "quit", "get_events", "TestEventProcessor"]
+__all__ = ["init", "quit", "get_events", "TestEventProcessor"]
 
 
 _sdl_subsystems = {
@@ -31,38 +32,6 @@
 }
 
 
-class SDLError(Exception):
-    """An SDL2-specific exception class."""
-
-    def __init__(self, msg=None):
-        """Creates a new SDLError instance with the specified message.
-
-        If no msg is passed, it will try to get the current SDL2 error via
-        :func:`sdl2.SDL_GetError`.
-
-        """
-        super(SDLError, self).__init__()
-        self.msg = msg
-        if not msg:
-            self.msg = error.SDL_GetError()
-            error.SDL_ClearError()
-
-    def __str__(self):
-        return repr(self.msg)
-
-
-def raise_sdl_err(desc=None):
-    # Raises and clears the latest SDL error. For internal use.
-    errmsg = error.SDL_GetError().decode('utf-8')
-    error.SDL_ClearError()
-    e = "Error encountered"
-    if desc:
-        e += " " + desc
-    if len(errmsg):
-        e += ": {0}".format(errmsg)
-    raise SDLError(e)
-
-
 def init(
     video=True, audio=False, timer=False, joystick=False, controller=False,
     haptic=False, sensor=False, events=True

sdl2/ext/draw.py

@@ -1,6 +1,6 @@
 import ctypes
 from .compat import isiterable, UnsupportedError
-from .common import raise_sdl_err
+from .err import raise_sdl_err
 from .array import to_ctypes
 from .color import convert_to_color
 from .. import surface, pixels, rect

sdl2/ext/err.py

@@ -0,0 +1,57 @@
+from .. import error
+
+__all__ = ["SDLError", "raise_sdl_err"]
+
+
+class SDLError(Exception):
+    """A custom exception class for SDL2-specific errors.
+    
+    Args:
+        msg (str, optional): The error message for the exception. If not
+            provided, the current SDL error (if any) will be retrieved using
+            `:func:~sdl2.SDL_GetError`.
+    """
+
+    def __init__(self, msg=None):
+        super(SDLError, self).__init__()
+        self.msg = msg
+        if not msg:
+            self.msg = error.SDL_GetError()
+            error.SDL_ClearError()
+
+    def __str__(self):
+        return repr(self.msg)
+
+
+def raise_sdl_err(desc=None):
+    """Raises an exception for an internal SDL error.
+    
+    The format of the exception message depends on whether a description is
+    provided and whether `:func:~sdl2.SDL_GetError` returns an error string.
+    If a description is given, it will be appended after the default text
+    ``Error encountered``. If SDL has set an error string, it will be appended
+    to the end of the message following a colon (clearing the error in the
+    process).
+    
+    For example, if ``SDL_GetError() == b"unsupported pixel format"`` and the
+    function is called as ``raise_sdl_err("creating the surface")``, the
+    resulting exception message will be "Error encountered creating the surface:
+    unsupported pixel format".
+
+    Args:
+        desc (str. optional): A description of what SDL was trying to do when
+            the error occurred. Will be placed after the text "Error encountered"
+            in the exception message if provided.
+
+    Raises:
+        :exc:`~SDLError`: An exception explaining the most recent SDL error.
+
+    """
+    errmsg = error.SDL_GetError().decode('utf-8')
+    error.SDL_ClearError()
+    e = "Error encountered"
+    if desc:
+        e += " " + desc
+    if len(errmsg):
+        e += ": {0}".format(errmsg)
+    raise SDLError(e)

sdl2/ext/image.py

@@ -1,6 +1,6 @@
 import os
 from .. import endian, surface, pixels, error, rwops
-from .common import raise_sdl_err
+from .err import raise_sdl_err
 from .compat import UnsupportedError, byteify, stringify
 from .resources import _validate_path
 from .surface import _get_target_surface

sdl2/ext/msgbox.py

@@ -1,7 +1,7 @@
 from ctypes import byref, c_int
 from .color import Color
 from .compat import isiterable, utf8
-from .common import raise_sdl_err
+from .err import raise_sdl_err
 from .window import Window
 from .. import dll, SDL_PumpEvents, SDL_Window
 from .. import messagebox as mb