Document integration with more ASGI frameworks

[florimondmanca]

We should document how to integrate with various ASGI frameworks besides Starlette (relevant resources in parentheses):

• [x] Starlette
• [ ] FastAPI
• [ ] Responder
• [ ] Quart
• [ ] Sanic (listeners ≈ ASGI lifespan event handlers)

~The first step would be to moving the current "ASGI sub-mounting" Starlette-specific instructions to new section, e.g. "Integrating with an ASGI web framework". Then we can add more frameworks to the section.~ - Done. Documentation now lives under docs/, and there's an "ASGI sub-mounting" section in the User Guide. I has a Starlette example - we can add examples for the missing frameworks there. :-)

[xeor]

Looking forward to use this with FastAPI :)

[florimondmanca]

@xeor If you end up experimenting and find about how to set things up, feel free to send a PR. :)

[abusi]

I think we should change the setup.py in order to reflect that "starlette" is only a flavor of tartiflette-asgi by implementing a pip install tartiflette-asgi[starlette] way of instaling it.

having then all flavor imported on demand at init time when the tartiflette-asgi app is initialized.

something like

pip install tartiflette-asgi[fastApi]

and then in my app

from tartiflette_asgi import TartifletteApp


app = TartifletteApp.with_flavor(flavor=fastAPI)

then in TartifletteApp

import import_module

_IMPORT_MODULE = {
     "fastapi": "fastapi.application"   # example don't know were it is
     "starlette": "starlette.application"  
}

class TartifletteApp:
     @staticmethod # or a cls one this is a pseudo example
     def with_flavor(flavor, *args, **kwargs):
           return import_module(_IMPORT_MODULE[favor.lower()])(*args, **kwargs) #make an instance of the cls

[florimondmanca]

@bubu The only “flavor” we need to care about is ASGI — an interface that both Starlette and FastAPI apps implement. There really isn’t a need to specialize this library beyond ASGI. Starlette is merely a dependency that allows us to work at a higher level in this package’s code, but it really does not matter at all from our users’ perspective. As long as their app/framework implements ASGI, they’re good to go.

[florimondmanca]

Using Tartiflette-ASGI with FastAPI is most likely a matter of knowing how to mount an ASGI app on a FastAPI router — much like what we currently document for Starlette. This can be more reliably solved via documentation rather than code.

[abusi]

I think it matters, if this package depends on them, then it should be flavored. because if i'm using fastapi i don't need any other python package, if you install everything (FastAPI, Responder, Quart, Sanic, Starlette) it will certainly bring a dependency hell you won't want to manage. I merly ask that people installing tartiflette-asgi can choose which deps they want OR maybe tartiflette-asgi shouldn't depends on any of them ? which mean that the starlette deps in the setup.py should go. And it's the "integrator" choice/role to do :

tartiflette-asgi
fastapi # or any other

in it's requirements.txt ?

[florimondmanca]

So — FastAPI and Responder already depend on Starlette anyway, so we’re not adding any extra dependencies in those cases.

This leaves us with Quart and Sanic, which don’t depend on Starlette. We’d be adding Starlette to our users’ dependency tree in those cases, true.

I think it’s a very cheap price to pay, though: Starlette doesn’t have any hard dependencies itself.

If that does prove to be a problem for our users, I might be happy to consider an « ASGI backend » mechanism.

But I’ll definitely argue that it will bring a complexity to this code base that I’m not sure is worth the cheapness of using Starlette in all cases. Consider what it would mean for maintenance overhead: we’d have to integrate with the release schedule and changes of all those frameworks, vs only Starlette. But I think we all agree that maintainer time is rare as a resource, and should be kept to a minimum.

So I would treat this as « not immediately a problem, potentially happy to consider if it proves to solve an actual problem for our users down the road ». Hope this sounds fair?

[florimondmanca]

As I wrote in my previous comment, I think we do support all existing ASGI frameworks already, because of the defining characteristic of ASGI serving as a compatibility layer between otherwise incompatible apps/frameworks.

The low touch approach right now is to document examples of using tartiflette-asgi against those frameworks.

[abusi]

I'm okay with you on the principle that this should have the minimal code base possible. It's always the way to go. My first idea was probably too much, you're right.

My only remaining point is that if you have here a deps on starlette==x.y.z and that the user of this libe want to use fastapi in u.v.w BUT fastapi depends on startlette m.n.o which isn't compatible with x.y.z you'll have a problem. (An example of the many one that can exists). I think, agreeing with you BUT going a little further, that this shouldn't depends on anything and document that the choosen backend should be installed separatly. (i.e. another line in the requirement.txt). So you don't even have to manage these deps problems. It's even more time gained. But the compromise you propose is also acceptable and i'll be happy with it.

[florimondmanca]

I think, agreeing with you BUT going a little further, that this shouldn't depends on anything and document that the choosen backend should be installed separatly.

I see your point about potential dependency hell issues. I think this package needs to be as broadly compatible with Starlette as possible. At the same time, we'll want to have at least some control so that the basic APIs we use (the Request instance, the Lifespan helper, etc.) don't break without notice. We currently have Starlette pinned to 0.12.*, so I think to alleviate potential dependency hell problems, while making sure we update this package if/when 1.x comes out, we can safely loosen it to 0.*. What do you think?

[abusi]

I think that is a good idea yes. Thanks :). I really like the asgi approach, i'm very happy about this project :)