PR: Improve import modularity between QtGui, QtWidgets and QtOpenGL* related modules (#387)

Author: dalthviz

qtpy/QtGui.py

@@ -8,7 +8,35 @@
 
 """Provides QtGui classes and functions."""
 
-from . import PYQT6, PYQT5, PYSIDE2, PYSIDE6
+from . import PYQT6, PYQT5, PYSIDE2, PYSIDE6, QtModuleNotInstalledError
+from .utils import getattr_missing_optional_dep
+
+
+_missing_optional_names = {}
+
+_QTOPENGL_NAMES = {
+    'QOpenGLBuffer',
+    'QOpenGLContext',
+    'QOpenGLContextGroup',
+    'QOpenGLDebugLogger',
+    'QOpenGLDebugMessage',
+    'QOpenGLFramebufferObject',
+    'QOpenGLFramebufferObjectFormat',
+    'QOpenGLPixelTransferOptions',
+    'QOpenGLShader',
+    'QOpenGLShaderProgram',
+    'QOpenGLTexture',
+    'QOpenGLTextureBlitter',
+    'QOpenGLVersionProfile',
+    'QOpenGLVertexArrayObject',
+    'QOpenGLWindow',
+}
+
+def __getattr__(name):
+    """Custom getattr to chain and wrap errors due to missing optional deps."""
+    raise getattr_missing_optional_dep(
+        name, module_name=__name__, optional_names=_missing_optional_names)
+
 
 if PYQT5:
     from PyQt5.QtGui import *
@@ -18,7 +46,20 @@
 elif PYQT6:
     from PyQt6 import QtGui
     from PyQt6.QtGui import *
-    from PyQt6.QtOpenGL import *
+
+    # Attempt to import QOpenGL* classes, but if that fails,
+    # don't raise an exception until the name is explicitly accessed.
+    # See https://github.com/spyder-ide/qtpy/pull/387/
+    try:
+        from PyQt6.QtOpenGL import *
+    except ImportError as error:
+        for name in _QTOPENGL_NAMES:
+            _missing_optional_names[name] = {
+                'name': 'PyQt6.QtOpenGL',
+                'missing_package': 'pyopengl',
+                'import_error': error,
+            }
+
     QFontMetrics.width = lambda self, *args, **kwargs: self.horizontalAdvance(*args, **kwargs)
     QFontMetricsF.width = lambda self, *args, **kwargs: self.horizontalAdvance(*args, **kwargs)
 
@@ -42,7 +83,19 @@
         QFontMetrics.width = lambda self, *args, **kwargs: self.horizontalAdvance(*args, **kwargs)
 elif PYSIDE6:
     from PySide6.QtGui import *
-    from PySide6.QtOpenGL import *
+
+    # Attempt to import QOpenGL* classes, but if that fails,
+    # don't raise an exception until the name is explicitly accessed.
+    # See https://github.com/spyder-ide/qtpy/pull/387/
+    try:
+        from PySide6.QtOpenGL import *
+    except ImportError as error:
+        for name in _QTOPENGL_NAMES:
+            _missing_optional_names[name] = {
+                'name': 'PySide6.QtOpenGL',
+                'missing_package': 'pyopengl',
+                'import_error': error,
+            }
 
     # Backport `QFileSystemModel` moved to QtGui in Qt6
     from PySide6.QtWidgets import QFileSystemModel
@@ -121,3 +174,4 @@ def movePositionPatched(
     QSinglePointEvent.globalPos = lambda self: self.globalPosition().toPoint()
     QSinglePointEvent.globalX = lambda self: self.globalPosition().toPoint().x()
     QSinglePointEvent.globalY = lambda self: self.globalPosition().toPoint().y()
+

qtpy/QtWidgets.py

@@ -8,15 +8,36 @@
 
 """Provides widget classes and functions."""
 
-from . import PYQT5, PYQT6, PYSIDE2, PYSIDE6
+from . import PYQT5, PYQT6, PYSIDE2, PYSIDE6, QtModuleNotInstalledError
+from .utils import getattr_missing_optional_dep
+
+
+_missing_optional_names = {}
+
+def __getattr__(name):
+    """Custom getattr to chain and wrap errors due to missing optional deps."""
+    raise getattr_missing_optional_dep(
+        name, module_name=__name__, optional_names=_missing_optional_names)
+
 
 if PYQT5:
     from PyQt5.QtWidgets import *
 elif PYQT6:
     from PyQt6 import QtWidgets
     from PyQt6.QtWidgets import *
     from PyQt6.QtGui import QAction, QActionGroup, QShortcut, QFileSystemModel, QUndoCommand
-    from PyQt6.QtOpenGLWidgets import QOpenGLWidget
+
+    # Attempt to import QOpenGLWidget, but if that fails,
+    # don't raise an exception until the name is explicitly accessed.
+    # See https://github.com/spyder-ide/qtpy/pull/387/
+    try:
+        from PyQt6.QtOpenGLWidgets import QOpenGLWidget
+    except ImportError as error:
+        _missing_optional_names['QOpenGLWidget'] = {
+           'name': 'PyQt6.QtOpenGLWidgets',
+           'missing_package': 'pyopengl',
+           'import_error': error,
+        }
 
     # Map missing/renamed methods
     QTextEdit.setTabStopWidth = lambda self, *args, **kwargs: self.setTabStopDistance(*args, **kwargs)
@@ -39,7 +60,18 @@
 elif PYSIDE6:
     from PySide6.QtWidgets import *
     from PySide6.QtGui import QAction, QActionGroup, QShortcut, QUndoCommand
-    from PySide6.QtOpenGLWidgets import QOpenGLWidget
+
+    # Attempt to import QOpenGLWidget, but if that fails,
+    # don't raise an exception until the name is explicitly accessed.
+    # See https://github.com/spyder-ide/qtpy/pull/387/
+    try:
+        from PySide6.QtOpenGLWidgets import QOpenGLWidget
+    except ImportError as error:
+        _missing_optional_names['QOpenGLWidget'] = {
+           'name': 'PySide6.QtOpenGLWidgets',
+           'missing_package': 'pyopengl',
+           'import_error': error,
+        }
 
     # Map missing/renamed methods
     QTextEdit.setTabStopWidth = lambda self, *args, **kwargs: self.setTabStopDistance(*args, **kwargs)
@@ -52,3 +84,4 @@
     QApplication.exec_ = QApplication.exec
     QDialog.exec_ = lambda self, *args, **kwargs: self.exec(*args, **kwargs)
     QMenu.exec_ = lambda self, *args, **kwargs: self.exec(*args, **kwargs)
+

qtpy/tests/optional_deps/__init__.py

@@ -0,0 +1,27 @@
+"""Package used for testing the deferred import error mechanism."""
+
+
+# See https://github.com/spyder-ide/qtpy/pull/387/
+
+
+from qtpy.utils import getattr_missing_optional_dep
+from .optional_dep import ExampleClass
+
+
+_missing_optional_names = {}
+
+
+try:
+    from .optional_dep import MissingClass
+except ImportError as error:
+    _missing_optional_names['MissingClass'] = {
+        'name': 'optional_dep.MissingClass',
+        'missing_package': 'test_package_please_ignore',
+        'import_error': error,
+    }
+
+
+def __getattr__(name):
+    """Custom getattr to chain and wrap errors due to missing optional deps."""
+    raise getattr_missing_optional_dep(
+        name, module_name=__name__, optional_names=_missing_optional_names)

qtpy/tests/optional_deps/optional_dep.py

@@ -0,0 +1,4 @@
+"""Test module with an optional dependency that may be missing."""
+
+class ExampleClass:
+    pass

qtpy/tests/test_missing_optional_deps.py

@@ -0,0 +1,22 @@
+"""Test the deferred import error mechanism"""
+
+
+# See https://github.com/spyder-ide/qtpy/pull/387/
+
+
+import pytest
+
+from qtpy import QtModuleNotInstalledError
+
+
+def test_missing_optional_deps():
+    """Test importing a module that uses the deferred import error mechanism"""
+    from . import optional_deps
+
+    assert optional_deps.ExampleClass is not None
+
+    with pytest.raises(QtModuleNotInstalledError) as excinfo:
+        from .optional_deps import MissingClass
+    
+    msg = 'The optional_dep.MissingClass module was not found. It must be installed separately as test_package_please_ignore.'
+    assert msg == str(excinfo.value)

qtpy/tests/test_qtgui.py

@@ -132,3 +132,28 @@ def test_qtextcursor_moveposition():
     assert cursor.position() == cursor.anchor()
     assert cursor.movePosition(QtGui.QTextCursor.NextWord, QtGui.QTextCursor.KeepAnchor, 3)
     assert cursor.selectedText() == "foo bar baz"
+
+
+def test_opengl_imports():
+    """
+    Test for presence of QOpenGL* classes.
+
+    These classes were members of QtGui in Qt5, but moved to QtOpenGL in Qt6.
+    QtPy makes them available in QtGui to maintain compatibility.
+    """
+
+    assert QtGui.QOpenGLBuffer is not None
+    assert QtGui.QOpenGLContext is not None
+    assert QtGui.QOpenGLContextGroup is not None
+    assert QtGui.QOpenGLDebugLogger is not None
+    assert QtGui.QOpenGLDebugMessage is not None
+    assert QtGui.QOpenGLFramebufferObject is not None
+    assert QtGui.QOpenGLFramebufferObjectFormat is not None
+    assert QtGui.QOpenGLPixelTransferOptions is not None
+    assert QtGui.QOpenGLShader is not None
+    assert QtGui.QOpenGLShaderProgram is not None
+    assert QtGui.QOpenGLTexture is not None
+    assert QtGui.QOpenGLTextureBlitter is not None
+    assert QtGui.QOpenGLVersionProfile is not None
+    assert QtGui.QOpenGLVertexArrayObject is not None
+    assert QtGui.QOpenGLWindow is not None

qtpy/tests/test_qtwidgets.py

@@ -116,3 +116,13 @@ def test_enum_access():
     assert QtWidgets.QStyle.State_None == QtWidgets.QStyle.StateFlag.State_None
     assert QtWidgets.QSlider.TicksLeft == QtWidgets.QSlider.TickPosition.TicksAbove
     assert QtWidgets.QStyle.SC_SliderGroove == QtWidgets.QStyle.SubControl.SC_SliderGroove
+
+
+def test_opengl_imports():
+    """
+    Test for presence of QOpenGLWidget.
+
+    QOpenGLWidget was a member of QtWidgets in Qt5, but moved to QtOpenGLWidgets in Qt6.
+    QtPy makes QOpenGLWidget available in QtWidgets to maintain compatibility.
+    """
+    assert QtWidgets.QOpenGLWidget is not None

qtpy/utils.py

@@ -0,0 +1,32 @@
+# -----------------------------------------------------------------------------
+# Copyright © 2023- The Spyder Development Team
+#
+# Released under the terms of the MIT License
+# (see LICENSE.txt for details)
+# -----------------------------------------------------------------------------
+
+"""Provides utility functions for use by QtPy itself."""
+
+import qtpy
+
+
+def _wrap_missing_optional_dep_error(
+        attr_error,
+        *,
+        import_error,
+        wrapper=qtpy.QtModuleNotInstalledError,
+        **wrapper_kwargs,
+    ):
+    """Create a __cause__-chained wrapper error for a missing optional dep."""
+    qtpy_error = wrapper(**wrapper_kwargs)
+    import_error.__cause__ = attr_error
+    qtpy_error.__cause__ = import_error
+    return qtpy_error
+
+
+def getattr_missing_optional_dep(name, module_name, optional_names):
+    """Wrap AttributeError in a special error if it matches."""
+    attr_error = AttributeError(f'module {module_name!r} has no attribute {name!r}')
+    if name in optional_names:
+        return _wrap_missing_optional_dep_error(attr_error, **optional_names[name])
+    return attr_error