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

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:

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
 
 

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

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):