Route registration syntax

[Tinche]

I'm brainstorming API registration syntaxes.

The contenders:

• Flask-style (also used by Quart, FastAPI, Sanic, aiohttp (when using RouteDef))

@app.get("/")
async def index(): ...

• Starlette-style (also used by aiohttp by default)

async def index(): ...

app = App(routes=[Route("/", index)])

I think it's a no-brainer, Flask wins hands down. Still, maybe worth considering the alternatives.

@hynek @wbolster

[hynek]

If you go the Flask way, you also need support for something like Blueprints.

The starlette style (that is also the Falcon and Pyramid style – and I believe Django?) has the upside that the routes configuration is centralized.

I can live with both.

[Tinche]

Blueprints: good point, need to consider for later.

Centralization: I think the Flask style can be converted into the Starlette style pretty easily (you don't have to apply the decorator right then and there, you can choose to apply it later in a central location). The Starlette style cannot be easily converted into Flask style (you need to write an additional class or something).

[wbolster]

i agree, for 99% of cases decorator style apis are nicer for "registration" apis.

but i usually prefer to implement those decorators on top of a more conventional "register(thing, callback, whatever=else)" api, so you can have the best of both worlds. i believe flask itself does just that, making it possible to have centralized routing or even a mix. this can be useful in some cases, e.g. when conditionally adding a route. cases like that often depend on some kind of configuration (e.g. DEBUG=1 env var), and that can be annoying to do with decorators, because those are typically used at the module level, and hence executed at import time.

(i personally don't like functions that magically behave like a decorator sometimes, and typing them is not nice, requiring overloads and unions etc)