Templates

Which one to pick for a new project is rarely a technical question. Jinja2 is the engine that most Python web developers already know, it is the default of the official cookiecutter (see Cookiecutter Projects & pserve), and its binding is the only one with recent releases. Chameleon is the natural choice for teams coming from Zope or Plone and for pages that must remain well-formed XML. Mako is a good fit for developers who want Python expressions in templates. This page spends most of its length on Jinja2 for that reason, and then shows what differs for the other two.

There are two ways to render a template in Pyramid. The recommended one is declarative: name the template as the renderer of the view configuration and return a plain dictionary. The other one calls the rendering API from inside the view and returns a Response.

The dictionary returned by a renderer-configured view becomes the set of top-level names of the template, and Pyramid adds a number of system values to it. The official Templates chapter lists them:

The first block prepares a small package named shelvesui in a temporary directory, with a layout template, a shelf template and a style sheet, so that the later examples are self-contained and can be run as they are. In a real project the same files live in the templates/ and static/ directories of your package (the cookiecutter generates this layout) and you simply create them in your editor.

Source: Templates

The listing prints the three files created below shelvesui/. The next block is the first complete application. It includes pyramid_jinja2, points the Jinja2 search path at the package, installs the two URL filters, registers a static view and a route, and uses the asset specification shelvesui:templates/shelf.jinja2 as the renderer.

The status is 200 OK and the title of the page is +Ada <Lovelace> & friends | +: the view’s text was escaped on output and parsed back by the HTML parser, and the template variable site_name that nobody provided rendered as an empty string, without any error. That silence is a pitfall explained in the settings section below, and the variable is provided properly with a renderer global in Renderer Globals with BeforeRender.

Source: Templates

To render a template from inside a view instead, use pyramid.renderers.render (returns a string) or pyramid.renderers.render_to_response (returns a Response). Always pass request as a keyword argument: without it, request and context are not available to the template and renderer globals are not applied, which is the most common cause of "my template works as a renderer but not through `render`".

The first response is 200 OK, text/plain, because a response was built by hand; the second is 201 Created with the default text/html, because render_to_response creates a response with the default content type of the renderer. To change status, headers or content type of a view that uses renderer=, set them on request.response before returning the dictionary; the request and response page of this section covers that object.

Source: Using Templates Directly

The reason to prefer the renderer configuration is testability: a view that returns a dictionary can be unit-tested by comparing dictionaries, without parsing HTML, while a view that returns a response needs its body to be inspected. The official documentation makes the same argument. Calling the engine’s own API from a view, as in the raw Mako example of the Templates chapter, is possible but loses three things: automatic reloading, asset overriding and the ability to use the template as a renderer.

Install the binding with pip install pyramid_jinja2 (Jinja2 comes with it) and activate it in one of two equivalent ways: call config.include("pyramid_jinja2"), or list pyramid_jinja2 in the pyramid.includes setting of the .ini file (see Settings, Environment & .ini Files). Activation does three things: it registers a renderer for the .jinja2 extension together with a jinja2.Environment, it adds the configurator directives add_jinja2_renderer, add_jinja2_search_path, add_jinja2_extension and get_jinja2_environment, and it adds the package that called include to the template search path.

The binding does not register the URL filters automatically. Installing route_url, static_url and the others is a setting, as in the previous example. Everything else in the Jinja2 language, such as inheritance, macros, filters, tests and expressions, is documented by Jinja2 itself and is not repeated here.

Install pip install pyramid_chameleon and activate it with config.include("pyramid_chameleon") or pyramid.includes = pyramid_chameleon. The extensions .pt and .txt become renderers: .pt is an XML-based Zope Page Template (ZPT), .txt a text template. Both understand ${expression} substitutions, and ZPT also the tal: and metal: attributes (tal:repeat, tal:content, metal:define-macro and others; the language is documented by Chameleon).

