Python

Python allows for lots of variation on how to write code. That could be a disadvantage when working in a team. This guide to Python conventions should be followed as a way to work with Python within the company. All conventions mentioned have accumulated because of multiple teams choosing to stick with a convention, or because it’s simple the standard in the global Python community.

One last word of advice: while we stick with shared conventions to make working in a team easier, it doesn’t mean the conventions can’t change, get dropped or replaced by a better one.

Code style

All python code should comply with the PEP 8. You can validate your code using flake8 and several additional checkers: flake8-import-order, pep8-naming, flake8-blind-except, flake8-docstrings, flake8-isort.

Running black with flake8, you can easily auto-format code according to the spec. The style is enforced to reduce work, not add to it.

Also add isort in the mix to automatically sort your imports.

Docs

There are several standards in style when writing documentations. The two styles used by us are numpy and google. Per project, choose one, stick to it and of course, lint accordingly.

flake8-docstrings can be configured to lint either style.

We employ many non-native English speakers while all of our codebase is written in English. No surprise that we encourage the use of pyenchant the spell checker to be executed through pylint. A competing linter to flake8 which we don’t use except for running the spell check.

Only few projects go so far as to lint the validity of arguments within docstrings using darglint.

Quotes

Something that can’t be enforced by linters currently. Use double quotes for multiline strings and docstrings:

>>> def cheese_shop():
... """
... We are out of stock.
...
... """
... return 'empty basket'
...
>>>

Tests

The excellent pytest suggests a test location to keep tests alongside code.

Use pytest-cov to keep an eye on test coverage and visualize the output in CI.

When you use requests to perform API calls, consider using responses to capture and replay test data.

freezegun is useful for mocking date and time. smtpdfix for SMTP servers.

Tools

Several projects are using these tools with success.

• flask to build a webservice.
• sqlalchemy (flask-sqlalchemy, psycopg2-binary) as ORM to connect to a SQL database.
• marshmallow (flask-marshmallow, marshmallow-sqlalchemy) to validate incoming API request data against a data model.
• alembic (flask-migrate) to perform DB schema migrations.
• polars to work with big datasets and making better use of strict typing to save memory.

reStructuredText

reStructuredText is the markup syntax for use in Python docstrings and other documentation domains.

Indentation

Use an indentation of 4. The only exception are lists, in which the text must be aligned with the indentation of the first line.

Use appropriate syntax

Try to use the appropriate roles / directives / syntax. For example, use the code-block directive for code, but use doctext syntax for Python. Use the proper roles when referencing files, RFCs, PEPs, the Cheese Shop, etc. Use common sense to comply with this rule.

Headers

Use the right header level. Try to use as low level headers as possible unless this is explicitly unwanted behavior.

######################
Parts (Level 1 header)
######################

*************************
Chapters (Level 2 header)
*************************

Sections (Level 3 header)
=========================

Subsections (Level 4 header)
----------------------------

Subsubsections (Level 5 header)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Paragraphs (Level 6 header)
"""""""""""""""""""""""""""

Directives

The directive arguments should be one space after the directive definition. Each option should be on the next new line. Then there is a blank line followed by the directive content.

Examples:

.. toctree::
    :maxdepth: 2

    /styleguides/python
    /styleguides/restructuredtext

.. toctree:: /styleguides/*
    :maxdepth: 2
    :glob:

Line length

The maximum line length of paragraphs and other multiline content is 79 characters. The only exception are code blocks.