Revisiting custom authentication.

Originally opened by @tomchristie on 2024-10-30 16:35:39 in encode/httpx

Let's have a go at simplifying our authentication API.

We have an existing API using generators and an "auth_flow", which could be simplified.
The following base API would be sufficient for almost all authentication use-cases...

class Auth:
    def authenticate_request(request: Request) -> Request:
        # Most authentication schemes only need to override this method.
        return request 

    def authenticate_response(response: Response) -> Request | None:
        # Challenge-response authentication schemes may override this method,
        # Allows a second request to optionally be made, once a server challenge is received.
        return None

It's feasible that there are might(???) be some exceptional cases where this might not be sufficient, but we have a "Transport API" that allows completely customising the entire request/response implementation. That'd be adequate for anyone needing to implement an oddball multi-stage authentication scheme.

Moderately involved, tho likely still suitable for a new contributor to deal with.

Checklist...

• Update the base Auth class as above.
• Update the BasicAuth, DigestAuth and NetRCAuth classes to use the new API.
• Update the auth handling in _client.py.
• Update the documentation.
• Update tests as required.

Simplicity ftw.

Start with the base Auth class and the authentication handling in _client.py, then inspect BasicAuth, DigestAuth, and NetRCAuth. Update the documentation and relevant tests alongside the API changes. Done means these authentication classes use the simplified API and the test suite confirms the expected request and response behavior.