From: Amin Alaee <mohammadamin.alaee@gmail.com>
Date: Tue, 4 Jan 2022 08:54:22 +0000 (+0100)
Subject: Add WebSocketRoute docs in Routing (#1388)
X-Git-Tag: 0.18.0~20
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bff81f83d07dcf3f0fd3bda6a079747d74bb8d26;p=thirdparty%2Fstarlette.git

Add WebSocketRoute docs in Routing (#1388)
---

diff --git a/docs/routing.md b/docs/routing.md
index f19c57b7..f0b672d8 100644
--- a/docs/routing.md
+++ b/docs/routing.md
@@ -1,3 +1,5 @@
+## HTTP Routing
+
 Starlette has a simple but capable request routing system. A routing table
 is defined as a list of routes, and passed when instantiating the application.
 
@@ -26,8 +28,7 @@ The `endpoint` argument can be one of:
 
 * A regular function or async function, which accepts a single `request`
 argument and which should return a response.
-* A class that implements the ASGI interface, such as Starlette's [class based
-views](endpoints.md).
+* A class that implements the ASGI interface, such as Starlette's [HTTPEndpoint](endpoints.md#httpendpoint).
 
 ## Path Parameters
 
@@ -262,3 +263,42 @@ app = Router(routes=[
     ])
 ])
 ```
+
+## WebSocket Routing
+
+When working with WebSocket endpoints, you should use `WebSocketRoute`
+instead of the usual `Route`.
+
+Path parameters, and reverse URL lookups for `WebSocketRoute` work the the same
+as HTTP `Route`, which can be found in the HTTP [Route](#http-routing) section above.
+
+```python
+from starlette.applications import Starlette
+from starlette.routing import WebSocketRoute
+
+
+async def websocket_index(websocket):
+    await websocket.accept()
+    await websocket.send_text("Hello, websocket!")
+    await websocket.close()
+
+
+async def websocket_user(websocket):
+    name = websocket.path_params["name"]
+    await websocket.accept()
+    await websocket.send_text(f"Hello, {name}")
+    await websocket.close()
+
+
+routes = [
+    WebSocketRoute("/", endpoint=websocket_index),
+    WebSocketRoute("/{name}", endpoint=websocket_user),
+]
+
+app = Starlette(routes=routes)
+```
+
+The `endpoint` argument can be one of:
+
+* An async function, which accepts a single `websocket` argument.
+* A class that implements the ASGI interface, such as Starlette's [WebSocketEndpoint](endpoints.md#websocketendpoint).