Typographical Conventions


This chapter describes typographical conventions used in the Pyramid documentation.


A glossary defines terms used throughout the documentation. References to glossary terms appear as follows.


Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term.


A topic is similar to a block quote with a title, or a self-contained section with no subsections. A topic indicates a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur.

Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.


Code may be displayed in blocks or inline. Blocks of code may use syntax highlighting, line numbering, and emphasis.

Syntax highlighting


<somesnippet>Some XML</somesnippet>

Unix shell commands are prefixed with a $ character. (See venv for the meaning of $VENV.)

$ $VENV/bin/pip install -e .

Windows commands are prefixed with a drive letter with an optional directory name. (See venv for the meaning of %VENV%.)

c:\> %VENV%\Scripts\pserve development.ini


# A random part in the buildout
recipe = collective.recipe.foo
option = value



Interactive Python:

>>> class Foo:
...     bar = 100
>>> f = Foo()
>>> f.bar
>>> f.bar / 0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: integer division or modulo by zero

Displaying long commands

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

$ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \
    --cov=tutorial -q

Code block options

To emphasize lines, we give the appearance that a highlighting pen has been used on the code.

if "foo" == "bar":
    # This is Python code

A code block with line numbers.

if "foo" == "bar":
    # This is Python code

Some code blocks may be given a caption.

if "foo" == "bar":
    # This is Python code

Inline code

Inline code is displayed as follows, where the inline code is 'pip install -e ".[docs]"'.

Install requirements for building documentation: pip install -e ".[docs]"

Feature versioning

We designate the version in which something is added, changed, or deprecated in the project.

Version added

The version in which a feature is added to a project is displayed as follows.

New in version 1.1: pyramid.paster.bootstrap()

Version changed

The version in which a feature is changed in a project is displayed as follows.

Changed in version 1.8: Added the ability for bootstrap to cleanup automatically via the with statement.


The version in which a feature is deprecated in a project is displayed as follows.

Deprecated since version 1.7: Use the require_csrf option or read Checking CSRF Tokens Automatically instead to have pyramid.exceptions.BadCSRFToken exceptions raised.


Warnings represent limitations and advice related to a topic or concept.


This is a warning.


Notes represent additional information related to a topic or concept.


This is a note.

See also

"See also" messages refer to topics that are related to the current topic, but have a narrative tone to them instead of merely a link without explanation. "See also" is rendered in a block as well, so that it stands out for the reader's attention.


Cross-references are links that may be to a document, arbitrary location, object, or other items.

Cross-referencing documents

Links to pages within this documentation display as follows.

Quick Tour of Pyramid

Cross-referencing arbitrary locations

Links to sections, and tables and figures with captions, within this documentation display as follows.

Internationalization and Localization

Python modules, classes, methods, and functions

All of the following are clickable links to Python modules, classes, methods, and functions.

Python module names display as follows.


Python class names display as follows.


Python method names display as follows.


Python function names display as follows.


Sometimes we show only the last segment of a Python object's name, which displays as follows.


The application "Pyramid" itself displays as follows.