Python Code Style

We make use of PEP-8 for our basic code style but there are some issues on which it is silent. There are other matters which are not style in the strictest sense but are requirements we have of our code.

You Touch It, You Fix It

The current state of the code is not as good as we would like. We would like to avoid sweeping re-styling changes so we operate a "you touch it, you fix it" policy.

This means that if you modify any part of a file you are expected restyle the whole file in line with PEP-8 and these additional requirements.

More generally, do not feel afraid of improving the documentation if you see an opportunity. Code style is more down to personal taste so only change it if it fails validation or these directives.

Type Hinting

Static type checking (we use mypy) is a valuable tool for avoiding errors.

In order to gain this advantage we need type hints to be provided on all function arguments.

API Documentation

We make use of the Sphinx tool's ability to automatically generate API documentation from doc-strings. This uses certain reStructured text notation to add structured information.

Quote Types

Python does not consider double (") and single (') quotes semantically different. Which to use is down to local choice.

The rule of thumb is that natural language (such as doc-strings, prompts and log messages) should use double-quotes. Meanwhile programatic strings such as those specified in APIs (e.g. str(..., encoding='utf8')) should use single quotes.