aiohttp-jinja2

Warnings

• breaking The `static_root_url` key for accessing static file configuration has been deprecated in favor of `aiohttp.web.AppKey`. Update application configuration to use `AppKey` instances.
  Fix: Replace direct string key access (e.g., `app['static_root_url']`) with `aiohttp.web.AppKey` instances for configuration.
• breaking Python 3.7 is no longer supported. The library now requires Python 3.8 or newer.
  Fix: Upgrade your Python environment to 3.8, 3.9, 3.10, 3.11, or 3.12.
• breaking Jinja2 versions older than 3.0 are no longer supported. This can lead to package conflicts if other dependencies require older Jinja2 versions.
  Fix: Ensure `jinja2` is installed at version `3.0.0` or higher.
• deprecated Decorating non-async functions with `@aiohttp_jinja2.template` is no longer supported. All web handlers using this decorator must be `async` functions.
  Fix: Refactor web handlers decorated with `@aiohttp_jinja2.template` to be `async def` functions.
• gotcha Asynchronous functions (coroutines) cannot be directly called from within Jinja2 templates. They must be awaited in the handler before passing their results to the template context.
  Fix: Ensure any data requiring an `await` call is resolved in your `aiohttp` handler before constructing the context dictionary passed to the template.
• gotcha When using `aiohttp.web.RouteTableDef` with `@aiohttp_jinja2.template`, the `@template` decorator must be applied *before* the `@routes.get()` (or other HTTP method) decorator.
  Fix: Correct the decorator order: ` @routes.get('/path') @aiohttp_jinja2.template('template.html') async def handler(...): ... `

Install

• pip install aiohttp-jinja2 Install stable version

Imports

• setup

  import aiohttp_jinja2
  from aiohttp import web
  import jinja2
  
  app = web.Application()
  aiohttp_jinja2.setup(app, loader=jinja2.FileSystemLoader('templates'))

  Initializes the Jinja2 environment for the aiohttp application.
• template

  from aiohttp import web
  import aiohttp_jinja2
  
  @routes.get('/hello')
  @aiohttp_jinja2.template('index.html')
  async def handler(request: web.Request):
      return {'name': 'World'}

  The `@template` decorator must be applied *before* route decorators like `@routes.get()` to ensure proper functionality.
• render_template

  from aiohttp import web
  import aiohttp_jinja2
  
  async def handler(request: web.Request):
      context = {'data': 'Some info'}
      response = aiohttp_jinja2.render_template('page.html', request, context)
      response.headers['Content-Language'] = 'en'
      return response

  For handlers requiring more control over the response (e.g., setting headers) or explicit rendering.

Quickstart

This quickstart demonstrates how to set up `aiohttp-jinja2` with an `aiohttp.web` application. It initializes the Jinja2 environment, defines a template directory, and uses the `@aiohttp_jinja2.template` decorator to render HTML responses for different routes. Create a 'templates' directory with `index.html` and `hello.html` files (e.g., `index.html`: `<h1>{{ title }}</h1>`, `hello.html`: `<h1>Hello, {{ name }}!</h1>`).

import os
from aiohttp import web
import aiohttp_jinja2
import jinja2

async def hello_page(request):
    name = request.match_info.get('name', 'Anonymous')
    return {'name': name, 'title': 'Hello Page'}

async def welcome_page(request):
    return {'title': 'Welcome'}

def setup_routes(app):
    aiohttp_jinja2.setup(
        app, 
        loader=jinja2.FileSystemLoader(
            os.path.join(os.path.dirname(__file__), 'templates')
        )
    )

    routes = web.RouteTableDef()

    @routes.get('/')
    @aiohttp_jinja2.template('index.html')
    async def index(request: web.Request):
        return await welcome_page(request)

    @routes.get('/hello/{name}')
    @aiohttp_jinja2.template('hello.html')
    async def hello(request: web.Request):
        return await hello_page(request)

    app.add_routes(routes)


if __name__ == '__main__':
    app = web.Application()
    setup_routes(app)
    web.run_app(app, port=8080)