Version 1.0

[tomchristie]

Introduce App first in README / Docs intro.

• Promote the app = App() style, but then go on to demonstrate plain ASGI style example, and discuss design philosophy of "everything is just ASGI" , interoperable, eg. use TestClient with Channels.

Naming

• WebSocketSession as just WebSocket? Rename session variable as websocket in docs?
• Drop StaticFile, and just leave StaticFiles and FileResponse.
• Module naming - should it be starlette.requests/starlette.responses instead of starlette.request/starlette.response? Would fit websockets and align better with documentation titles.
• App should perhaps be Starlette instead. Less likely to be confused with plain ASGI App class examples, and mirrors eg. flask.Flask and sanic.Sanic.
• Class based views instead as HTTPEndpoint and WebSocketEndpoint?

• Zero-dependencies

Ensure that requests is only required if TestClient is used. Ensure that aiofiles is only required if FileResponse/StaticFiles is used. We could choose to push FileResponse into the starlette.staticfiles module, and only ever import aiofiles from there.

Features

See https://github.com/encode/starlette/milestone/1

• URL Reversing
• Cookies
• Form support
• Class based views
• Exception handling
• Middleware
• StartUp / Shutdown events
• Background tasks

Later

• Server Sent Events
• HTTP/2 (and server push)

Important

• We're using Polar.sh so you can upvote and help fund this issue.
• We receive the funding once the issue is completed & confirmed by you.
• Thank you in advance for helping prioritize & fund our backlog.

[tomchristie]

We have everything that I'd originally wanted for 1.0 support.

The only bit of API that's giving me any pause on a 1.0 jump is the async bits of requests/websockets. eg. request parsing. Ideally we'd like to eventually be able to use
fully sync views too, and still have all functionality available to us. Haven't yet figured
how that'd look for the request/websocket APIs.

[Jitsusama]

One other thing that I'd like to throw in is a request that you keep the ability for Starlette to be utilized as a library toolset. I personally dislike Flask's style of global application objects. I much prefer having my own class where I can inject dependencies and then call out your framework as needed.

BTW; I love this library/framework. Thanks so much for the hard work you've put into it!

[tomchristie]

a request that you keep the ability for Starlette to be utilized as a library toolset

Oh, absolutely! We'll want the documentation to come from a "here's how you use a Starlette app" first, and a "here's the low level stuff" second, but it's really important that Starlette remains both a framework and a toolkit.

At some point the datastructures ought to get some documentation. Also I'm planning on expanding out concurrency.py with context managers that let you use asyncio timeouts and branching in a more structured way. (ie. Take the lessons from trio, and apply the most important bits. Some of this sort of thing ought to start appearing in Python 3.8 too, but we'd probably like good support for it before that's widespread.)

[Jitsusama]

That's great to hear. I have found certain things that I've had to dig into the source to figure out. Particularly how to setup my own router instance. Also, clues to wrapping middle-ware exist, but it could be called out a bit stronger in the documentation also.

BTW; I love your tests. They have generally supplied for documentation lack, except in the case of routers which you only seem to test when coupled with an App instance.

[Jitsusama]

Scratch part of the last comment, I must've been thinking of something other than routers, but I can't think of what right now.

[sscherfke]

At some point the datastructures ought to get some documentation. Also I'm planning on expanding out concurrency.py with context managers that let you use asyncio timeouts and branching in a more structured way. (ie. Take the lessons from trio, and apply the most important bits. Some of this sort of thing ought to start appearing in Python 3.8 too, but we'd probably like good support for it before that's widespread.)

Would supporting trio (as an optional replacement for asyncio) be an option?

[tomchristie]

@sscherfke Potentially. The awkwardness is that asyncio and trio are completely incompatible, so anywhere we're using asyncio primitives is a point where we'd need to be able to intelligently switch between the two.

My personally opinion is that rather than promoting an ecosystem split, the most productive approach here is to take the design lessons from trio and apply them to asyncio.

If someone did want to try to tackle a pull request for this, the place to look would be httpx - since we're working towards supporting alternate concurrency backends there.

[sscherfke]

Yes, I know that it is not an easy task.

