Skip to content

refactor exceptions - #3333

Merged
davidism merged 1 commit into
mainfrom
exception-response
Oct 17, 2026
Merged

davidism merged 1 commit into
mainfrom
exception-response

Conversation

@davidism

@davidism davidism commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

Mainly, deprecate the various builder methods on HTTPException and the envrion and scope arguments. Then, cleaned up all the descriptions and docs.

  • HTTPException.get_description, get_body, and get_headers are deprecated. Passing description or overriding get_response covers anything that's needed, a lot more simply.
  • The environ and scope arguments to those methods are deprecated. They weren't used anywhere, including in frameworks that could have passed them.
  • name can be set as a class attribute, or is pulled from HTTPStatus.phrase if not set.
  • code and description can't be none, simplifying type checking. They default to 0 and empty, but will be filled in by all concrete exceptions.
  • __doc__ is automatically prefixed with {code} {name}, description, and a link to MDN, if it's not already prefixed. This allows adding additional :param or ..versionchanged items, without repeating the definitions in the doc.
  • get_response creates a response object and sets content_type. Subclasses override it, call super, then add additional headers using the header properties, rather than constructing the low-level list of tuples.
  • All the descriptions are rewritten using a consistent style. I paraphrased MDN or RFC 9110, and kept it two one sentence. These messages will mainly be seen by users who can't do anything about them, so they should be simple and non-technical.
  • All the docs are simplified and rewritten using a consistent style.
  • Updated the tests.

part of #3281

@davidism davidism added this to the 3.2.0 milestone Oct 17, 2026
@davidism

Copy link
Copy Markdown
Member Author

Noticed that a few of the exception class names don't match the status phrase listed in RFC 9110, MDN, and HTTPStatus. I considered renaming, but decided to leave it. They're uncommon (mostly used by frameworks), most users probably use abort and don't see the class name, and there's no guarantee they won't change again.

class phrase
RequestEntityTooLarge Content Too Large
RequestURITooLarge URI Too Long
RequestedRangeNotSatisfiable Range Not Satisfiable
UnprocessableEntity Unprocessable Content

There's a few that are from WebDAV too. There's no reason we should have these, but I'll just leave them for now.

  • 423 Locked
  • 424 Failed Dependency

@davidism
davidism merged commit 665e760 into main Oct 17, 2026
12 checks passed
@davidism
davidism deleted the exception-response branch October 17, 2026 03:47
@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Nov 1, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant