Document HttpResponseBase and allow import from django.http

[Collin Anderson]

HttpResponseBase shouldn't be used directly for creating responses, but it's super useful for type-checking, so I think we should document and allow import from django.http.

[Collin Anderson]

​https://github.com/django/django/pull/15667

[Carlton Gibson]

Hey Collin.

Question: rather than exposing the base class, should we not be defining a protocol here, that you'd then use for type annotations? (Does Python typing allow... erm... retrofitting — that's probably not the word — protocol conformance? 🤔)

[Collin Anderson]

I don't really know what you mean by "protocol". Could you explain more or give an example of another "protocol"?

My use case is I have a view that wraps django.views.static.serve, which returns HttpResponseBase according to django-stubs ​https://github.com/typeddjango/django-stubs/blob/master/django-stubs/views/static.pyi#L8.

So my view that wraps serve needs also needs to be annotated as returning HttpResponseBase, so it would nice if HttpResponseBase was part of the official api, rather than being undocumented.

[Carlton Gibson]

Hey Colin.

There's a PEP here: ​PEP 544 – Protocols: Structural Subtyping (Static Duck Typing)

The idea roughly being that you declare a protocol, which any class can conform to, and use that in your annotations, rather than requiring a specific subclass, since folks are used to passing any kind of object that responds appropriately.

Does Python typing allow... erm... retrofitting — that's probably not the word — protocol conformance? 🤔

Reading from the PEP, on ​Explicitly declaring implementation:

Static analysis tools are expected to automatically detect that a class implements a given protocol. So while it’s possible to subclass a protocol explicitly, it’s not necessary to do so for the sake of type-checking.

So... testing needed but... one would hope that a suitable Protocol definition would satisfy the type-checkers, without needing changes everywhere in the existing code.
With runtime_checkable() it looks like that's usable with isinstance() too which might help avoid issues like #33362.

None of this is necessary here — more just thinking how we move forward: documenting HttpResponseBase is fine I think.
Thanks.

[Collin Anderson]

Ahh, I think. see what you're saying now. Though yeah I think it's ultimately up to the stubs projects to figure out what sort of type framework to use (protocol vs implementation, etc), unless we do actually want type annotations in Django. But maybe there's a chance documenting HttpResponseBase pushes the type-checking ecosystem in a direction we don't necessarily want to go, so I could see holding off on documenting it.

[Carlton Gibson <carlton@…>]

In 2a5d2ee:

Fixed #33683 -- Document HttpResponseBase and allow import from django.http