Documentation in progress Edit me on GitHub

Typographical ConventionsΒΆ

Literals, filenames and function arguments are presented using the following style:

argument1

Warnings, which represent limitations and need-to-know information related to a topic or concept are presented in the following style:

Warning

This is a warning.

Notes, which represent additional information related to a topic or concept are presented in the following style:

Note

This is a note.

We present Python method names using the following style:

We present Python class names, module names, attributes and global variables using the following style:

References to glossary terms are presented using the following style:

URLs are presented using the following style:

References to sections and chapters are presented using the following style:

Code and configuration file blocks are presented in the following style:

1
2
def foo(abc):
    pass

Example blocks representing UNIX shell commands are prefixed with a $ character, e.g.:

$ $VENV/bin/nosetests

(See virtualenv for the meaning of $VENV)

Example blocks representing Windows cmd.exe commands are prefixed with a drive letter and/or a directory name, e.g.:

c:\examples> %VENV%\Scripts\nosetests

(See virtualenv for the meaning of %VENV%)

Sometimes, when it's unknown which directory is current, Windows cmd.exe example block commands are prefixed only with a > character, e.g.:

> %VENV%\Scripts\nosetests

When a command that should be typed on one line is too long to fit on a page, the backslash \ is used to indicate that the following printed line should actually be part of the command:

c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
      --cover-erase --with-coverage

A sidebar, which presents a concept tangentially related to content discussed on a page, is rendered like so:

When multiple objects are imported from the same package, the following convention is used:

from foo import (
    bar,
    baz,
    )

It may look unusual, but it has advantages:

  • It allows one to swap out the higher-level package foo for something else that provides the similar API. An example would be swapping out one Database for another (e.g. graduating from SQLite to PostgreSQL).
  • Looks more neat in cases where a large number of objects get imported from that package.
  • Adding/removing imported objects from the package is quicker and results in simpler diffs.

Previous topic

Copyright, Trademarks, and Attributions

Next topic

Quick Tour of Pyramid