Opened 5 months ago

Closed 5 months ago

#33683 closed Cleanup/optimization (fixed)

Document HttpResponseBase and allow import from django.http

Reported by: Collin Anderson Owned by: nobody
Component: HTTP handling Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (7)

comment:1 Changed 5 months ago by Collin Anderson

Has patch: set

comment:2 Changed 5 months ago by Carlton Gibson

Triage Stage: UnreviewedAccepted

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? 🤔)

comment:3 Changed 5 months ago by 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.

comment:4 Changed 5 months ago by 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.

comment:5 Changed 5 months ago by 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.

comment:6 Changed 5 months ago by Carlton Gibson

Triage Stage: AcceptedReady for checkin

comment:7 Changed 5 months ago by Carlton Gibson <carlton@…>

Resolution: fixed
Status: newclosed

In 2a5d2ee:

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

Note: See TracTickets for help on using tickets.
Back to Top