Coding Style

The Encoding¶

Since we only use UTF-8, the first line of the module will always be:

# -*- coding: UTF-8 -*-

The Copyright¶

After the encoding comes the copyright, which is made up of one or more lines with the following structure:

# Copyright (C) YEARS AUTHOR-NAME <AUTHOR-EMAIL>

The License¶

Right after the copyright statement comes a reference to the license. For itools it is the GPL version 3, or later.

The Documentation String¶

There must be a documentation string explaining what the module does. See section Documentation Strings for details on how to write the documentation strings.

The Imports¶

The import statements follow the module’s documentation string and close the heading. There may be import statements within the code too, but only in exceptional cases, for example to avoid circular references.

Imports must be classified: first those from the Standard Library, then those from itools, and finally those from other third-party packages. Within each group the order must be alphabetical.

The example that follows comes from the itools/xml/office.py file:

# Import from the Standard Library
from os.path import join as join_path
from subprocess import call
from tempfile import mkdtemp

# Import from itools
from itools import vfs
from itools.handlers import File, register_handler_class
from indexer import xml_to_text

Note that every section starts with the comment Import from .... Also, generally we import the functions, classes and constants we are going to use, and not the whole package:

Good	Bad
from tempfile import mkdtemp	import tempfile
mkdtemp(..)	tempfile.mkdtemp(..)

Note that the import vfs line above shows an exception to the rule. Another rule is not to import everything within a package:

Good	Bad
from tempfile import mkdtemp	from tempfile import *

Indentation, Spaces and Line Length¶

Here the general rules to format the code that must always be respected:

• There must be no tabs, nowhere, never.
• Each indentation level must have four (4) spaces.
• There must be no trailing spaces in a line.
• Lines should be 79 characters wide at most.

Line Wrap¶

The preferred way of wrapping long lines is by using Python’s implied line continuation inside parentheses, brackets and braces. If necessary, you can add an extra pair of parentheses around an expression, but sometimes using a backslash looks better. Make sure to indent the continued line appropriately.

One line, one statement¶

Don’t put more than one statement on the same line:

Bad

if x is True: do_something()

Good

if x is True:
    do_something()

Bad

do_one(); do_two()

Good

do_one()
do_two()

Bad

def f(x, y): return x * y`

Good

def f(x, y):
    return x * y

Blank lines¶

Separate classes with three blank lines. Separate methods and functions with two blank lines. There is also a blank line between the class definition and the first method definition.

Use blank lines in functions, sparingly, to indicate logical sections.

Whitespace in expressions and statements¶

Surround operators with one white space. There are a couple of exceptions to this rule: first, arithmetic operators in complex mathematical expressions may not be surrounded by a white space to make them more compact.

And the the sign = used in keyword arguments should not be surrounded by spaces, never:

Good	Bad
Document(title="hello")	Document(title = "hello")

Never add spaces neither before nor after parentheses, brackets or braces. The only exception is for list comprehensions, where it is allowed to add a space after the opening bracket, and another space before the closing bracket.

The comma and colon must be followed by a space (or a new line), but never put a space before. The only exception is for one element tuples, where the comma must be immediately followed by the closing parentheses. The semicolon should never be used.

Class names¶

Class names are written in capitalized words. Typically they are made of nouns and/or adjectives.

Functions and methods¶

Functions and methods are written in lowercase with underscores.

They must start by a verb, and they should be followed by a complement that clarifies what the function does. For example, it is better to spell set_object than just set.

Variables¶

Variables are written in lowercase with underscores. Most of the time they are nouns with or without adjectives.

One letter variables may be used in mathematical expressions, for sequence indexes, or in comprehensive lists:

public = [ x for x in handlers if x.state == 'public' ]

Constants¶

Constants are written in uppercase with underscores.