Style Conventions

As we have seen, the syntax and semantics of Python leave open many semantically equivalent choices to be made for a given program. For instance, a list can be defined with

l = [
    "foo", 
    "bar", 
    "baz"
]

or with

l = ["foo", "bar", "baz"]

Semantically, these are equivalent. Which is better? This is the question of style: what is a good way to make these decisions?

A style guide is a collection of rules to be applied consistently to a program, a software suite, or even all programs in a given language. Consistency is crucial; without it, a program will be harder to read, maintain, and improve. The Python standard library style guide by pep8 (often called simply “PEP 8”) has become the de facto official Python style guide. Most professionally written programs will follow this guide with more or less variation (e.g., there might be a “house” style for certain cases). However, as Emerson tells us and PEP 8 reminds us,

A foolish consistency is the hobgoblin of little minds

A common paraphrase of this leaves off the qualifier “foolish,” suggesting that any consistency should be dispatched, which would be … inconsistent … with so much wisdom that embraces the value of consistency. However, a foolish consistency is, indeed, a hobgoblin; a style guide is most effective when its wielder knows when and how to break from it.

Rather than presenting the PEP 8 style guide in detail, we will learn it through experience. Most of the code in this book uses the PEP 8 style, with some variation for succinct presentation. Furthermore, the reader should turn on autoformatting in their VS Code editor to follow the PEP 8 style guide and the Black code formatter with the following steps:

Install the Ruff extension: https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff.
Follow the instructions at the link above to configure the extension to autoformat your Python code each time you save a file.

Now, whenever you save a file, it will be autoformatted in conformance with the PEP 8 style guide.

The Black code formatter (Langa and contributors to Black 2024) necessarily goes beyond the PEP 8 guide, which still has some flexibility, to enforce a strict style. It is used extensively in the software development community, so beginning with this as a baseline should help you develop well in your own style.

There are some important aspects of style that are not enforced by PEP 8 or Black, including some aspects of docstrings and type hints. For these, we will follow another popular style guide from google2024, as described in the following sections.

Docstrings

A docstring is a string literal that is the first statement of a function definition, class definition, or module (i.e., a .py file). By convention, it is surrounded with three double-quotation marks, like

"""Here is a docstring."""

For simple functions, classes, and modules, this can be a single line of 88 characters or less. For instance,

def foo(x):
    """Return a fun string that ends with x."""
    return f"This string is fun {x}"

For complex functions, a multiline docstring is necessary and should be formatted as follows:

"""A succinct description or imperative.

A longer description or imperative.

Args:
    arg1: A description of the first argument.
    arg2: A description of the second argument. This one is going to be
        longer to show the hanging indent.

Returns:
    A description of the return value(s).
    
Raises:
    IOError: An error occurred doing X.
    ValueError: An error occurred doing Y.
"""

For complex classes, a multiline docstring should be formatted as follows:

"""A succinct description or imperative.

A longer description or imperative.

Attributes:
    attr1: A description of the first attribute.
    attr2: A description of the second attribute.
"""

For complex modules, a multiline docstring should be formatted as follows:

"""A succinct description or imperative.

A longer description or imperative.

Typical usage example:
    
    x = FooClass()
    y = x.BarFunction()
"""

The “typical usage example” idiom can also be added to function and class docstrings.

Type hints

Unlike programming languages like C, Python is dynamically typed, meaning we can replace an object a given name refers to with an object of another type. For instance, the following is fine (but inadvisable):

x = 4  # An int type
x = "foo"  # A str type

In a statically typed language like C, a name’s type is explicitly declared with a statement like int x. This makes it clear to the compiler, interpreter, or (human) programmer the type of objects to which it can refer.

In Python, type declarations are not required; however, type hints have been introduced to the language to serve a similar purpose. A type hint is an annotation of a name (variable or return value of a function) that indicates the type (i.e., class) of objects that should be stored in it. For instance, we can indicate that variable x should be of type int with the statement

x: int  # A type hint for variable x, stating x should be an int
x = 3  # Actually assign x

Similarly, a type hint can be included in an assignment statement, as in

x: int = 3 # An assignment of variable x with a type hint

The Python interpreter does not check these hints. However, a separate typechecker like mypy or pytype can be applied.¹ We will not use a type checker, but we will still find value in type hints as hints to programmers, ourselves most of all. Before the introduction of these hints to Python, it was common to annotate types via comments. Now we can reserve comments for more semantic descriptions.

For function definitions, it is very useful to use type checking, as follows:

def foo(x: int, y: complex, z: str) -> str:
    """An operation that returns the score."""
    return str(x + y) + z

As we can see, each argument can be annotated, as can the return value via the syntax ->. Note that for numbers, a type annotation of complex indicates that the value can have type complex, float, or int (Rossum, Lehtosalo, and Langa [2014] 2024). Similarly, a type annotation of float indicates that the value can have type float or int. This is an interpretation of Python’s “numeric tower” (Yasskin [2007] 2024).

pep8, pep484, pep526, google2024

Langa, Łukasz, and contributors to Black. 2024. “Black: The Uncompromising Python Code Formatter.” https://github.com/psf/black.

Rossum, Guido van, Jukka Lehtosalo, and Łukasz Langa. (2014) 2024. “PEP 484 – Type Hints.” https://peps.python.org/pep-0484/.

Yasskin, Jeffrey. (2007) 2024. “PEP 3141 – a Type Hierarchy for Numbers.” https://peps.python.org/pep-3141/.

At this point, unlike some other IDEs, Spyder doesn’t have type-checking integration.↩︎

Online Resources for Section 2.6

No online resources.