Add headers parameter to HTTPException

docs/exceptions.md

@@ -4,17 +4,19 @@ how you return responses when errors or handled exceptions occur.
 
 ```python
 from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
 from starlette.responses import HTMLResponse
 
 
 HTML_404_PAGE = ...
 HTML_500_PAGE = ...
 
 
-async def not_found(request, exc):
+async def not_found(request: Request, exc: HTTPException):
     return HTMLResponse(content=HTML_404_PAGE, status_code=exc.status_code)
 
-async def server_error(request, exc):
+async def server_error(request: Request, exc: HTTPException):
     return HTMLResponse(content=HTML_500_PAGE, status_code=exc.status_code)
 
 
@@ -40,14 +42,26 @@ In particular you might want to override how the built-in `HTTPException` class
 is handled. For example, to use JSON style responses:
 
 ```python
-async def http_exception(request, exc):
+async def http_exception(request: Request, exc: HTTPException):
     return JSONResponse({"detail": exc.detail}, status_code=exc.status_code)
 
 exception_handlers = {
     HTTPException: http_exception
 }
 ```
 
+The `HTTPException` is also equipped with the `headers` argument. Which allows the propagation
+of the headers to the response class:
+
+```python
+async def http_exception(request: Request, exc: HTTPException):
+    return JSONResponse(
+        {"detail": exc.detail},
+        status_code=exc.status_code,
+        headers=exc.headers
+    )
+```
+
 ## Errors and handled exceptions
 
 It is important to differentiate between handled exceptions and errors.
@@ -76,7 +90,7 @@ The `HTTPException` class provides a base class that you can use for any
 handled exceptions. The `ExceptionMiddleware` implementation defaults to
 returning plain-text HTTP responses for any `HTTPException`.
 
-* `HTTPException(status_code, detail=None)`
+* `HTTPException(status_code, detail=None, headers=None)`
 
 You should only raise `HTTPException` inside routing or endpoints. Middleware
 classes should instead just return appropriate responses directly.

starlette/exceptions.py

@@ -9,11 +9,14 @@
 
 
 class HTTPException(Exception):
-    def __init__(self, status_code: int, detail: str = None) -> None:
+    def __init__(
+        self, status_code: int, detail: str = None, headers: dict = None
+    ) -> None:
         if detail is None:
             detail = http.HTTPStatus(status_code).phrase
         self.status_code = status_code
         self.detail = detail
+        self.headers = headers
 
     def __repr__(self) -> str:
         class_name = self.__class__.__name__
@@ -99,5 +102,7 @@ async def sender(message: Message) -> None:
 
     def http_exception(self, request: Request, exc: HTTPException) -> Response:
         if exc.status_code in {204, 304}:
-            return Response(status_code=exc.status_code)
-        return PlainTextResponse(exc.detail, status_code=exc.status_code)
+            return Response(status_code=exc.status_code, headers=exc.headers)
+        return PlainTextResponse(
+            exc.detail, status_code=exc.status_code, headers=exc.headers
+        )

tests/test_exceptions.py

@@ -21,6 +21,10 @@ def not_modified(request):
     raise HTTPException(status_code=304)
 
 
+def with_headers(request):
+    raise HTTPException(status_code=200, headers={"x-potato": "always"})
+
+
 class HandledExcAfterResponse:
     async def __call__(self, scope, receive, send):
         response = PlainTextResponse("OK", status_code=200)
@@ -34,6 +38,7 @@ async def __call__(self, scope, receive, send):
         Route("/not_acceptable", endpoint=not_acceptable),
         Route("/no_content", endpoint=no_content),
         Route("/not_modified", endpoint=not_modified),
+        Route("/with_headers", endpoint=with_headers),
         Route("/handled_exc_after_response", endpoint=HandledExcAfterResponse()),
         WebSocketRoute("/runtime_error", endpoint=raise_runtime_error),
     ]
@@ -67,6 +72,12 @@ def test_not_modified(client):
     assert response.text == ""
 
 
+def test_with_headers(client):
+    response = client.get("/with_headers")
+    assert response.status_code == 200
+    assert response.headers["x-potato"] == "always"
+
+
 def test_websockets_should_raise(client):
     with pytest.raises(RuntimeError):
         with client.websocket_connect("/runtime_error"):