The ZPT page escapes ${title} to Ada & co and each book (<i>x</i> for the markup one), while the structure: prefix inserts trusted as raw markup, the Chameleon equivalent of Jinja2’s safe. The text template renders Hello, <world>! without escaping, as a response whose content type is still text/html, which is the default of every renderer that does not choose its own; use .txt templates only for trusted content or set request.response.content_type yourself. The last request shows a Pyramid feature specific to the Chameleon and Mako bindings: the renderer name shelf#card.pt renders only the macro named card of shelf.pt.

Macros need one more step than in Jinja2. To use a macro defined in another template, the view obtains the template object with pyramid.renderers.get_renderer("templates/master.pt").implementation() and passes it to the template, or, for a master page used by every template, adds it to the renderer globals in a BeforeRender subscriber (next section). The pyramid_chameleon documentation shows both.

Two settings matter: pyramid.reload_templates (see Reloading Templates) and pyramid.debug_templates (environment variable PYRAMID_DEBUG_TEMPLATES), which adds the template file name and arguments to the traceback of a failing template; it slows rendering and is for development only.

Source: pyramid_chameleon

Install pip install pyramid_mako and activate it with config.include("pyramid_mako") or pyramid.includes = pyramid_mako. It registers the renderers for .mako and .mak. As in Chameleon, ${name} substitutes a value, and the view must return a dictionary or a Response.

The values are escaped by default (<b>bold</b>), and the n filter written after a pipe turns the default escaping off for one expression. The system value context is renamed _context in Mako templates because context is an internal Mako name. shelf#card.mako renders only the def named card.

The settings of pyramid_mako are prefixed with mako.: mako.directories (the search path), mako.module_directory (where compiled modules are cached), mako.input_encoding, mako.error_handler, mako.default_filters (default ['h']; setting it to None disables escaping everywhere, which is almost never what you want), mako.imports, mako.future_imports, mako.strict_undefined, mako.preprocessor, mako.preprocessor_wants_settings and the mako.cache.* and mako.cache_impl family. mako.strict_undefined = true is the Mako counterpart of jinja2.undefined = strict and is recommended for the same reason. Mako’s own filesystem_checks option is driven by pyramid.reload_templates; unlike plain Mako, reloading is off unless that setting is true. config.add_mako_renderer(".html", settings_prefix="mymako.") adds another extension with another group of settings.

Source: pyramid_mako

A template named by an asset specification is an asset, and every asset can be overridden without editing the package that ships it. This is what makes a reusable add-on’s templates customisable: the add-on renders addon:templates/shelf.jinja2, and your application substitutes its own file.

The first application renders <h1>Default: Ada</h1> and the second <h1>Custom theme: Ada</h1>. Overriding works for templates named by an asset specification and for caller-relative names, which are converted into specifications, and not for templates rendered through the engine’s own API. override_asset can also override a whole directory, as in to_override="addonui:templates/". The Extending an Existing Application chapter of the narrative documentation describes the rules, and the extending page of this section covers them as a topic of their own.

Source: Overriding Assets

Values that every page needs (the site name, the current user, a navigation menu) should not be copied into every view’s dictionary. Pyramid sends a pyramid.events.BeforeRender event just before a renderer is invoked, and a subscriber can add keys to it. The event behaves like a dictionary holding the renderer globals, which include the system values, and its rendering_val attribute exposes the dictionary the view returned. This fixes the missing site_name of the first example.

The page is rendered now: the title is Ada <Lovelace> & friends | Bookshelf Shelves, the link to the style sheet is an absolute URL built by static_url, and every <, > and & coming from the view’s data is escaped. A subscriber must not reuse a key that exists already, because subscribers have no defined order and so nothing decides which value wins. The narrative documentation says that Pyramid raises a KeyError for such a duplicate; do not rely on that, because a subscriber that assigned the system name request was accepted without error on 2.1. Give every global a name that no view and no other subscriber uses. The event is the right place for read-only helpers and constants; do not put request-specific database queries in it, because it runs for every rendered template including error pages.

The subscriber may also be declared with @subscriber(BeforeRender) and picked up by config.scan(). The events page of this section covers subscribers in general.

Source: Using the Before Render Event

