Python Guidelines

Data Structures

Think about the format of your data structures, especially for extendible ones. For example:

# This works.
spam = ['i', 'hate', 'spam']

# But this is much better.
eggs = [
    'i',
    'like',
    'eggs',
]

Hint

If you’re expanding both lists and you make a diff, you’ll notice that the changes of spam are much harder to tell than the changes of eggs. Therefor prefer the multi- over the single-line format. Also make sure you always add a trailing comma to the last element as well.

Documentation Strings

Make extensive use of Python’s docstrings. Also use the Sphinx info fields notation to document things like arguments or return values.

Here’s an example:

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, for example:

def spam():
    '''
    Provides SPAM.

    .. seealso::

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