Wikimedia Cloud Services team/Python coding
This page is currently a draft.
More information and discussion about changes to this draft on the talk page.
This is a proposal to start the conversation for now.
In the interest of clean, readable code across the team, it is common practice by development groups to share formatting and other development practices in order to facilitate collaboration. A common example is shared linter settings, like what is used in operations/puppet for puppet-lint.
This is also intended as Team Practices, not an overall standard. The Foundation has several materials on that in a more general sense already, such as https://www.mediawiki.org/wiki/Manual:Coding_conventions/Python or https://wikitech.wikimedia.org/wiki/PythonStyleGuide (merged into the former to prevent duplication/forking).
We write a lot of python, so it seems like that would be the place to introduce some common practices for the WMCS team.
While PEP8 provides most of this, and the flake8 linter enforces it on CI, flake8 is pretty liberal, and formatting is hardly consistent. Using the auto-formatter black provides a more narrow interpretation of PEP8, can be integrated into all of our text editors, and makes the reasoning of the code stand out over the format. Black is configurable if we have disagreements with its defaults.
We have, as a rule, set black to a line length of 80 to comply with PEP8 and make things easier in gerrit reviews. Otherwise, we prefer black's conventions to flake8s when there is a conflict.
In a repository where a pyproject.toml is appropriate or doesn't clash with other settings, we can use the settings:
[tool.black] line-length = 80
If that repository is set to check for 79 char lines because of some old flake8 setting, like in tools-webservice, we use that for now.