I like trio's design for structured concurrency, its API and that it is based on coroutines all the way down. But I also see the “problem” that asyncio has currently more users and is, at least when using uvloop, a lot faster.

[tomchristie]

I like trio's design for structured concurrency

Indeed, me too. One thing that certainly needs to happen is for Python to get a task supervisor that's similar to Trio's nurseries, and for the documentation and ecosystem to start moving users away for more gnarly lower-level primitives. (Same goes for timeouts too)

[Fuyukai]

The awkwardness is that asyncio and trio are completely incompatible

Luckily, you can support both with the anyio project. This gives you the nice trio-inspired APIs whilst working on both asyncio and trio.

[skewty]

Are there any plans to introduce a back end so web socket connections in different Starlette processes (production) can communicate with each other? This would be nice for v1.0.

[tiangolo]

@skewty I think that would belong to the "application development" side.

It would probably involve some kind of message passing system/DB. E.g. a Redis instance and connections between different processes to receive and write messages to that central DB from their own WebSocket connections with their clients.

As any system like that would be very application-dependent, having something very strictly pre-defined like that probably wouldn't fit in the framework.

[skewty]

@tiangolo #133 seems the best place to further discuss what I wrote above. What I was looking for is basically what nemja is offering. Maybe something like that can be brought into Starlette itself.

[ryanhiebert]

Module naming - should it be starlette.requests/starlette.responses instead of starlette.request/starlette.response? Would fit websockets and align better with documentation titles.

I found this issue, and see that it's asking a question I have an opinion on, and it's still pre-1.0, so maybe it'll persuade someone to see it my way ;-)

My recommendation for organizing the code would be to use singular names, and move sub-classes into separate modules that relate to the specializations rather than the base class. For example, if you have a JSONResponse, that would properly go into a module or package named json, where your base classes are specialized for various utilities handling JSON. Or you may have a package or module named websocket where specializations of various base concepts are implemented specifically for web sockets. In general, this also makes for pretty decent documentation boundaries as well.

In this system, you would rarely use a plural name, and the file names would represent, in general, separations of specializations, or unique ideas, rather than groupings of specializations for a given base type. This idea became known to me as "separation of concerns, not technologies". Here's someone describing roughly these thoughts in the context of .NET: https://www.youtube.com/watch?v=PRns0rqPonA

One benefit of this approach is that things like optional dependencies are rather straightforward. If you have some specializations that depend on an external module, those will rather naturally be in a package related to that dependency, and if that package is imported, you know that they are looking to use that dependency. Thus you can import directly, and allow the error of the missing module to surface via the normal python import error mechanism.

If you find that you don't like this suggestion, the plural name for the module strikes me as better than using the singular name for a group of specializations combined with the base class. So I'm glad you went with it.

[pikeas]

@tomchristie Love the ongoing work on starlette, what's your current timeline for cutting a 1.0 release?

[uSpike]

Hi, just wanted to mention that #1157 adds anyio integration, and also removes the old graphql app executor argument. Maybe that could be a candidate for a major version bump?

[Kludex]

SSE is implemented on this package: https://github.com/sysid/sse-starlette
Do we like to have it on starlette instead?

For HTTP/2, I guess we first want to have support on uvicorn, which will be accomplished when we close this: encode/uvicorn#47

Should we add "TestClient using httpx instead of requests" as requisite for 1.0 as well?

[tomchristie]

Do we like to have it on starlette instead?

No not really. I'm very keen that Starlette really should be absolutely as minimal as possible. Moreso than it currently is now.

For HTTP/2

HTTP/2 support isn't really a Starlette issue. Also we could perfectly well be pointing folks towards Hypercorn, which does have HTTP/2 support. I'm actually quite keen on that.

Should we add "TestClient using httpx instead of requests" as requisite for 1.0 as well?

That's pretty much my number one thing I'd like to see switched around on Starlette yeah.

[Kludex]

I guess the removal of GraphQL code should be included on the 1.0 milestone.

[Kludex]

TestClient is now using httpx i.e. there are no blocking points to move to 1.0.

I'll try to create a plan for this bump. It's a big step for us. 🙏