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.

• 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 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 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!

PEP-8 standards:

• indentation
• tabs or spaces
• maximum line length
• line breaks after binary operators
• blank lines
• encoding
• imports

PEP-8 standards:

• string quotes
• whitespace in expressions and statements
• whitespace in general
• trailing commas

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:

• naming conventions
• module-level dunder names
• naming styles
• use of naming styles

PEP-8 standards:

• comments
• block comments
• inline comments
• documentation strings

PEP-8 standards:

• inheritance
• public interfaces

PEP-8 standards:

• function annotations
• variable annotations

PEP-8 standards:

• programming recommedations