Version 1.0.0

[Kludex]

• Closes Version 1.0 #51

Description

This PR bumps Starlette to 1.0.0. 🎉

Changes

• Bump Starlette to 1.0.0.
• Add deprecation policy (docs/deprecation.md).
• Remove all code that was marked as deprecated.
• Deprecate BaseHTTPMiddleware.
• Deprecate decorator functions in the Router method, which were discouraged for some time.

Note
UPDATE [05/10/22]: PRs created according to comments on this PR:

• Deprecate BaseHTTPMiddleware #1898
• Deprecate Starlette and Router decorators #1897

Blockers

A blocker is PR or idea that can potentially make us jump to 2.0.0 too fast. If you see one around, please comment.

• Decision on UploadFile PRs:
  • Feature: Add size attribute to UploadFile #1405
  • Make the file argument to UploadFile required #1413
• Decision on Request.url_for or related PRs:
  • Change url_for signature to return a URL instance #1385
  • allow 'name' in key word arguments of url_for() and url_path_for() (#608) #611
  • Make the URL.include_query_params() to support multiple query string parameters with the same name #1738 - No need to be included.
  • Let Request.url_for lookup routes in mounted app first #1416 - No need to be included.
• Important: check if Validating host header #1858 is really an issue. - No need to be included.

Note
UPDATE [22/10/22]: We need to fix the python-multpart issues.

• Issue with MultiPartParser class #1059

Missing

• Deprecate decorators on Starlette - I've only deprecated on Router until now.

Note
UPDATE [05/10/22]: Based on the comments on this PR, there's an agreement that Starlette 1.0 will not have deprecation warnings. We shall remove all deprecated code before that.

Questions

1. Should we remove the code around the lifespan warnings? Is that part of the code supposed to be removed?
2. Should we remove the allow_redirects deprecation? It was recently added.
   • Yes. It's been months already.
3. Should we think about release cycle?
   • We are going to support only the latest version.

How to review this PR?

1. Check warnings.warn in code.
2. Read the Deprecation Policy section using ./scripts/docs serve.
3. Try hyperlinks used in the code, and release notes.

[alex-oleshkevich]

This is good news! Here are my thoughts about deprecation.

As Starlette goes 1.0 then it is a good time to drop all deprecated stuff and apply breaking changes. If this is too risky at this moment, then I would advise rolling out a few more 0.xx releases with deprecation warnings and then release 1.0 by the end of the year.

[alex-oleshkevich]

We may want to get back to #1803

[tiangolo]

Awesome! Exciting! I just have a couple of minor comments.

[tiangolo]

Another thing to have in mind that might be worth deprecating and can create some strange behaviors/issues now: app.add_middleware would create multiple instances of any previous middlewares as described here: #1161

There are not many cases where this is a problem, but it is in some, for example when dealing with Prometheus, that expects that an object is created and registered only once.

---

I was chatting with @Kludex and he pointed me to that discussion, so, mentioning it here as well.

[Kludex]

I also agree on what @alex-oleshkevich (if I got what you said right) and @tiangolo said about the deprecation.

The plan changes a bit then, we should include the deprecation warnings on the next release (0.22.0).

Then, on this PR, we remove all the deprecation warnings - Let's not have any pendency on our stable release. Conceptually, it makes more sense to do this.

[tiangolo]

Last night I remembered a couple of extra things I had pending and probably worth discussing here.

Closing UploadFile

When enabling tests for Python 3.11 in FastAPI, I'm getting errors about UploadFile not being closed. It seems Python 3.10 and below don't complain about that. But it would make sense that it would expect those files to be closed.

It seems those errors don't show up in Starlette's tests for Python 3.11, but maybe it's just because that code path is currently not tested, not sure.

The other thing is, it might be the decision in Starlette that users/developers are responsible for closing those UploadFile objects or something, in that case, I should just handle that in FastAPI, but I wanted to mention it here in case it's something that should be fixed.

I know this should be a proper issue/example. But I thought it was worth at least mentioning it here before the changes and releases are fixed.

Routers supporting empty trailing slash

What I refer with this is that there could be a router that handles all the routes under some prefix, for example: https://github.com/encode, and it would also handle https://github.com/encode/starlette and https://github.com/encode/uvicorn. But the same router handles https://github.com/encode without requiring it to end in a trailing slash. BTW, these GitHub URLs work like that.

Currently, Starlette doesn't internally support that, at least not in the same router.

FastAPI has supported that in a strange way, because in FastAPI, when using app.include_router(), currently it just copies all the paths, and in the end, it's just a single global router with everything, in FastAPI routers are currently not really "mounted" as in Starlette. So, if a router has a route with a path of "", (instead of "/"), that would handle that top level route without the trailing slash.

Now, I've wanted to refactor that in FastAPI, so that routes are not copied but routers are actually mounted (or something similar). This will allow some things on the FastAPI side. But one of the blockers I found was that I couldn't use the standard Starlette Routers and Mounts because that would not support prefixes without a trailing slash.

I need to support that and a couple of other things in FastAPI.

I'm totally fine if the decision is to not support that in Starlette, but I thought it was worth mentioning that here too, in case it seems it's something that would make sense to support.

[adriangb]

Routers supporting empty trailing slash

Thank you for bringing that up Sebastián. I've wanted to fix that for a while (I wrote the implementation at one point) but it required some minor breaking changes (I think it had to do with what errors are raised). If we want to make the change I'm happy to make the PR.

[adriangb]

With respect to UploadFile: can you add the .close() to the AsyncExitStack for dependencies? It works in Xpresso: https://github.com/adriangb/xpresso/blob/ae1586513b8ee48bfe9a8fdb2e7cc7038c37053d/xpresso/binders/_binders/file_body.py#L76

[Kludex]

Another thing to have in mind that might be worth deprecating and can create some strange behaviors/issues now: app.add_middleware would create multiple instances of any previous middlewares as described here: #1161

There are not many cases where this is a problem, but it is in some, for example when dealing with Prometheus, that expects that an object is created and registered only once.

I was chatting with @Kludex and he pointed me to that discussion, so, mentioning it here as well.

app.add_middleware doesn't have any issues since 0.24.0 thanks to @adriangb. 🙏

[adriangb]

Let’s add #2068

[Kludex]

I'm going to review both (which I also invite others to review):

• Reuse Request's body buffer for call_next in BaseHTTPMiddleware #1692
• Move exception handling logic to Route #2026

After a decision is made there, let's release the last zero version release, then wait some weeks, and then prepare for 1.0 with:

• Remove on_startup, on_shutdown, event system and deprecated lifespans #2068
• Version 1.0.0 #1888

Comments, feedback, or anything that you want to include before 1.0, please feel free to talk cc @encode/maintainers

[BrettMoan]

I'm just here to write a thank you to all the people here supporting starlette and fastapi and other related repos. And congratulate you on a massive undertaking (an official release you are feeling prod and confident of)

Often open source is thankless and while I may be a random person on the internet you don't know, know I'm a person out there like you, typing away as part of a living supporting my family via a career in programming. Using starlette and fastapi has had helped me tremendously at my job as a backend developer. It has been a joy to work with.

(this includes pydantic as well where theres also a decent amount of contributor overlap)

Thank you. Really. My job wouldn't be nearly as sane without all the of the great work y'all have already done, both in implementation and documentation.

[Kludex]

@BrettMoan Thank you for saying it. Much appreciated! ❤️

[Kludex]

Let's go to #2384.

I've cleaned the branch. There were too many conflicts, I thought it would be easier to create a new one.