qt: Add module docstrings and update lint ignores

.flake8

@@ -62,6 +62,7 @@ min-version = 3.7.0
 max-complexity = 12
 per-file-ignores =
     qutebrowser/api/hook.py : N801
+    qutebrowser/qt/*.py : F403
     tests/* : B011,B028,D100,D101
     tests/unit/browser/test_history.py : D100,D101,N806
     tests/helpers/fixtures.py : D100,D101,N806

qutebrowser/qt/core.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Core.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtcore-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/dbus.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt DBus.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtdbus-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/gui.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt Gui.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtgui-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/machinery.py

@@ -1,9 +1,11 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring
-# flake8: noqa
 # pyright: reportConstantRedefinition=false
 
+"""Qt wrapper selection.
+
+Contains selection logic and globals for Qt wrapper selection.
+"""
+
 import os
 import sys
 import argparse
@@ -25,7 +27,7 @@ WRAPPERS = [
 
 
 class Error(Exception):
-    pass
+    """Base class for all exceptions in this module."""
 
 
 class Unavailable(Error, ImportError):
@@ -37,7 +39,10 @@ class Unavailable(Error, ImportError):
 
 
 class UnknownWrapper(Error):
-    pass
+    """Raised when an Qt module is imported but the wrapper values are unknown.
+
+    Should never happen (unless a new wrapper is added).
+    """
 
 
 def _autoselect_wrapper() -> str:

qutebrowser/qt/network.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Network.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtnetwork-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/opengl.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt OpenGL.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtopengl-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/printsupport.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Print Support.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtprintsupport-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/qml.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt QML.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtqml-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/sip.py

@@ -1,7 +1,18 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,unused-wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for PyQt5.sip/PyQt6.sip.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/sip directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the PyQt6.sip API:
+https://www.riverbankcomputing.com/static/Docs/PyQt6/api/sip/sip-module.html
+
+Note that we don't yet abstract between PySide/PyQt here.
+"""
 
 from qutebrowser.qt import machinery
 
@@ -11,7 +22,7 @@ machinery.init()
 # still package later versions of PyQt6 with a top-level "sip" rather than "PyQt6.sip".
 _VENDORED_SIP = False
 
-if machinery.USE_PYSIDE6:
+if machinery.USE_PYSIDE6:  # pylint: disable=no-else-raise
     raise machinery.Unavailable()
 elif machinery.USE_PYQT5:
     try:
@@ -25,9 +36,8 @@ elif machinery.USE_PYQT6:
         _VENDORED_SIP = True
     except ImportError:
         pass
-
 else:
     raise machinery.UnknownWrapper()
 
 if not _VENDORED_SIP:
-    from sip import *  # type: ignore[import]  # pylint: disable=import-error
+    from sip import *  # type: ignore[import]

qutebrowser/qt/sql.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt SQL.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtsql-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/test.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Test.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qttest-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/webenginecore.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt WebEngine Core.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwebenginecore-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/webenginewidgets.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt WebEngine Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwebenginewidgets-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/webkit.py

@@ -1,14 +1,24 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=wildcard-import
+
+"""Wrapped Qt imports for Qt WebKit.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6
+(though WebKit is only supported with Qt 5).
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the QtWebKit 5.212 API:
+https://qtwebkit.github.io/doc/qtwebkit/qtwebkit-index.html
+"""
 
 from qutebrowser.qt import machinery
 
 machinery.init()
 
 
-if machinery.USE_PYSIDE6:
+if machinery.USE_PYSIDE6:  # pylint: disable=no-else-raise
     raise machinery.Unavailable()
 elif machinery.USE_PYQT5:
     from PyQt5.QtWebKit import *

qutebrowser/qt/webkitwidgets.py

@@ -1,7 +1,17 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=wildcard-import,no-else-raise
+
+"""Wrapped Qt imports for Qt WebKit Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6
+(though WebKit is only supported with Qt 5).
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the QtWebKit 5.212 API:
+https://qtwebkit.github.io/doc/qtwebkit/qtwebkitwidgets-index.html
+"""
 
 from qutebrowser.qt import machinery
 

qutebrowser/qt/widgets.py

@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwidgets-index.html
+"""
 
 from qutebrowser.qt import machinery