Merge pull request #3249 from aatle/lazy-numpy

New approach to lazy loading of pygame submodules (`surfarray`, `sndarray`)

Author: MyreMylar

docs/reST/ref/sndarray.rst

@@ -23,6 +23,8 @@ Each sample is an 8-bit or 16-bit integer, depending on the data format. A
 stereo sound file has two values per sample, while a mono sound file only has
 one.
 
+.. versionchanged:: 2.5.6 sndarray module is lazily loaded to avoid an expensive NumPy import when unnecessary
+
 .. function:: array
 
    | :sl:`copy Sound samples into an array`

docs/reST/ref/surfarray.rst

@@ -35,6 +35,8 @@ pixels from the surface and any changes performed to the array will make changes
 in the surface. As this last functions share memory with the surface, this one
 will be locked during the lifetime of the array.
 
+.. versionchanged:: 2.5.6 surfarray module is lazily loaded to avoid an expensive NumPy import when unnecessary
+
 .. function:: array2d
 
    | :sl:`Copy pixels into a 2d array`

src_py/__init__.py

@@ -73,9 +73,13 @@ class MissingModule:
 
     def __init__(self, name, urgent=0):
         self.name = name
-        exc_type, exc_msg = sys.exc_info()[:2]
-        self.info = str(exc_msg)
-        self.reason = f"{exc_type.__name__}: {self.info}"
+        exc_type, exc_msg, _ = sys.exc_info()
+        if exc_type is not None:
+            self.info = str(exc_msg)
+            self.reason = f"{exc_type.__name__}: {self.info}"
+        else:
+            self.info = "<no info>"
+            self.reason = f"<no exception>: {self.info}"
         self.urgent = urgent
         if urgent:
             self.warn()
@@ -302,15 +306,57 @@ def PixelArray(surface):  # pylint: disable=unused-argument
 except (ImportError, OSError):
     scrap = MissingModule("scrap", urgent=0)
 
+# Two lazily imported modules to avoid loading numpy unnecessarily
+
+from importlib.util import LazyLoader, find_spec, module_from_spec
+
+
+def lazy_import(name):
+    """Lazily import a pygame module.
+
+    See https://docs.python.org/3/library/importlib.html#implementing-lazy-imports
+    Only load the module upon its first attribute access.
+
+    Lazily imported modules are directly referenced in packager_imports function.
+    """
+    fullname = "pygame." + name
+    spec = find_spec(fullname)
+    if spec is None or spec.loader is None:
+        return MissingModule(name, urgent=0)
+    loader = LazyLoader(spec.loader)
+    spec.loader = loader
+    module = module_from_spec(spec)
+    sys.modules[fullname] = module
+    loader.exec_module(module)
+    return module
+
+
+# Check if numpy is available for surfarray and sndarray modules
+numpy_missing = find_spec("numpy") is None
+
 try:
-    import pygame.surfarray
+    if numpy_missing:
+        # Always fails here. Need the error message for MissingModule.reason
+        import numpy  # pylint: disable=ungrouped-imports
+    # Check that module dependencies are not missing, or get error message
+    import pygame.pixelcopy  # pylint: disable=ungrouped-imports
 except (ImportError, OSError):
     surfarray = MissingModule("surfarray", urgent=0)
+else:
+    surfarray = lazy_import("surfarray")
 
 try:
-    import pygame.sndarray
+    if numpy_missing:
+        # Always fails here. Need the error message for MissingModule.reason
+        import numpy  # pylint: disable=ungrouped-imports
+    # Check that module dependencies are not missing, or get error message
+    import pygame.mixer  # pylint: disable=ungrouped-imports
 except (ImportError, OSError):
     sndarray = MissingModule("sndarray", urgent=0)
+else:
+    sndarray = lazy_import("sndarray")
+
+del LazyLoader, find_spec, lazy_import, module_from_spec, numpy_missing
 
 try:
     import pygame._debug
@@ -361,13 +407,21 @@ def Window(title="pygame window", size=(640, 480), position=None, **kwargs):  #
 
 
 def packager_imports():
-    """some additional imports that py2app/py2exe will want to see"""
+    """Some additional imports that py2app/py2exe will want to see.
+
+    This function is never executed.
+    Some tools scan the source code for import statements.
+    """
     import atexit
     import numpy
     import OpenGL.GL
     import pygame.macosx
     import pygame.colordict
 
+    # lazy imports
+    import pygame.surfarray
+    import pygame.sndarray
+
 
 # make Rects pickleable