Async views, Flask, and Quart

How async views are detected, why decorator order no longer matters on Flask, the one rule that still applies on Quart and older Pythons, writing async-aware decorators, and when to turn auto_reload off.

The decorator works on async def views without being told. It looks at the function at decoration time, and if the function is a coroutine function it installs an awaiting wrapper; otherwise it installs a plain one. Both wrappers share the same code for turning a dict into a response, so sync and async views cannot drift apart. From the outside there is nothing to configure:

@app.get('/async')
@chameleon_flask.template('async.pt')
async def async_world():
    await asyncio.sleep(0.01)
    return {'message': "Let's go async Chameleon!"}

The interesting part is what happens when you stack your own decorators on an async view, because that is where web frameworks get picky.

Why decorator order used to matter

Frameworks decide how to call a view by looking at the function they registered. Flask checks whether that function is a coroutine function; if it is, Flask awaits it, and if it is not, Flask calls it and expects a response back. Now stack a login_required decorator on an async view. login_required is almost always a plain def wrapper, so the function Flask registers is a plain function, even though the view underneath is async. Flask calls it, gets a coroutine object instead of a response, and fails with TypeError: The view function did not return a valid response ... but it was a coroutine.

Through 0.6.2 the only cure was a rule: put @template directly under the route decorator and your sync decorators beneath it, using functools.wraps. The rule still produces the best-behaved code, and it is still required on Quart, but on Flask with Python 3.12 or newer it is no longer required.

Flask: any order works

On Python 3.12 and newer, calling a decorated async view returns an object that awaits like the coroutine it wraps, so Flask, Quart, and asyncio.run() all treat it as one. The same object is also a WSGI callable. When a sync decorator outside @template hands it to Flask without awaiting it, Flask does what it does with any callable return value: it runs it as a WSGI application, and the view runs to completion through the same asgiref machinery Flask uses for its own async views. The result is that every arrangement below serves the page. Each row was verified against Flask with a test client:

Order, outermost first functools.wraps Flask, Python 3.12+ Flask, Python 3.10 and 3.11 Quart
route, @template, view n/a Works Works Works
route, @template, your sync decorator, view yes Works Works Works
route, @template, your sync decorator, view no Works FlaskChameleonException: returned an awaitable FlaskChameleonException: returned an awaitable
route, your sync decorator, @template, view either Works Flask TypeError: the view function did not return a valid response Quart TypeError: the response value type is not valid
route, your async decorator, @template, view either Works Works Works
route, @template, your async decorator, view either Works Works Works

A decorator with an early return, such as login_required redirecting to the login page, works in every “Works” cell too. The redirect is a Response, and it passes straight through whichever path it takes.

Quart and older Pythons: the one rule

On Quart, and on Flask under Python 3.10 or 3.11, the framework has to see a coroutine function to await the view, and a plain sync decorator stacked outside @template hides it. So keep @template directly under the route, and put your own sync decorators beneath it with functools.wraps:

import functools

import quart

import chameleon_flask


def login_required(f):
    @functools.wraps(f)
    def wrapper(*args, **kwargs):
        if not current_user():
            return quart.redirect('/login')
        return f(*args, **kwargs)
    return wrapper


@app.get('/account/settings')
@chameleon_flask.template('account/settings.pt')   # directly under the route
@login_required                                     # sync, with functools.wraps
async def settings():
    return {'user': await load_user()}

functools.wraps records the wrapped function on the wrapper, and @template follows that chain to find the async def underneath, so it installs the awaiting wrapper and the framework sees a coroutine function. Without wraps the async def is invisible, the sync wrapper is installed, and when it discovers an awaitable where it expected a dict it closes the stray coroutine and raises a FlaskChameleonException that names this fix.

Or make the decorator async

The other way out, on every framework and every Python, is a decorator that is itself async and awaits whatever it wraps:

def login_required(f):
    @functools.wraps(f)
    async def wrapper(*args, **kwargs):
        if not current_user():
            return flask.redirect('/login')
        result = f(*args, **kwargs)
        return await result if inspect.isawaitable(result) else result
    return wrapper

This is the shape to reach for when a decorator is shared between sync and async views, since the isawaitable check makes it indifferent to which kind it wraps, and it works in either position.

Flask needs the async extra

Flask runs async def views through the asgiref package, and it refuses to register one without it: RuntimeError: Install Flask with the 'async' extra in order to use async views. This library depends on flask[async], so a normal install already has it. If you see that error, Flask was installed another way, without the extra, and pip install 'flask[async]' fixes it.

Quart

Quart is the async-first sibling of Flask, with the same API shape, and the decorator does not know or care which one it is running under:

import quart

import chameleon_flask

app = quart.Quart(__name__)


@app.get('/')
@chameleon_flask.template('home/index.pt')
async def index():
    return {'videos': await video_service.latest(10)}

Return a dict for the template or a quart.Response to pass through, exactly as on Flask. The library recognizes Quart responses without importing Quart: quart.Response and flask.Response share a werkzeug base class, and the pass-through check is an isinstance against that base. Nothing Quart-specific ever has to be installed alongside this library.

The decorator-order rule above does apply on Quart, because Quart awaits only what it recognizes as a coroutine function and does not run callables the way Flask does.

auto_reload in development and production

global_init(template_folder, auto_reload=True) makes Chameleon check a template’s modification time on each render and recompile when the file changed. That is what lets you edit a .pt file and refresh the browser. It costs a file stat per render, and in production it buys nothing, because the templates do not change until the next deploy. Tie it to your dev-mode flag so production renders from the compiled cache and never touches the disk:

dev_mode = os.environ.get('APP_ENV', 'dev') == 'dev'
chameleon_flask.global_init(template_folder, auto_reload=dev_mode)

Compiled templates are cached per process. A multi-worker server compiles each template once per worker, on its first render; the cost is small and paid once.