pyramid_jinja2¶
Overview¶
pyramid_jinja2 is a set of bindings that make templates written for the Jinja2 templating system work under the Pyramid web framework.
Installation¶
Install using pip
, where $VENV
is the path to a virtual environment.
$ $VENV/bin/pip install pyramid_jinja2
Setup¶
Note
If you start a project from scratch, consider using the project 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
includeme()
function viainclude()
.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 use 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 in any of these ways, the following happens:
Files with the
.jinja2
extension are considered to be Jinja2 templates and ajinja2.Environment
is registered to handle this extension.The
pyramid_jinja2.add_jinja2_renderer()
directive is added to the Configurator instance.The
pyramid_jinja2.add_jinja2_search_path()
directive is added to the Configurator instance.The
pyramid_jinja2.add_jinja2_extension()
directive is added to the Configurator instance.The
pyramid_jinja2.get_jinja2_environment()
directive is added to the Configurator instance.
Preparing for distribution¶
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
Usage¶
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.
Template Lookup Mechanisms¶
There are several ways to configure pyramid_jinja2
to find your templates.
Asset Specifications¶
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:
1@view_config(renderer='mypackage:templates/foo.jinja2')
2def hello_world(request):
3 return {'a': 1}
Asset specifications have some significant benefits in Pyramid, as they can be fully overridden. An add-on package can ship with code that renders using asset specifications. Later, another package can externally override the templates without having to actually modify the add-on in any way. See Overriding Assets for more information.
Caller-Relative Template Lookup¶
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:
1@view_config(renderer='templates/mytemplate.jinja2')
2def my_view(request):
3 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.
A caller-relative template lookup is converted to a asset specification
underneath the hood. This means that it’s almost always possible to override
the actual template in an add-on package without having to fork the add-on
itself. For example, the full asset specification for the view above would be
myapp.admin.views:templates/mytemplate.jinja2
. This template, or the
entire templates
folder, may be overridden.
config.override_asset(
to_override='myapp.admin.views:templates/mytemplate.jinja2',
override_with='yourapp:templates/sometemplate.jinja2')
See Overriding Assets for more information.
Search Path-Based Template Lookup¶
When used outside of Pyramid, Jinja2’s default lookup mechanism is a search
path. To use a search path within Pyramid, simply define the
jinja2.directories
configuration setting, or use the
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
will always be added
to the search path (in most cases this is the top-level package in your
application). This behavior may be deprecated or removed in the future.
It is always better to specify your search path explicitly.
Templates Including Templates¶
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, template-relative names, and normal
template names found on the search path. The search path will always be
consulted if a template cannot be found relative to the parent
template. For example, if you had a template named templates/child.jinja2
that wanted to extend templates/base.jinja2
, then it could use
{% extends 'base.jinja2' %}
and locate the file relative to itself.
Alternatively it could use {% extends 'templates/base.jinja2' %}
to find
the template in a templates
sub-folder rooted on the search path. The
template-relative option will always override the search path.
An example:
1<!-- templates/layout.jinja2 -->
2<!DOCTYPE html>
3<html lang="en">
4<head>
5 <meta charset="utf-8">
6 <title>Hello World!</title>
7 <link rel="stylesheet" href="style.css">
8</head>
9<body>
10 <div id="content">{% block content %}{% endblock %}</div>
11</body>
12</html>
1<!-- templates/root.jinja2 -->
2{% extends "templates/layout.jinja2" %}
3{% block content %}
4<h1>Yes</h1>
5<p>
6 Some random paragraph.
7</p>
8{% endblock %}
For further information on Template Inheritance in Jinja2 templates please see Template Inheritance in Jinja2 documentation.
Adding or Overriding a Renderer¶
By default, only templates ending in the .jinja2
file extension are
supported. However, it is very easy to add support for alternative 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 alternative 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 set up 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.
Internalization (i18n)¶
When pyramid_jinja2 is included in a Pyramid application, jinja2.ext.i18n 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
.
Settings¶
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.
Generic Settings¶
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, 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¶
Jinja2 autoescape setting.
Possible values: true
or false
.
Warning
By default Jinja2 sets autoescape
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 }}
.
pyramid.reload_templates¶
For usage see Pyramid: Automatically Reloading Templates.
True
or False
represent whether Jinja2 templates should be reloaded
when they change on disk. In development, it is useful to set it to True
.
This setting sets the Jinja2 auto_reload
setting.
reload_templates¶
Warning
Deprecated as of version 1.5, use pyramid.reload_templates instead.
jinja2.auto_reload¶
Use Pyramid pyramid.reload_templates setting.
jinja2.directories¶
A list of directory names, or a newline-delimited string, where each line
represents a directory name. These locations are where Jinja2 will search for
templates. Each can optionally be an absolute resource specification (e.g.,
package:subdirectory/
).
jinja2.input_encoding¶
The input encoding of templates. Defaults to utf-8
.
jinja2.undefined¶
Changes the undefined types that are used when a variable name lookup fails.
If unset, defaults to Undefined
(silent ignore). Setting
it to strict
will trigger StrictUndefined
behavior
(which raises an error, and is recommended for development). Setting it to
debug
will trigger DebugUndefined
, which outputs
debug information in some cases. See Undefined Types.
jinja2.extensions¶
A list of extension objects, or a newline-delimited set of dotted import locations, where each line represents an extension. jinja2.ext.i18n is automatically activated.
jinja2.i18n.domain¶
Pyramid domain for translations. See Translation Domain in the
Pyramid documentation. Defaults to the name of the package that activated
pyramid_jinja2 or if that fails it will use messages
as the domain.
jinja2.i18n.gettext¶
A subclass of pyramid_jinja2.i18n.GetTextWrapper
to override
gettext
and ngettext
methods in Jinja i18n extension. The Subclass can
be either a dotted name or the subclass itself.
jinja2.filters¶
A dictionary mapping a filter name to a filter object, or a newline-delimited string with each line in the format:
name = dotted.name.to.filter
representing Jinja2 filters.
jinja2.globals¶
A dictionary mapping a global name to a global template object, or a newline-delimited string with each line in the format:
name = dotted.name.to.globals
representing Jinja2 globals
jinja2.tests¶
A dictionary mapping a test name to a test object, or a newline-delimited string with each line in the format:
name = dotted.name.to.test
representing Jinja2 tests.
jinja2.bytecode_caching¶
If set to true
, a file system bytecode cache will be configured in a
directory determined by jinja2.bytecode_caching_directory. To configure
other types of bytecode caching, jinja2.bytecode_caching
may also be set
directly to an instance of jinja2.BytecodeCache
. However doing so
cannot be done in a paste .ini
file and it must be done programmatically.
By default, no bytecode cache is configured.
Changed in version 1.10: Previously, jinja2.bytecode_caching
defaulted to true
.
Note that configuring a filesystem bytecode cache will (not surprisingly) 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 for more information on bytecode caching.
Changed in version 1.10: Previously, an atexit
callback which called
jinja2.BytecodeCache.clear()
was registered in an effort
to delete the cache files. This is no longer done.
jinja2.bytecode_caching_directory¶
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
.
jinja2.newstyle¶
true
or false
to enable the use of newstyle
gettext
calls.
Defaults to false
.
See New Style Gettext.
jinja2.finalize¶
A callable or a dotted-import string.
Jinja2 Filters¶
pyramid_jinja2
comes with Pyramid routing specific filters. All Jinja2
built-in filters are enabled in templates. Read how Filters work
in Jinja2.
Installing filters¶
To use these filters, configure the settings of jinja2.filters
:
1[app:yourapp]
2# ... other stuff ...
3jinja2.filters =
4 model_url = pyramid_jinja2.filters:model_url_filter
5 route_url = pyramid_jinja2.filters:route_url_filter
6 static_url = pyramid_jinja2.filters:static_url_filter
Filter reference¶
- pyramid_jinja2.filters.resource_url_filter(ctx, model, *elements, **kw)¶
A filter from
model
to a string representing the absolute URL. This filter callspyramid.url.resource_url()
.Example:
<a href="{{'my_traversable_object'|resource_url}}"> See my object </a>
You can also specify optional view name attached at the end of a path:
<a href="{{'my_traversable_object'|resource_url('edit')}}"> Edit my object </a>
- pyramid_jinja2.filters.model_url_filter(ctx, model, *elements, **kw)¶
A filter from
model
to a string representing the absolute URL. This filter callspyramid.url.resource_url()
.Note
This is being deprecated. See
pyramid_jinja2.filters.resource_url()
- pyramid_jinja2.filters.route_url_filter(ctx, route_name, *elements, **kw)¶
A filter from
route_name
to a string representing the absolute URL. This filter callspyramid.url.route_url()
.Example:
<a href="{{'login'|route_url}}"> Sign in </a>
- pyramid_jinja2.filters.static_url_filter(ctx, path, **kw)¶
A filter from
path
to a string representing the absolute URL. This filter callspyramid.url.static_url()
.Example:
<link rel="stylesheet" href="{{'yourapp:static/css/style.css'|static_url}}" />
- pyramid_jinja2.filters.model_path_filter(ctx, model, *elements, **kw)¶
A filter from
model
to a string representing the relative URL. This filter callspyramid.request.Request.resource_path()
.
- pyramid_jinja2.filters.route_path_filter(ctx, route_name, *elements, **kw)¶
A filter from
route_name
to a string representing the relative URL. This filter callspyramid.url.route_path()
.
- pyramid_jinja2.filters.static_path_filter(ctx, path, **kw)¶
A filter from
path
to a string representing the relative URL. This filter callspyramid.url.static_path()
.
Creating a Jinja2 Pyramid project¶
After you have installed pyramid_jinja2
, you can invoke the following
command to create a Jinja2-based Pyramid project from its included scaffold.
$ $VENV/bin/pcreate -s pyramid_jinja2_starter myproject
After it’s created, you can visit the myproject
directory and install the
project in development mode.
$ cd myproject
$ $VENV/bin/pip install -e .
At this point you can start the application like any other Pyramid application.
$ $VENV/bin/pserve development.ini
This is a good way to see a working Pyramid application that uses Jinja2, even if you do not end up using the result.
See also
See also Creating a Pyramid Project.
Running tests for your application¶
The scaffold provides a convenience for the developer to install pytest
and
pytest-cov
as the test runner and test coverage. To run unit tests for your
application, you must first install the testing dependencies.
$ $VENV/bin/pip install -e ".[testing]"
Once the testing requirements are installed, then you can run the tests using
the py.test
command that was just installed in the bin
directory of
your virtual environment. The -q
option means “quiet” output, and the
--cov
option includes test coverage.
$ $VENV/bin/py.test -q --cov
The scaffold includes configuration defaults for py.test
and test coverage.
These configuration files are pytest.ini
and .coveragerc
, located at
the root of your package. Without these defaults, we would need to specify the
path to the module on which we want to run tests and coverage.
$ $VENV/bin/py.test -q --cov=myproject myproject/tests.py
See also
See py.test’s documentation for How to invoke pytest or invoke
py.test -h
to see its full set of options.
pcreate template i18n¶
The pcreate 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
$ $VENV/bin/pip install Babel
# extract translatable strings from *.jinja2 / *.py
$ $VENV/bin/python setup.py extract_messages
$ $VENV/bin/python setup.py update_catalog
# Translate strings in <mypackage>/locale/<mylocale>/LC_MESSAGES/<myproject>.po
# and re-compile *.po files
$ $VENV/bin/python setup.py compile_catalog
If you see the following output:
running compile_catalog
1 of 1 messages (100%) translated in myproject/locale/de/LC_MESSAGES/myproject.po
catalog myproject/locale/de/LC_MESSAGES/myproject.po is marked as fuzzy, skipping
1 of 1 messages (100%) translated in myproject/locale/fr/LC_MESSAGES/myproject.po
catalog myproject/locale/fr/LC_MESSAGES/myproject.po is marked as fuzzy, skipping
When an item is marked as fuzzy, then you should review your .po files to make sure translations are correct. Fuzzy is not exact matching, but matches most of a word (its root) or phrase.
When you are satisfied that the translations are good, you can either remove the line marked with #, fuzzy immediately above its related msgid line (preferred) or force Babel to compile the message catalog with the -f flag.
$ $VENV/bin/python setup.py compile_catalog -f
Assuming you have already created a project following the instructions under
Creating a Jinja2 Pyramid project, and started your application with pserve
,
then you should be able to view the various translations. Simply append a GET
parameter, such as http://localhost:6543/?_LOCALE_=de for German,
http://localhost:6543/?_LOCALE_=fr for French, or
http://localhost:6543/?_LOCALE_=en for English. The default language does not
require GET parameter.
The application could set the user’s language preference with a cookie based on request parameters sent on the first request. Alternatively, and usually as a fallback, the application could read the web browser’s Accept-Language header sent with each request and set the appropriate language. For example:
@subscriber(NewRequest)
def prepare_env(event):
request = event.request
# set locale depending on browser settings
settings = request.registry.settings
locale = settings.get('pyramid.default_locale_name', 'en')
available = [loc['code'] for loc in AVAILABLE_LOCALES]
if request.accept_language:
accepted = request.accept_language
locale = accepted.best_match(available, locale)
request._LOCALE_ = locale
More Information¶
Reporting Bugs / Development Versions¶
Visit http://github.com/Pylons/pyramid_jinja2 to download development or tagged versions.
Visit http://github.com/Pylons/pyramid_jinja2/issues to report bugs.