aiohttp_jinja2

jinja2 template renderer for aiohttp.web.

Usage

Before template rendering you have to setup jinja2 environment (jinja2.Environment) first:

app = web.Application()
aiohttp_jinja2.setup(app,
    loader=jinja2.FileSystemLoader('/path/to/templates/folder'))

After that you may use template engine in your web-handlers. The most convenient way is to decorate a web-handler.

Using the function based web handlers:

@aiohttp_jinja2.template('tmpl.jinja2')
def handler(request):
    return {'name': 'Andrew', 'surname': 'Svetlov'}

Or the class-based views (aiohttp.web.View):

class Handler(web.View):
    @aiohttp_jinja2.template('tmpl.jinja2')
    async def get(self):
        return {'name': 'Andrew', 'surname': 'Svetlov'}

On handler call the template() decorator will pass returned dictionary {'name': 'Andrew', 'surname': 'Svetlov'} into template named "tmpl.jinja2" for getting resulting HTML text.

More complex template processing can be achieved by modifying the existing list of global functions. Modification of Jinja2’s environment can be done via get_env(). For example, adding the zip function:

env = aiohttp_jinja2.get_env(app)
env.globals.update(zip=zip)

Which can now to be used in any template:

{% for value, square in zip(values, squares) %}
    <p>The square of {{ value }} is {{ square }}.</p>
{% endfor %}

In some cases, finer control over the dataflow may also be required. This can be worked out by explicitly asking for template to be rendered using render_template(). Explicit rendering will allow to possibly pass some context to the renderer and also to modify its response on the fly. This can for example be used to set response headers:

async def handler(request):
    context = {'name': 'Andrew', 'surname': 'Svetlov'}
    response = aiohttp_jinja2.render_template('tmpl.jinja2',
                                              request,
                                              context)
    response.headers['Content-Language'] = 'ru'
    return response

This, again, can also be done with a class-based view (aiohttp.web.View):

class Handler(web.View):
    async def get(self):
        context = {'name': 'Andrew', 'surname': 'Svetlov'}
        response = aiohttp_jinja2.render_template('tmpl.jinja2',
                                                  self.request,
                                                  context)
        response.headers['Content-Language'] = 'ru'
        return response

Context processors is a way to add some variables to each template context. It works like jinja2.Environment().globals, but calculate variables each request. So if you need to add global constants it will be better to use jinja2.Environment().globals directly. But if you variables depends of request (e.g. current user) you have to use context processors.

Context processors is following last-win strategy. Therefore a context processor could rewrite variables delivered with previous one.

In order to use context processors create required processors:

async def foo_processor(request):
    return {'foo': 'bar'}

And pass them into setup():

aiohttp_jinja2.setup(
    app,
    context_processors=[foo_processor,
                        aiohttp_jinja2.request_processor],
    loader=loader)

As you can see, there is a built-in request_processor(), which adds current aiohttp.web.Request into context of templates under 'request' name.

Here is an example of how to add current user dependant logic to template (requires aiohttp_security library):

from aiohttp_security import authorized_userid

async def current_user_ctx_processor(request):
    userid = await authorized_userid(request)
    is_anonymous = not bool(userid)
    return {'current_user': {'is_anonymous': is_anonymous}}

Template:

<body>
    <div>
        {% if current_user.is_anonymous %}
            <a href="{{ url('login') }}">Login</a>
        {% else %}
            <a href="{{ url('logout') }}">Logout</a>
        {% endif %}
    </div>
</body>

Async functions

If you pass the enable_async parameter to the setup function, then you will need to use the async functions for rendering:

aiohttp_jinja2.setup(
    app, enable_async=True,
    loader=jinja2.FileSystemLoader('/path/to/templates/folder'))

...

async def handler(request):
    return await aiohttp_jinja2.render_template_async(
        'tmpl.jinja2', request)

The @aiohttp_jinja2.template decorator will work for both cases.

Default Globals

app is always made in templates via jinja2.Environment().globals:

<body>
    <h1>Welcome to {{ app['name'] }}</h1>
</body>

Two more helpers are also enabled by default: url and static.

url can be used with just a view name:

<body>
    <a href="{{ url('index') }}">Index Page</a>
</body>

Or with arguments:

<body>
    <a href="{{ url('user', id=123) }}">User Page</a>
</body>

A query can be added to the url with the special query_ keyword argument:

<body>
    <a href="{{ url('user', id=123, query_={'foo': 'bar'}) }}">User Page</a>
</body>

For a view defined by app.router.add_get('/user-profile/{id}/', user, name='user'), the above would give:

<body>
    <a href="/user-profile/123/?foo=bar">User Page</a>
</body>

This is useful as it would allow your static path to switch in deployment or testing with just one line.

The static function has similar usage, except it requires you to set app[aiohttp_jinja2.static_root_key].

app = web.Application()
aiohttp_jinja2.setup(app, loader=jinja2.FileSystemLoader("/path/to/templates/folder"))
app[aiohttp_jinja2.static_root_key] = "/static"

Then in the template:

<script src="{{ static('dist/main.js') }}"></script>

Would result in:

<script src="/static/dist/main.js"></script>

Both url and static can be disabled by passing default_helpers=False to aiohttp_jinja2.setup.

Library Installation

The aiohttp_jinja2 can be installed by pip:

$ pip3 install aiohttp_jinja2

Source code

The project is hosted on GitHub.

Please feel free to file an issue on bug tracker if you have found a bug or have some suggestion for library improvement.

The library uses Travis for Continuous Integration.

License

aiohttp_jinja2 is offered under the Apache 2 license.

Contents

Indices and tables

Glossary

jinja2

A modern and designer-friendly templating language for Python.

See http://jinja.pocoo.org/

web-handler

An endpoint that returns http response.