Implement #1299: Accept header parsing and content negotiation

[NomAnor]

First iteration to implement Accept header parsing and content negotioation. Documentation is missing until the code is stable.

Things to discuss/check

• I'm not sure where to put the helper types, Accept might reside in request.py, the other I don't know.
• Should MediaType be exposed or only used internally?
• Are the tests appropiate?
• Is the ordering correct based on RFC 2616?

MediaType class

Exposing the results as str is obviously easier. But when paramters are involved it gets more complicated:

Accept("text/plain,text/plain;p=test").best_match(["text/plain", "text/html"]) == "text/plain;p=test"

In a handler you would do:

preferred_type = request.accept.best_mach(["text/plain", "text/html"])
if preferred_type == "text/plain":
   return text_response

which would not match because of the missing parameter.

Implementing parameters might just be too cumbersome and so rarely used that it might be best to ignore them, except for q and for specificity. Or my logic could be better and the method should only return elements from provided_types.

PR Checklist

• Have you followed the guidelines in CONTRIBUTING.rst?
• Have you got 100% test coverage on new code?
• Have you updated the prose documentation?
• Have you updated the reference documentation?

[provinzkraut]

which would not match because of the missing parameter.

IMO this can be simplified. best_match should always only return one of the types passed in. If you pass in text/plain;p=test, you may handle that case and get back a text/plain;p=test, but if you pass in text/plain, all you should get back is text/plain;p=test, regardless of the header value.

[provinzkraut]

I'm not sure where to put the helper types, ``Accept` might reside in request.py, the other I don't know.

datastructures. We have an ETag header in headers.py there as well for example.

[NomAnor]

Should the Accept class inherit from Header and become a pydantic model?
It looks like those classes (ETag, CacheControlHeader) are only used for responses.

[provinzkraut]

Should the Accept class inherit from Header and become a pydantic model?

Hm. I think we're running into a bit of an issue here. Conceptually, they should have the same base class. But as you pointed out, Header is currently only used for response headers. It should be usable for request headers as well. On the other hand, we don't really want to introduce pydantic models unnecessarily, as we're currently trying to move away from those and towards dataclasses.

On the other hand, there's no reason you can't just implement an Accept class that doesn't inherit from any of those. I think this might be the way to go here for now.

[NomAnor]

I moved the code to the dataclasses directory. I also changed it so the interface uses str and only internally the _MediaType class.
I added a small initial paragraph for content negotiation to the response documentation,but it needs a bit more polish.

[NomAnor]

I cleaned everything up, it should be ready for a final review.

I could not get sphinx to reference the accept property. Does anyone know why :attr:`Request.accept <starlite.connection.request.Request.accept>` does not work?

[provinzkraut]

I cleaned everything up, it should be ready for a final review.

I could not get sphinx to reference the accept property. Does anyone know why :attr:`Request.accept <starlite.connection.request.Request.accept>` does not work?

:attr:`Request.accept <starlite.connection.Request.accept>` or
:attr:`Request.accept <.connection.Request.accept>` should work.

The references don't work by their absolute path, but rather by how they're set up with autodoc. Since we don't expose this internal module structure to the user, we documented it accordingly, so as far as autodoc is concerned, starlite.connection.Request is the absolute path and starlite.connection.request does not exist.