Skip to content

Coding Standards#

PEP 8#

This project follows a superset of the PEP 8 – Style Guide for Python Code (PEP 8).

Strong Typing#

Strong typing is prefered wherever possible. Prefer using Duration instead of int, etc.

Explicit Types#

All functions must be fully annotated with Type Hints.

All classes must be fully annotated with Variable Annotations.

May be used wherever typing.cast types are ambiguious.

Explicity and namespace imports#

Never use wildcard imports. Either import the module or the items you require from the module.

Compatibility#

All code must be compatible with Python 3.8.

Defered/Postponed Evaluation of Annotations#

In the case that defered/postponed evaluation of annotations is required (e.g. when using type annotations that reference type defined later in the file), then use the annotations future statement

from __future__ from annotations

Note

This should be the only statement you may need to use.

Union Types#

Unions should be written using the syntax defined in PEP 604 – Allow writing union types as X | Y.

In the case the unions types are required, use the annotations future statement

from __future__ from annotations

Logging#

For logging the following rules apply:

  1. Use logging module for logging.
  2. Loggers must be declared at the top of the file after imports and global constants.
  3. The name of each logger must be __name__.
  4. Do not set log level of named loggers.
  5. Never log using the root logger.
  6. Do not share loggers between modules.
  7. Loggers stream must be set to stdout; they must only stream to the stderr (default) stream.

Here is an example of a logger in a module file.

# Correct
import logging

logger = logging.getLogger(__name__)
logger.debug(f"Created logger for {__name__}")

Documentation#

Python Docstrings#

All functions, classes and constants (class and global) must be documented using docstrings as standardized in PEP 287.

Docstring must follow the numpydoc standards which uses re-structured text (reST) syntax.

Class Variables#

In the Style guide for numpydoc there is an ambiguity in how static/class variables are to be documented.

For class variables, use the convention for Documenting constants

File Documentation#

Documentation files must be written in the /docs/ folder.

In Python the recommended file format for documentation is reST. However, due to the ubiquity of the Markdown format, it makes more logical sense to Markdown instead. Thus, all file documentation will be written in Markdown.

MkDocs using the Material for MkDocs theme, and the mkdocstrings extension.

Note

I initially considered using between Sphinx with the MyST Parser extension, and the Furo theme; however I decided to go with MkDoc due to how popular and recogizable it has become.

Static Analysis#

mypy will be used to perform static analysis.

Tip

If you wish, static analysis maybe performed using ty or pyrefly. Both these tools also have come with a language server, making them convient to use in an editor/IDE. However, it is worth noting that these tools is still in Alpha and may have some bugs so rely primarily on mypy.

Formatting#

Use ruff for formatting.