Coding Style Guide

Python Code Style Guide

Introduction

This document serves as a quick reference for adhering to Python's coding conventions as outlined in PEP 8. Additionally, the tool ruff is recommended for automatic code formatting to ensure consistent style throughout the codebase.

Table of Contents

1. Indentation
2. Whitespace
3. Imports
4. Comments
5. Naming Conventions
6. Function and Method Arguments
7. Code Organization
8. Exceptions
9. Whitespace in Expressions and Statements
10. Automatic Code Formatting with ruff

PEP 8 Quick Reference

Indentation

• Use 4 spaces per indentation level.

Whitespace

• Avoid extraneous whitespace.
• Use blank lines to separate functions, classes, and blocks of code inside functions.

Imports

• Imports should usually be on separate lines.
• Group imports in the following order:
  1. Standard library imports.
  2. Related third-party imports.
  3. Local application/library specific imports.

Comments

• Write comments sparingly and use them to explain complex sections.
• Avoid redundant comments that only repeat the code.

Naming Conventions

• Follow PEP 8 naming conventions for variables, functions, and classes.

Function and Method Arguments

• Put a space after the comma in function and method arguments.

Code Organization

• Organize code logically, with related functions and classes grouped together.
• Use blank lines to separate logical sections within a function.

Exceptions

• Catch specific exceptions instead of using a generic except clause.
• Use try and except blocks only for code that may raise exceptions.

Whitespace in Expressions and Statements

• Avoid extraneous whitespace in expressions and statements.

Automatic Code Formatting with ruff

To ensure consistent code formatting, the tool ruff can be used. ruff is an opinionated code formatter that automatically formats Python code to comply with PEP 8. Follow the instructions below to use ruff:

1. Install ruff using pip:

poetry add ruff

2. To run Ruff as a linter, try any of the following:

ruff check .                        # Lint all files in the current directory (and any subdirectories).
ruff check path/to/code/            # Lint all files in `/path/to/code` (and any subdirectories).
ruff check path/to/code/*.py        # Lint all `.py` files in `/path/to/code`.
ruff check path/to/code/to/file.py  # Lint `file.py`.
ruff check @arguments.txt           # Lint using an input file, treating its contents as newline-delimited command-line arguments.

3. Or, to run Ruff as a formatted:

ruff format .                        # Format all files in the current directory (and any subdirectories).
ruff format path/to/code/            # Format all files in `/path/to/code` (and any subdirectories).
ruff format path/to/code/*.py        # Format all `.py` files in `/path/to/code`.
ruff format path/to/code/to/file.py  # Format `file.py`.
ruff format @arguments.txt           # Format using an input file, treating its contents as newline-delimited command-line arguments.

Reference

https://astral.sh/ruff

https://peps.python.org/pep-0008/