From 1bd60385ebd3cbd410fad465ec325b386233211d Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Mon, 12 Jun 2023 21:30:15 +0200 Subject: qt: Add module docstrings and update lint ignores --- .flake8 | 1 + qutebrowser/qt/core.py | 15 ++++++++++++--- qutebrowser/qt/dbus.py | 15 ++++++++++++--- qutebrowser/qt/gui.py | 15 ++++++++++++--- qutebrowser/qt/machinery.py | 15 ++++++++++----- qutebrowser/qt/network.py | 15 ++++++++++++--- qutebrowser/qt/opengl.py | 15 ++++++++++++--- qutebrowser/qt/printsupport.py | 15 ++++++++++++--- qutebrowser/qt/qml.py | 15 ++++++++++++--- qutebrowser/qt/sip.py | 22 ++++++++++++++++------ qutebrowser/qt/sql.py | 15 ++++++++++++--- qutebrowser/qt/test.py | 15 ++++++++++++--- qutebrowser/qt/webenginecore.py | 15 ++++++++++++--- qutebrowser/qt/webenginewidgets.py | 15 ++++++++++++--- qutebrowser/qt/webkit.py | 18 ++++++++++++++---- qutebrowser/qt/webkitwidgets.py | 16 +++++++++++++--- qutebrowser/qt/widgets.py | 15 ++++++++++++--- 17 files changed, 198 insertions(+), 54 deletions(-) diff --git a/.flake8 b/.flake8 index 8838a6990..8460fa68d 100644 --- a/.flake8 +++ b/.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 diff --git a/qutebrowser/qt/core.py b/qutebrowser/qt/core.py index a80792ace..5cc437552 100644 --- a/qutebrowser/qt/core.py +++ b/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 diff --git a/qutebrowser/qt/dbus.py b/qutebrowser/qt/dbus.py index 5f0cc6475..e9ee15ff8 100644 --- a/qutebrowser/qt/dbus.py +++ b/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 diff --git a/qutebrowser/qt/gui.py b/qutebrowser/qt/gui.py index cec936687..edc3adaea 100644 --- a/qutebrowser/qt/gui.py +++ b/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 diff --git a/qutebrowser/qt/machinery.py b/qutebrowser/qt/machinery.py index 6699d5e73..1eef24f0b 100644 --- a/qutebrowser/qt/machinery.py +++ b/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: diff --git a/qutebrowser/qt/network.py b/qutebrowser/qt/network.py index e24a75bfa..2a665a3a9 100644 --- a/qutebrowser/qt/network.py +++ b/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 diff --git a/qutebrowser/qt/opengl.py b/qutebrowser/qt/opengl.py index 0fa09e5ac..5c3af3a5a 100644 --- a/qutebrowser/qt/opengl.py +++ b/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 diff --git a/qutebrowser/qt/printsupport.py b/qutebrowser/qt/printsupport.py index cdd1b4b22..e733bf828 100644 --- a/qutebrowser/qt/printsupport.py +++ b/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 diff --git a/qutebrowser/qt/qml.py b/qutebrowser/qt/qml.py index c97a44d0a..efb6901f2 100644 --- a/qutebrowser/qt/qml.py +++ b/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 diff --git a/qutebrowser/qt/sip.py b/qutebrowser/qt/sip.py index 12d346516..7be3b061c 100644 --- a/qutebrowser/qt/sip.py +++ b/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] diff --git a/qutebrowser/qt/sql.py b/qutebrowser/qt/sql.py index 187573bc1..825d0acc8 100644 --- a/qutebrowser/qt/sql.py +++ b/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 diff --git a/qutebrowser/qt/test.py b/qutebrowser/qt/test.py index c2ae4f192..11753a622 100644 --- a/qutebrowser/qt/test.py +++ b/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 diff --git a/qutebrowser/qt/webenginecore.py b/qutebrowser/qt/webenginecore.py index 8154d8c9f..fcffef9b9 100644 --- a/qutebrowser/qt/webenginecore.py +++ b/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 diff --git a/qutebrowser/qt/webenginewidgets.py b/qutebrowser/qt/webenginewidgets.py index fd2d281c8..9bb62db1f 100644 --- a/qutebrowser/qt/webenginewidgets.py +++ b/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 diff --git a/qutebrowser/qt/webkit.py b/qutebrowser/qt/webkit.py index b4b983037..c8b5c0b39 100644 --- a/qutebrowser/qt/webkit.py +++ b/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 * diff --git a/qutebrowser/qt/webkitwidgets.py b/qutebrowser/qt/webkitwidgets.py index edf6354fb..2c60909cc 100644 --- a/qutebrowser/qt/webkitwidgets.py +++ b/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 diff --git a/qutebrowser/qt/widgets.py b/qutebrowser/qt/widgets.py index 405483716..44b677f09 100644 --- a/qutebrowser/qt/widgets.py +++ b/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 -- cgit v1.2.3-54-g00ecf