Python guidelines

Hint

Most of the Python coding guidelines are automatically checked by the Python linters.

Python doc strings

Make extensive use of Python’s docstrings.

Since we generate documentation with Sphinx, also use the Sphinx info fields notation to document things like arguments or return values like this:

def spam(eggs):
    '''
    Add SPAM to ``eggs``.

    :param str eggs: The eggs

    :return: The eggs with SPAM
    :rtype: str
    '''
    return eggs ' with SPAM'

Cross-referencing should also be made with the Sphinx Python domain notation like so:

def spam():
    '''
    Provides SPAM.

    .. seealso::

        :py:meth:`spam.eggs.Egg.boil`
            The method used to boil eggs.
    '''