From 819d56043b8d3fda62c6c85b04504d96f38642e8 Mon Sep 17 00:00:00 2001 From: toofar Date: Thu, 22 Sep 2022 08:26:10 +1200 Subject: doc: add some contributor notes about mypy also update the default tox env list which I forgot to do when changing the mypy targets. --- doc/contributing.asciidoc | 38 ++++++++++++++++++++++++++++++++++++++ tox.ini | 2 +- 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/contributing.asciidoc b/doc/contributing.asciidoc index 35a72878e..e6bed08d2 100644 --- a/doc/contributing.asciidoc +++ b/doc/contributing.asciidoc @@ -128,6 +128,9 @@ Currently, the following tox environments are available: - untracked git files - VCS conflict markers - common spelling mistakes +* http://mypy-lang.org/[mypy] for static type checking: + - `mypy-pyqt5` run mypy with PyQt5 installed + - `mypy-pyqt6` run mypy with PyQt6 installed The default test suite is run with `tox`; the list of default environments is obtained with `tox -l`. @@ -685,6 +688,41 @@ Return: - `__magic__` methods - other methods - overrides of Qt methods +* Type hinting: the qutebrowser codebase uses type hints liberally to enable + static type checking and autocompletion in editors. + - We use http://mypy-lang.org/[mypy] in CI jobs to perform static type + checking. + - Not all of the codebase is covered by type hints currently. We encourage + including type hints on all new code and even adding type hints to + existing code if you find yourself working on some that isn't already + covered. There are some module specific rules in the mypy config file, + `.mypy.ini`, to make type hints strictly required in some areas. + - More often than not mypy is correct when it raises issues. But don't be + afraid to add `# type: ignore[...]` statements or casts if you need to. + As an optional part of the language not all type information from third + parties is always correct. Mypy will raise a new issue if it spots an + "ignore" statement which is no longer needed because the underlying + issue has been resolved. + - One area where we have to take particular care is in code that deals + with differences between PyQt5 and PyQt6. We try to write most code in a + way that will work with either backend but when you need to deal with + differences you should use a pattern like: ++ +[source,python] +---- +if machinery.IS_QT5: + ... # do PyQt5 specific implementation +else: + # PyQt6 + ... # do PyQt6 specific implementation +---- ++ +then you have to https://mypy.readthedocs.io/en/latest/command_line.html#cmdoption-mypy-always-true[tell] + mypy to treat `machinery.IS_QT5` as a constant value then run mypy twice to + cover both branches. There are a handful of variables in + `qutebrowser/qt/machinery.py` that mypy needs to know about. There are tox + jobs (`mypy-pyqt5` and `mypy-pyqt6`) that take care of telling mypy to use + them as constants. Checklists ---------- diff --git a/tox.ini b/tox.ini index 4e7311f45..7aa3d0821 100644 --- a/tox.ini +++ b/tox.ini @@ -4,7 +4,7 @@ # and then run "tox" from this directory. [tox] -envlist = py38-pyqt515-cov,mypy,misc,vulture,flake8,pylint,pyroma,check-manifest,eslint,yamllint,actionlint +envlist = py38-pyqt515-cov,mypy-pyqt5,misc,vulture,flake8,pylint,pyroma,check-manifest,eslint,yamllint,actionlint distshare = {toxworkdir} skipsdist = true minversion = 3.20 -- cgit v1.2.3-54-g00ecf