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 convinient way is to decorate web-handler:

@aiohttp_jinja2.template('tmpl.jinja2')
def handler(request):
    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.

If you need more complex processing (set response headers for example) you may call render_template() function:

@asyncio.coroutine
def handler(request):
    context = {'name': 'Andrew', 'surname': 'Svetlov'}
    response = aiohttp_jinja2.render_template('tmpl.jinja2',
                                              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. 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:

@asyncio.coroutine
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.

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 Continious Integration.

IRC channel

You can discuss the library on Freenode at #aio-libs channel.

Reference

aiohttp_jinja2.APP_KEY

The key name in aiohttp.web.Application dictionary, 'aiohttp_jinja2_environment' for storing jinja2 environment object (jinja2.Environment).

Usually you don’t need to operate with application manually, left it to aiohttp_jinja2 functions.

aiohttp_jinja2.get_env(app, app_key=APP_KEY)

Return jinja2.Environment object which has stored in the app (aiohttp.web.Application instance).

app_key is an optional key for application dict, APP_KEY by default.

aiohttp_jinja2.render_string(template_name, request, context, *, app_key=APP_KEY)

Return str which contains template template_name filled with context.

request is a parameter from web-handler, aiohttp.web.Request instance.

app_key is an optional key for application dict, APP_KEY by default.

aiohttp_jinja2.render_template(template_name, request, context, *, app_key=APP_KEY, encoding='utf-8')

Return aiohttp.web.Response which contains template template_name filled with context.

request is a parameter from web-handler, aiohttp.web.Request instance.

app_key is an optional key for application dict, APP_KEY by default.

encoding is response encoding, 'utf-8' by default.

Returned response has Content-Type header set to 'text/html'.

aiohttp_jinja2.setup(app, *args, app_key=APP_KEY, **kwargs)

Initialize jinja2.Environment object.

app is aiohttp.web.Application instance.

args and kawargs are passed into environment constructor.

app_key is an optional key for application dict, APP_KEY by default.

The functions is rougly equivalent for:

def setup(app, *args, app_key=APP_KEY, **kwargs):
    env = jinja2.Environment(*args, **kwargs)
    app[app_key] = env
    return env

@aiohttp_jinja2.template(template_name, *, app_key=APP_KEY, encoding='utf-8', status=200)

Decorate web-handler to convert returned dict context into aiohtttp.web.Response filled with template_name template.

app_key is an optional key for application dict, APP_KEY by default.

encoding is response encoding, 'utf-8' by default.

status is HTTP status code for returned response, 200 (OK) by default.

Returned response has Content-Type header set to 'text/html'.

License

aiohttp_jinja2 is offered under the Apache 2 license.

Glossary

jinja2

A modern and designer-friendly templating language for Python.

See http://jinja.pocoo.org/

web-handler

An endpoint that returns http response.

Indices and tables

• Index
• Search Page