Coding Style (Python)

Coding Style (Python)

The Python code in this project follows the following standard.

Naming Conventions

• All variables (arguments), functions (methods) and files should be in snake_case. Classes should be in PascalCase.
• Names may contain ONE underscore (_) at the beginning or the end of the name, in order to differentiate from the keywords or other variables in the parent scope.
• Good:

class MyClass:
    my_variable = 0

    def my_function(
        my_argument_a,
        my_argument_b_,
        _my_argument_c
    ):
        pass

• Bad:

class myClass:  # Not PascalCase.
    myVariable = 0  # Not snake_case.

    def myFunction(
        myArgumentA,  # Not snake_case.
        myArgumentB,  # Not snake_case.
        __myArgumentC  # Not snake_case, and two underscores.
    ):
        pass

Indentation

• Use 4 spaces for indentation. Do NOT use tabs.
• Good:

def my_function():
    if True:
        # Do something.

• Bad:

def my_function():
    if True:
    # Do something.

Line Length

• The maximum line length should be 120 characters. You may need to break long lines into multiple lines.
• Good:

my_variable = (
    "This is a very very very very very very very very very very very very very very very very long string"
    "that needs to be broken into multiple lines."
)

• Bad:

my_variable = "This is a very very very very very very very very very very very very very very very very long string that needs to be broken into multiple lines."

Spaces

• Always put a space after a comma.

• Always put a space before and after an operator.

• Do NOT put a space after the opening and before the closing parentheses.

• Do NOT put a space after the opening and before the closing square brackets.

• Do NOT put a space after the opening and before the closing curly braces.

• Good:

my_variable = 0
b = 1 + (4 * 5)

• Bad:

my_variable=0
b = 1+( 4*5 )

Comments

• Use # for single-line comments. Use """ for docstrings.
• Put a space after the # character. If it is an inline comment, put two spaces before the # character.
• Good:

# This is a single-line comment.

def my_function():
    """
    This is a docstring.
    """
    do_something()  # This is an inline comment.

• Bad:

#This is a single-line comment.

def my_function():
    # This is not a docstring.
    do_something()# This is an inline comment.

Imports

• Import statements should be on separate lines, and should be in alphabetical order.

Tip

Use the isort package to sort the imports.

Caution

Do NOT use from module import *. This will seriously affect the readability of the code.

• Good:

import os
import sys

• Bad:

import os, sys

File Structure

• The file structure should be as follows:

# Header comments...

# Standard library imports
import os
import sys

# Third-party imports
import numpy as np

# Local application imports
from my_module import my_function

# Constants
MY_CONSTANT = 0

# Classes
class MyClass:
    pass

# Functions
def my_function():
    pass

# Main code (driver code) if necessary / for testing
if __name__ == "__main__":
    my_function()

Typing

• Use type hints wherever possible. This will help in understanding the code and also in debugging.
• Good:

def my_function(a: int, b: str) -> float:
    return float(a)

• Bad:

def my_function(a, b):  # No type hints.
    return float(a)

• Add type hints to function parameters and return types. If the function does not return anything, use None.
• Add a documentation string to the function, and add type hints to the parameters and return types.

def my_function(a: int, b: str) -> float:
    """
    This function takes two parameters, an integer and a string, and returns a float.
    :param a: An integer.
    :param b: A string.
    :return: A float.
    :raises ValueError: If a is zero.
    """
    if a == 0:
        raise ValueError("a cannot be zero.")
    return float(a)

Python Version

• The code should be compatible with the last 3 subversions of Python. The code should be tested with the latest version of Python.

Note

As of now, the latest version is Python 3.12. Therefore, the last 3 subversions are 3.10, 3.11, and 3.12.

• Be very careful with version-specific features. If you use a feature that is not available in the last 3 subversions, just do not use it.

---

Tip

Tools

The Python code in this project follows the Black code style. The code should be formatted using Black before pushing to the repository.

Formatting

The code should be formatted using Black. You can install Black using pip:

pip install black

OR install everything in the pyproject.toml file:

pip install .

To format the code, use the following command:

black .

and it will format the code according to the Black code style.

Sorting Imports

The imports should be sorted using isort. You can install isort using pip:

pip install isort

To sort the imports, use the following command:

isort .

and it will sort the imports according to alphabetical order.