Public API for auth flow. #731

The authlib package provides support for oauth integration with httpx - they're currently reporting a breakage with the latest versions, which isn't particularly surprising since they were having to rely on private API (eg. Middleware)... authlib/authlib#178

Really we need to make sure that we introduce sufficient public API for them to be able to implement against.

Our public Auth API currently accepts...

• A two-tuple of username/password.
• Either httpx.BasicAuth or httpx.DigestAuth.
• A callable taking a request, and returning a response.

In order to support their use-case we should also make the custom auth class into public API for the 0.11 release, so that we're also officially supporting:

• A subclass of httpx.Auth.

Also, our auth class is now sans-IO, so that it can support both the Client and the AsyncClient cases. However, some kinds of auth need to be able to sign the request body, so we need some API in order to support that.

I'd suggest the following API for custom auth classes:

• Subclass httpx.Auth.
• Implement def auth_flow(request: Request) -> typing.Generator[Request, Response, None]. (We're currently using __call__, but I think we may as well us a named method instead
• Optionally include .requires_request_body = True. (If specified then the client should read the request body, making it available as request.content. The client should error if the request body is not replayable.)

We'll also need to implement .content and .read()/.aread() on request instances.