Python coding guidelines

The following are some guidelines on how new Python code should be written. Of course, there will be occasional times where exceptions to these rules have to be made. However, following these rules when submitting new code makes the review easier so new code can be integrated in Jagged\Verge projects in less time.

Formatting

Uniformly formatted code makes it easier to share code ownership. The official Python guidelines detailed in PEP8 give a good starting point for how code should be formatted and indented. Please read it and follow it.

The only difference we have to PEP8 recommendations is the maximum line length. Keeping lines to a reasonable length decreases the cognitive loading on the reader, so shorter lines are better and any lines that require horizontal scrolling are unacceptable. While the 80 characters is good for printing we are of the belief that printing code onto paper is not a desirable task and considering the higher resolution of modern monitors it is better to up this maximum to 100 characters. We find that with a slightly higher maximum we have fewer instances where we would need to use backslash line continuations without giving up on being able to vertically split two windows of code side by side on our monitors. Overly long lines do hurt readability so please do make an effort to keep lines at a reasonable width.

In addition to PEP8 we have the following guidelines for formatting:

  • Avoid multiple statements on one line. Prefer a line return after a control flow statement (if/for).

Testing and code quality

The impact of quality in core Python libraries is very high. If you are submitting patches to any of our Python libraries we appreciate well tested code with high coverage. In general we use pytest along with Tox to test multiple environments.

Static analysis tools such as Pylint provide a good way to get quick feedback on code quality metrics. If Pylint reports an error it indicates something that will require fixing in order to be merged in upstream. Warnings should also be taken seriously as they often indicate issues or potential for future issues. We have a strict policy that if code contains PyLint errors we will not accept a pull request.

Package requirements

If the python code is to be installable via python setup.py install as a library all dependencies for the package must be specified in the setup.py file.

If the project is a standalone application then package requirements should be stored in a requirements.txt file. The command  pip freeze may be useful  in determining which packages are required.

For more information about packaging python code please read the python packaging guide.

Deprecation

If any publicly accessible method, function, attribute or parameter is renamed, we still support the old one for at least one release and issue a deprecation warning when it is called/passed/accessed. See the deprecations tutorial for how this is done.

Python 2-3 support

New projects and code should be written in Python3. If Python2 compatibility is also required you should follow the guidelines found at Python-future: http://python-future.org/compatible_idioms.html