During development you want an edited template to appear on the next request. Pyramid has one switch for every binding: the setting pyramid.reload_templates = true, or the environment variable PYRAMID_RELOAD_TEMPLATES=1, for example PYRAMID_RELOAD_TEMPLATES=1 pserve development.ini. pyramid_jinja2 maps it to Jinja2’s auto_reload and pyramid_mako to Mako’s filesystem_checks. The cookiecutter’s development.ini sets it to true and its production.ini sets it to false, because checking the modification time of every template on every render costs time. The settings page of this section lists the other development switches (for example pyramid.reload_assets for static files, which is a different setting).

With reloading on, the second request prints version 2 Ada. With it off, a template that was already loaded is served from the cache and the second request still says version 1 Ada, until the process is restarted. A failed deployment where "the template change does not show up" is usually this cache, and the fix is a restart rather than a setting.

Source: Automatically Reloading Templates

Rendering untrusted data into HTML without escaping is cross-site scripting (XSS). Each binding has a default and a way to opt out, and the opt-out is where the vulnerabilities come from.

The rules that follow from the table are short. Never mark user-supplied text as safe. If a page must show user-written rich text, sanitise it with a library such as nh3 or bleach on input or output, and mark only the sanitised result. Escaping is context-sensitive: an escaped value is safe inside element content and quoted attribute values but not inside <script> blocks, inline event handlers or href values that begin with javascript:. To pass data to JavaScript, serialise it with Jinja2’s tojson filter into a <script type="application/json"> element or a data- attribute, and validate URLs that users can enter. A Content Security Policy header is the second line of defence and is set in a tween or a response callback (see the events page of this section).

Paragraph a contains <script>alert(1)</script> (safe), paragraph b contains the live script (the safe filter disabled the protection), paragraph c renders <em>ok</em> because the application deliberately constructed a Markup value, and the JSON element contains \u003c/script\u003e instead of a literal closing tag, as produced by tojson, so that a value cannot close the element early. Review every use of safe, structure:, n and Markup in code review as you would review eval.

Source: pyramid_jinja2: jinja2.autoescape

Every template rendered through a Pyramid renderer has a function get_csrf_token() in its globals. It returns the current CSRF token as a string, to be placed in a hidden form field or an X-CSRF-Token header. The CSRF page of this section covers token storage and verification; the template side is one line: <input type="hidden" name="csrf_token" value="{{ get_csrf_token() }}">.

The check prints True post. The default token storage is the session, so a session factory (or another storage policy set with set_csrf_storage_policy) must be configured; without one get_csrf_token() raises an AttributeError saying that no session factory is registered, and the template fails with it.

Source: Using the get_csrf_token global in templates

A renderer-configured view returns a dictionary, so its unit test needs no template at all. To test a template, render it with pyramid.renderers.render inside a pyramid.testing.setUp() configuration that has the binding included. For a functional test, use WebTest as in the examples above: response.html is a BeautifulSoup tree and response.forms holds the forms of the page, and the application already runs with jinja2.undefined = strict.

Forgetting config.include("pyramid_jinja2") in a unit test raises ValueError: No such renderer factory .jinja2, because the binding’s renderer is only registered when it is included. Testing is covered fully in the testing page of this section.

Source: Unit, Integration, and Functional Testing

Any engine can be used as a renderer by writing a renderer factory and registering it with config.add_renderer(".ext", factory); the official Renderers chapter shows the contract (a callable receiving the value returned by the view and the system values, returning a string). Using an engine only from inside views without a binding works too, but, as noted above, loses reloading and overriding. Because Pyramid is synchronous, a template is rendered inside the view’s worker thread and a slow template blocks that thread; there is no streaming or async rendering as in the Flask (Jinja Templates) and Tornado (Templates & UI Modules) sections of this site.

Source: Adding and Changing Renderers

Pyramid separates rendering from view logic: views return dictionaries and a renderer named in the view configuration turns them into HTML. The renderer comes from a binding package that matches the file extension, and pyramid_jinja2 is the recommended one. Name templates by asset specification so they can be overridden, enable strict undefined variables in development and in tests, add shared values with BeforeRender, keep autoescaping on, and leave template reloading off in production.