• next
• previous |
• ZTM »
• Documentation »
• Styleguides »

Python style guidelines for ZTM

A Foolish Consistency is the Hobgoblin of Little Minds, adored by little statesmen and philosophers and divines. With consistency a great soul has simply nothing to do.

– Ralph Waldo Emerson

Code is read and debugged more often than it is written. Therefore readability and comprehension is paramount and overrides any particular guideline in this document. As a contributor to ZTM you are hereby granted permission to think for yourself.

The guidelines should be followed in the following order:

0. Readability
1. Specifications in this document
2. Zope style guide
3. PEP 8.

Meaning that this document overrides the Zope style guide which overrides PEP 8.

Note

PEP 8 states it very well:

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.

But most importantly: know when to be inconsistent – sometimes the style guide just doesn’t apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

Indentation

Always use 4 spaces and no tabs. Code using tabs should be cleaned up as early as possible.

Docstrings

Read PEP 257 for conventions on writing good documentation strings.

You should also read PEP 287 on the reStructuredText Docstring Format.

Please take the time to become familiar with these and then read ZTM’s own documentation guidelines.

From PEP 257:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first line (see example below).

Maximum line length

PEP 008 requires all lines to be wrapped at 79.

In ZTM we just very strongly prefer to keep the length below 80, but allow lines up to 120 characters. Particularly lines in unit-tests tend to be long.

The main reason to prefer 80 characters is that it makes it simpler to have multiple files open horizontally.

Just configure your IDE (Integrated Development Environment)/text-editor to break lines at 80 characters. If it can’t do that consider learning a new one.

Whitespace

Trailing whitespace should be removed. The exception is blank lines that should try to follow the indentation level. The argument being that it is then easier to copy and paste to the interpreter, and it helps folding in some less forgiving text editors:

class TopicWrapper(object):
····"""One liner up to max 80th character describing class.
····
····Notice that we keep the indentation on the previous line.
...."""
····
····def __init__(self, topic):
········"""Function docstrings are formatted like class docstrings. Max 80."""
········self.topic = topic
····
····def setName(self, value):
········"""Sets the default name of the topic map in the unconstrained scope.
········
········:param: unicode string
········"""
········self.topic.setName(value, type=ztm.topicmaps.psis.model.topic_name)

No blank lines at the end of files.

Encodings

All files must be stored using UTF-8 but you are not allowed to use non-ASCII identifiers.

Make sure you always put the following preamble in every Python file:

# -*- coding: utf-8 -*-

This tells Python to interpret the source file as UTF-8. No need to add the byte-order mark.

Imports

Follow PEP 8 using this order:

1. standard library imports
2. related third party imports
3. related ztm-namespace imports
4. local application/library specific imports

Jim Fulton of Zope Corporation recommends just using sort order calling the PEP 8 way stupid. We tend to follow his advice, but haven’t read his argumentation yet so we’re following PEP 8 for now.

Naming conventions

Follow Zope’s naming conventions.