for `werkzeug.exceptions.HTTPException.get_response`, type signature and documentation disagree

[glyph]

from werkzeug.exceptions import HTTPException

e: HTTPException
reveal_type(e.get_response())

src/t.py:4:13: note: Revealed type is "werkzeug.sansio.response.Response"
Success: no issues found in 1 source file

This is surprising because the type import of "Response" and the reference to "Response" seem to be indicating the sansio Response, however, I think that Sphinx is resolving the name reference in some global namespace that gets clobbered, which then results in the actual rendered documentation referring to werkzeug.wrappers.Response.

The actual implementation does return a werkzeug.wrappers.Response and we have code in Klein that expects this to be the case, so I think that this was perhaps a case of jumbled intent?

In any case these should be made to agree.

Environment:

• Python version: 3.13.5
• Werkzeug version: 3.1.3 / 504a8c4

[davidism]

This is one of those places where it's very hard to shoehorn in ASGI stuff where it was authored for WSGI only, while still making type checkers happy internally and externally. For WSGI applications, this should return werkzeug.response.Response, for ASGI this should return sansio.Response. Quart relies on that, so it needs the broader annotation so that its own type checking doesn't fail. There's no way to tell the type system "this is a WSGI application", so the annotation ends up being less accurate. I don't see a way to change this, but if you have a suggestion I'd be happy to review it.

[glyph]

This is one of those places where it's very hard to shoehorn in ASGI stuff where it was authored for WSGI only, while still making type checkers happy internally and externally. For WSGI applications, this should return werkzeug.response.Response, for ASGI this should return sansio.Response. Quart relies on that, so it needs the broader annotation so that its own type checking doesn't fail. There's no way to tell the type system "this is a WSGI application", so the annotation ends up being less accurate. I don't see a way to change this, but if you have a suggestion I'd be happy to review it.

First, a simple fix would be that, if this is the case, then sure, just make the documentation say it. Right now it points at the wrong class, apparently by accident. If client code needs to do an isinstance check that's fine.

Second, if you want to get more sophisticated, If you make the attribute read-only, you could make SynchronousHTTPException a subclass of HTTPException that repurposes the attribute to be a werkzeug.wrappers.response.Response, and then WSGI applications could just catch SynchronousHTTPException, secure in the knowledge that they're not ASGI and thus will never see that exception type raised.

[glyph]

For a spooky, third option, you could use typing.Generics to tell which kind of application you're talking to but I suspect that would involve a huge and annoying cascade of TypeVars across a few hundred call sites, all to communicate this not-that-interesting detail