From a8c61d498cbff8191dae76da11e0fff7ad1a9070 Mon Sep 17 00:00:00 2001 From: chucknuris Date: Sun, 5 Jul 2026 16:23:13 +0200 Subject: [PATCH] docs(redirects): clarify headers argument on redirect exceptions The redirect exceptions accept a headers argument, but its behavior was not documented, leading to confusion over whether these headers merge with the incoming request headers or the response headers. Document the headers argument on HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPTemporaryRedirect, and HTTPPermanentRedirect, clarifying that the headers are merged into those already set on the response and are unrelated to the request headers. Closes #1920 --- docs/_newsfragments/1920.misc.rst | 6 ++++++ falcon/redirects.py | 15 +++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/_newsfragments/1920.misc.rst diff --git a/docs/_newsfragments/1920.misc.rst b/docs/_newsfragments/1920.misc.rst new file mode 100644 index 000000000..89f909d63 --- /dev/null +++ b/docs/_newsfragments/1920.misc.rst @@ -0,0 +1,6 @@ +The ``headers`` argument of the redirect exceptions +(:class:`~falcon.HTTPMovedPermanently`, :class:`~falcon.HTTPFound`, +:class:`~falcon.HTTPSeeOther`, :class:`~falcon.HTTPTemporaryRedirect`, and +:class:`~falcon.HTTPPermanentRedirect`) is now documented. The accompanying +docstrings clarify that these headers are merged into the ones already set on +the response, and are unrelated to the headers of the incoming request. diff --git a/falcon/redirects.py b/falcon/redirects.py index 75675b0fe..afdf9532b 100644 --- a/falcon/redirects.py +++ b/falcon/redirects.py @@ -41,6 +41,9 @@ class HTTPMovedPermanently(HTTPStatus): Args: location (str): URI to provide as the Location header in the response. + headers (dict): Extra headers to add to the response. These are + merged into the headers already set on the response; they + are not related to the headers of the incoming request. """ def __init__(self, location: str, headers: Headers | None = None) -> None: @@ -70,6 +73,9 @@ class HTTPFound(HTTPStatus): Args: location (str): URI to provide as the Location header in the response. + headers (dict): Extra headers to add to the response. These are + merged into the headers already set on the response; they + are not related to the headers of the incoming request. """ def __init__(self, location: str, headers: Headers | None = None) -> None: @@ -104,6 +110,9 @@ class HTTPSeeOther(HTTPStatus): Args: location (str): URI to provide as the Location header in the response. + headers (dict): Extra headers to add to the response. These are + merged into the headers already set on the response; they + are not related to the headers of the incoming request. """ def __init__(self, location: str, headers: Headers | None = None) -> None: @@ -133,6 +142,9 @@ class HTTPTemporaryRedirect(HTTPStatus): Args: location (str): URI to provide as the Location header in the response. + headers (dict): Extra headers to add to the response. These are + merged into the headers already set on the response; they + are not related to the headers of the incoming request. """ def __init__(self, location: str, headers: Headers | None = None) -> None: @@ -159,6 +171,9 @@ class HTTPPermanentRedirect(HTTPStatus): Args: location (str): URI to provide as the Location header in the response. + headers (dict): Extra headers to add to the response. These are + merged into the headers already set on the response; they + are not related to the headers of the incoming request. """ def __init__(self, location: str, headers: Headers | None = None) -> None: