Typographical Conventions

Introduction

This chapter describes typographical conventions used in the Pyramid documentation.

Glossary

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

request

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

Topic

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.

Code

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

Syntax highlighting

XML:

<somesnippet>Some XML</somesnippet>

Unix shell commands (See venv for the meaning of $VENV.):

$VENV/bin/pip install -e .

Windows commands (See venv for the meaning of %VENV%.):

%VENV%\Scripts\pserve development.ini

cfg:

[some-part]
# A random part in the buildout
recipe = collective.recipe.foo
option = value

ini:

[nosetests]
match=^test
where=pyramid
nocapture=1

Interactive Python:

>>> class Foo:
...     bar = 100
...
>>> f = Foo()
>>> f.bar
100
>>> 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/pytest 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
    pass

A code block with line numbers.

1if "foo" == "bar":
2    # This is Python code
3    pass

Some code blocks may be given a caption.

sample.py
if "foo" == "bar":
    # This is Python code
    pass

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.

Deprecated

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

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

Warning

This is a warning.

Notes

Notes represent additional information related to a topic or concept.

Note

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.

See also

See Quick Tutorial section on Requirements.

Cross-references

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.

pyramid.config

Python class names display as follows.

pyramid.config.Configurator

Python method names display as follows.

pyramid.config.Configurator.add_view()

Python function names display as follows.

pyramid.renderers.render_to_response()

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

render_to_response()

The application "Pyramid" itself displays as follows.

Pyramid