Prelude

Invoca Python Style Guide

The contents of this styleguide are to be enforced by flake8 and black through the use of the flake8 plugin flake8-black.

Any adjustments to this styleguide should be captured in the tox.ini config.

Table of Contents

Prelude
Table of Contents
PEP-8: Style Guide for Python Code
PEP-20: The Zen of Python
Layout
Syntax
Naming
Comments
Classes
Type Annotations
Recommendations

PEP-8: Style Guide for Python Code

PEP-8 defines the official style guide for python. While it is not entirely comprehensive, it provides a sufficient foundation for more detailed style guides such as this. This style guide makes frequent reference to PEP-8. In general code should adhere to that. Any extensions to or deviations from PEP-8 will be documented here.

PEP-20: The Zen of Python

PEP-20 defines the so-called Zen of Python which is a set of principles for writing clean, idiomatic python code. Where PEP-8 is prescriptive, this is much more abstract and interpretive. While this shouldn't be taken as scripture, it may be useful to apply these abstract principles when faced with ambiguity.

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Layout

PEP-8 standards:

Syntax

PEP-8 standards:

Naming

Names that are visible to the user as public parts of the API should
follow conventions that reflect usage rather than implementation.

PEP-8 standards:

Comments

PEP-8 standards:

Classes

PEP-8 standards:

Type Annotations

PEP-8 standards:

Recommendations

PEP-8 standards:

programming recommedations