[SIP-46] Proposal for strict Pylint enforcement

[SIP] Proposal for strict pylint enforcement

Motivation

Over the past number of years there have been a number of initiatives to improve the quality of the Python code via a number of linters (flake8; deprecated), formatters (black, isort), and type checkers (mypy). The one elephant in the room is pylint, a powerful yet sometimes perceived unusable quality checker.

Though pylint is enabled as part of CI and tox many of the checks are ignored either globally or at the file level via:

# pylint: disable=C,R,W

From previous experiences the value of many of these linters/checkers only materializes when strict enforcement exists for the entire repo (somewhat akin to heard immunity). Hence rather than merely trying to ensure that new code meets a higher bar, we (as a community) need to roll up our sleeves and take the somewhat painstaking approach of systematically re-enabling checks, removing blanket disablement, etc. somewhat akin to how we were able to strictly enforce flake8 (PRs) and mypy (PRs). Once the entire code base adheres to the strictly enforced rules it is then relatively simple (in terms of effort) to ensure a PR adheres to the necessary checks.

Proposed Change

I propose that by strictly enforcing pylint we will drastically improve the quality, readability, and maintainability of the Python code. I have worked on a number of repos which strictly enforce pylint (with very few checks disabled) and unequivocally can say that having pylint enabled helped to improve the code quality (preventing a number of bugs), consistency, readability, etc. Additionally I have not found pylint to be unusable as others have stated and do not find it cumbersome to use (once the necessary ground work has been laid).

Note the scale and effort involved is greater than any of the previous checkers and thus will require a systematic approach (hopefully undertaken by a number of individuals in the community). This initiative may take a number of months to complete, i.e., for context having the Python code fully adhere to having all function definitions be typed took around three months with limited involvement.

The three steps which need to be undertaken (in order) are:

1. Bumping the version of pylint to the latest stable version (2.5.2 at time of writing). Currently we are using pylint 1.9.2 which was released on June 6, 2018.
2. Systematically† remove the globally disabled checkers‡.
3. Systematically† reenable checking for all files, i.e., removing the # pylint: disable=C,R,W comments.

† Note systematically implies via a slew of PRs which re-enables a check (or small subset of checks) and/or file(s) at a time.

‡ Note based on other repos which use pylint the only the following checks should be disabled:

• bad-continuation which is incompatible with black. This was removed in Pylint 2.6 as it was deemed black or other formatters are better equipped to handle this.
• missing-module-docstring since Python modules are typically not documented at the module/file level. This isn’t necessary given all files contain a copyright header.

Additionally the following checks should be enabled:

• useless-suppression ensures there are no unnecessary # pylint: disable suppressions.

New or Changed Public Interfaces

N/A

New dependencies

N/A

Migration Plan and Compatibility

N/A

Rejected Alternatives

A list of Python static analysis tools are described here. Note that we previously used flake8 (in conjunction with pylint) but later deprecated it as felt that black, isort, and pylint represented a superset in terms of functionality.

[rusackas]

I don’t believe this has gone up for a DISCUSS thread on the dev@ list, has it @john-bodley ? Shall we push this through?

[john-bodley]

The vote has officially passed.