pyramid_jinja2
is a set of bindings that make templates written for the Jinja2
templating system work under the Pyramid
web framework.
Install using setuptools, e.g. (within a virtualenv):
$ $VENV/bin/easy_install pyramid_jinja2
Note
If you start a project from scratch, consider using the project template <jinja2_starter_template>
which comes with a working setup and sensible defaults.
There are multiple ways to make sure that pyramid_jinja2
is active. All are completely equivalent:
Use the :py
~pyramid_jinja2.includeme
function via :py~pyramid.config.Configurator.include
:config = Configurator() config.include('pyramid_jinja2')
Add
pyramid_jinja2
to the list of yourpyramid.includes
in your.ini
settings file:pyramid.includes = pyramid_jinja2
If you're using pyramid_zcml instead of imperative configuration, ensure that some ZCML file with an analogue of the following contents is executed by your Pyramid application:
<include package="pyramid_jinja2"/>
Once activated either of these says, the following happens:
- Files with the
.jinja2
extension are considered to beJinja2
templates and ajinja2.Environment
is registered to handle this extension. - The
pyramid_jinja2.add_jinja2_renderer
directive is added to theConfigurator
instance. - The
pyramid_jinja2.add_jinja2_search_path
directive is added to theConfigurator
instance. - The
pyramid_jinja2.add_jinja2_extension
directive is added to theConfigurator
instance. - The
pyramid_jinja2.get_jinja2_environment
directive is added to theConfigurator
instance.
If you want to make sure your .jinja2
template files are included in your package's source distribution (e.g. when using python setup.py sdist
), add *.jinja2
to your MANIFEST.in
:
recursive-include yourapp *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.jinja2 *.js *.html *.xml
Once pyramid_jinja2 has been activated, .jinja2
templates can be used by the Pyramid rendering system.
When used as the renderer
argument of a view, the view must return a Python dict
which will be passed into the template as the set of available variables.
There are several ways to configure pyramid_jinja2 to find your templates.
Templates may always be defined using an asset specification
. These are strings which define an absolute location of the template relative to some Python package. For example myapp.views:templates/home.jinja2
. These specifications are supported throughout Pyramid and provide a fool-proof way to find any supporting assets bundled with your application.
Here's an example view configuration which uses an asset specification
:
@view_config(renderer='mypackage:templates/foo.jinja2')
def hello_world(request):
return {'a': 1}
Asset specifications have some significant benefits in Pyramid, as they are fully overridable. An addon package can ship with code that renders using asset specifications. Later another package can externally override the templates without having to actually modify the addon in any way. See pyramid:overriding_assets_section
for more information.
Note
All lookup mechanisms in pyramid_jinja2 actually convert a requested template into an asset specification
underneath the hood except for absolute paths. This means that it's almost always possible to override the actual templates in an addon package without having to fork the addon itself.
By default, templates are discovered relative to the caller's package. This means that if you define a view in a Python module, the templates would be found relative to the module's directory on the filesystem.
Let's look at an example:
@view_config(renderer='templates/mytemplate.jinja2')
def my_view(request):
return {'foo': 1, 'bar': 2}
Imagine that the above code is in a myapp.admin.views
module. The template would be relative to that module on the filesystem, as shown below:
myapp
|- __init__.py
`- admin
|- views.py
`- templates
|- base.jinja2
`- mytemplate.jinja2
Caller-relative lookup avoids naming collisions which can be common in a search path-based approach.
When used outside of Pyramid, Jinja2's default lookup mechanism is a search path. To use this mechanism within Pyramid, simply define the search path using the jinja2.directories
configuration setting or the ~pyramid_jinja2.add_jinja2_search_path
configurator directive.
Rendering Jinja2
templates with a search path is typically done as follows:
@view_config(renderer='mytemplate.jinja2')
def my_view(request):
return {'foo': 1, 'bar': 2}
If mytemplate.jinja2
is not found in the same directory as the module then it will be searched for on the search path. We are now dependent on our configuration settings to tell us where the template may be located. Commonly a templates
directory is created at the base of the package and the configuration file will include the following directive:
jinja2.directories = mypkg:templates
Warning
It is possible to specify a relative path to the templates folder, such as jinja2.directories = templates
. This folder will be found relative to the first package that includes pyramid_jinja2, which will normally be the root of your application. It is always better to be explicit when in doubt.
Note
The package that includes pyramid_jinja2 or the package that adds a new renderer via pyramid_jinja2.add_jinja2_renderer
will always be added to the search path.
Jinja2
allows template inheritance
as well as other mechanisms for templates to load each other. The lookup mechanisms supported in these cases include asset specifications and template-relative names. The search path will also be consulted, but the name of the requested template will always be mounted with respect to its child. For example if you had a template named templates/child.jinja2
that wanted to extend templates/base.jinja2
then it would use {% extends 'base.jinja2' %}
and locate the file relative to itself.
An example:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!-- templates/layout.jinja2 -->
<html lang="en">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
</body>
<!-- templates/root.jinja2 -->
{% extends "templates/layout.jinja2" %}
{% block content %}
<h1>Yes</h1>
<p>
Some random paragraph.
</p>
{% endblock %}
For further information on Template Inheritance
in Jinja2 templates please see Template Inheritance <jinja2:template-inheritance>
in Jinja2 documentation.
By default, only templates ending in the .jinja2
file extension are supported. However, it is very easy to add support for alternate file extensions using the pyramid_jinja2.add_jinja2_renderer
directive.
config.include('pyramid_jinja2')
config.add_jinja2_renderer('.html')
It would now be possible to use templates named foo.html
and foo.jinja2
. Each renderer extension will use its own jinja2.Environment
. These alternate renderers can be extended at runtime using the name
parameter to the other directives such as pyramid_jinja2.get_jinja2_environment
.
config.include('pyramid_jinja2')
config.add_jinja2_renderer('.html')
config.add_jinja2_search_path('myapp:templates', name='.html')
It is also possible to setup different renderers that use different search paths, configuration settings and environments if necessary. This technique can come in handy when different defaults are required for rendering templates with different content types. For example, a plain text email body versus an html page. For this reason, pyramid_jinja2.add_jinja2_renderer
accepts an optional parameter settings_prefix
which can point a renderer at a different group of settings.
settings = {
'jinja2.directories': 'myapp:html_templates',
'mail.jinja2.directories': 'myapp:email_templates',
}
config = Configurator(settings=settings)
config.include('pyramid_jinja2')
config.add_jinja2_renderer('.email', settings_prefix='mail.jinja2.')
Now foo.email
will be rendered using the mail.jinja2.*
settings.
When pyramid_jinja2
is included in a Pyramid application, jinja2.ext.i18n <jinja2:i18n-extension>
is automatically activated.
Be sure to configure jinja2.i18n.domain according to setup.cfg domain settings. By default, jinja2.i18n.domain is set to the name of the package that included pyramid_jinja2. If no package was found, it will use messages
.
Jinja2
derives additional settings to configure its template renderer. Many of these settings are optional and only need to be set if they should be different from the default. The below values can be present in the .ini
file used to configure the Pyramid application (in the app
section representing your Pyramid app) or they can be passed directly within the settings
argument passed to a Pyramid Configurator.
These settings correspond to the ones documented in Jinja2. Set them accordingly.
For reference please see: http://jinja.pocoo.org/docs/api/#high-level-api
Note
For the boolean settings please use true
or false
jinja2.block_start_string
jinja2.block_end_string
jinja2.variable_start_string
jinja2.variable_end_string
jinja2.comment_start_string
jinja2.comment_end_string
jinja2.line_statement_prefix
jinja2.line_comment_prefix
jinja2.trim_blocks
jinja2.newline_sequence
jinja2.optimized
jinja2.cache_size
Jinja2 autoescape setting.
Possible values: true
or false
.
Warning
By default Jinja2 sets autoescaping to False
.
pyramid_jinja2 sets it to true as it is considered a good security practice in a web setting where we want to prevent XSS attacks from rendering unsanitized user-generated content. To turn off escaping on a case-by-case basis you may use the safe
filter such as {{ html_blob | safe }}
.
For usage see Pyramid: Automatically Reloading Templates
<pyramid:reload_templates_section>
.
true
or false
representing whether Jinja2 templates should be reloaded when they change on disk. Useful for development to be true
. This setting sets the Jinja2 auto_reload
setting.
Warning
Deprecated as of version 1.5, use setting_reload_templates
instead
Use Pyramid setting_reload_templates
setting.
A list of directory names or a newline-delimited string with each line representing a directory name. These locations are where Jinja2 will search for templates. Each can optionally be an absolute resource specification (e.g. package:subdirectory/
).
The input encoding of templates. Defaults to utf-8
.
Changes the undefined types that are used when a variable name lookup fails. If unset, defaults to :py~jinja2.Undefined
(silent ignore). Setting it to strict
will trigger :py~jinja2.StrictUndefined
behavior (raising an error, this is recommended for development). Setting it to debug
will trigger :py~jinja2.DebugUndefined
, which outputs debug information in some cases. See Undefined Types
A list of extension objects or a newline-delimited set of dotted import locations where each line represents an extension. jinja2.ext.i18n
<jinja2:i18n-extension>
is automatically activated.
Pyramid domain for translations. See Translation Domain
in Pyramid documentation. Defaults to the name of the package that activated pyramid_jinja2 or if that fails it will use messages
as the domain.
A dictionary mapping filter name to filter object, or a newline-delimted string with each line in the format:
name = dotted.name.to.filter
representing Jinja2 filters <jinja2:writing-filters>
.
A dictionary mapping global name to global template object, or a newline-delimited string with each line in the format:
name = dotted.name.to.globals
representing Jinja2 globals <jinja2:global-namespace>
A dictionary mapping test name to test object, or a newline-delimted string with each line in the format:
name = dotted.name.to.test
representing Jinja2 tests <jinja2:writing-tests>
.
If set to true
, a filesystem bytecode cache will be configured (in a directory determined by setting_jinja2_byte_cache_dir
.) To configure other types of bytecode caching, jinja2.bytecode_caching
may also be set directly to an instance of jinja2.BytecodeCache
(This can not be done in a paste .ini
file, however, it must be done programatically.) By default, no bytecode cache is configured.
1.10
Previously, jinja2.bytecode_caching
defaulted to true
.
Note that configuring a filesystem bytecode cache will (not surprisiningly) generate files in the cache directory. As templates are changed, some of these will become stale, pointless wastes of disk space. You are advised to consider a clean up strategy (such as a cron job) to check for and remove such files.
See the Jinja2 Documentation <jinja2:bytecode-cache>
for more information on bytecode caching.
1.10
Previously, an atexit callback which called :pyjinja2.BytecodeCache.clear
was registered in an effort to delete the cache files. This is no longer done.
Absolute path to directory to store bytecode cache files. Defaults to the system temporary directory. This is only used if jinja2.bytecode_caching
is set to true
.
true
or false
to enable the use of newstyle gettext calls. Defaults to false
.
See Newstyle Gettext http://jinja.pocoo.org/docs/extensions/#newstyle-gettext
pyramid_jinja2
provides following filters.
pyramid_jinja2.filters
model_url_filter
route_url_filter
static_url_filter
route_path_filter
static_path_filter
To use these filters, configure the settings of jinja2.filters
:
[app:yourapp]
# ... other stuff ...
jinja2.filters =
model_url = pyramid_jinja2.filters:model_url_filter
route_url = pyramid_jinja2.filters:route_url_filter
static_url = pyramid_jinja2.filters:static_url_filter
And use the filters in template.
<a href="{{context|model_url('edit')}}">Edit</a>
<a href="{{'top'|route_url}}">Top</a>
<link rel="stylesheet" href="{{'yourapp:static/css/style.css'|static_url}}" />
After you've got pyramid_jinja2
installed, you can invoke one of the following commands to create a Jinja2-based Pyramid project.
On Pyramid 1.0, 1.1, or 1.2:
$ $VENV/bin/paster create -t pyramid_jinja2_starter myproject
On Pyramid 1.3+:
$ $VENV/bin/pcreate -s pyramid_jinja2_starter myproject
After it's created, you can visit the myproject
directory and run setup.py develop
. At that point you can start the application like any other Pyramid application.
This is a good way to see a working Pyramid application that uses Jinja2, even if you wind up not using the result.
The paster template automatically sets up pot/po/mo locale files for use with the generated project.
The usual pattern for working with i18n in pyramid_jinja2 is as follows:
# make sure Babel is installed
easy_install Babel
# extract translatable strings from *.jinja2 / *.py
python setup.py extract_messages
python setup.py update_catalog
# Translate strings in <mypackage>/locale/<mylocale>/LC_MESSAGES/<myproject>.po
# and re-compile *.po files
python setup.py compile_catalog
api.rst changes.rst glossary.rst
Visit http://github.com/Pylons/pyramid_jinja2 to download development or tagged versions.
Visit http://github.com/Pylons/pyramid_jinja2/issues to report bugs.
glossary
genindex
modindex
search