✨ Re-export Starlette's `WebSocketException` and add it to docs (#5629)

diff --git a/docs/en/docs/advanced/websockets.md b/docs/en/docs/advanced/websockets.md
index 0e9bc5b06b378cd2dcefa7b0e07cbd892d9babd5..3cf840819fdcce7857c5e08764304bc05590b2d8 100644 (file)
--- a/docs/en/docs/advanced/websockets.md
+++ b/docs/en/docs/advanced/websockets.md
@@ -112,17 +112,15 @@ In WebSocket endpoints you can import from `fastapi` and use:
 
 They work the same way as for other FastAPI endpoints/*path operations*:
 
-```Python hl_lines="58-65  68-83"
+```Python hl_lines="66-77  76-91"
 {!../../../docs_src/websockets/tutorial002.py!}
 ```
 
 !!! info
-    In a WebSocket it doesn't really make sense to raise an `HTTPException`. So it's better to close the WebSocket connection directly.
+    As this is a WebSocket it doesn't really make sense to raise an `HTTPException`, instead we raise a `WebSocketException`.
 
     You can use a closing code from the <a href="https://tools.ietf.org/html/rfc6455#section-7.4.1" class="external-link" target="_blank">valid codes defined in the specification</a>.
 
-    In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the <a href="https://github.com/encode/starlette/pull/527" class="external-link" target="_blank">PR #527</a> in Starlette.
-
 ### Try the WebSockets with dependencies
 
 If your file is named `main.py`, run your application with:

diff --git a/docs_src/websockets/tutorial002.py b/docs_src/websockets/tutorial002.py
index cf5c7e805af864b98cad5a06a29cbb88edb688ee..cab749e4db7fa081ae2c623d92298b5ebaf33ec4 100644 (file)
--- a/docs_src/websockets/tutorial002.py
+++ b/docs_src/websockets/tutorial002.py
@@ -1,6 +1,14 @@
 from typing import Union
 
-from fastapi import Cookie, Depends, FastAPI, Query, WebSocket, status
+from fastapi import (
+    Cookie,
+    Depends,
+    FastAPI,
+    Query,
+    WebSocket,
+    WebSocketException,
+    status,
+)
 from fastapi.responses import HTMLResponse
 
 app = FastAPI()
@@ -61,7 +69,7 @@ async def get_cookie_or_token(
     token: Union[str, None] = Query(default=None),
 ):
     if session is None and token is None:
-        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
     return session or token
 
 

diff --git a/fastapi/__init__.py b/fastapi/__init__.py
index a5c7aeb17600efab52d0c2b5b142a66590cd95ef..70f363c89c121a665a9e359198b2883563641b48 100644 (file)
--- a/fastapi/__init__.py
+++ b/fastapi/__init__.py
@@ -8,6 +8,7 @@ from .applications import FastAPI as FastAPI
 from .background import BackgroundTasks as BackgroundTasks
 from .datastructures import UploadFile as UploadFile
 from .exceptions import HTTPException as HTTPException
+from .exceptions import WebSocketException as WebSocketException
 from .param_functions import Body as Body
 from .param_functions import Cookie as Cookie
 from .param_functions import Depends as Depends

diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py
index 0f50acc6c58d0f361c4350beb49172b60bd7f56b..ca097b1cef5f8dc697f66ee18df6c3ca6e5756de 100644 (file)
--- a/fastapi/exceptions.py
+++ b/fastapi/exceptions.py
@@ -3,6 +3,7 @@ from typing import Any, Dict, Optional, Sequence, Type
 from pydantic import BaseModel, ValidationError, create_model
 from pydantic.error_wrappers import ErrorList
 from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.exceptions import WebSocketException as WebSocketException  # noqa: F401
 
 
 class HTTPException(StarletteHTTPException):