📝 Update all docs to use Annotated as the main recommendation, with new examples and tests (#9268)

* 🍱 Add new source examples with Annotated for Query Params and String Validations * 📝 Add new docs with Annotated for Query Params and String Validations * 🚚 Rename incorrectly named tests for Query Params and str validations * ✅ Add new tests with Annotated for Query Params and Sring Validations examples * 🍱 Add new examples with Annotated for Intro to Python Types * 📝 Update Python Types Intro, include Annotated * 🎨 Fix formatting in Query params and string validation, and highlight * 🍱 Add new Annotated source examples for Path Params and Numeric Validations * 📝 Update docs for Path Params and Numeric Validations with Annotated * 🍱 Add new source examples with Annotated for Body - Multiple Params * 📝 Update docs with Annotated for Body - Multiple Parameters * ✅ Add test for new Annotated examples in Body - Multiple Parameters * 🍱 Add new Annotated source examples for Body Fields * 📝 Update docs for Body Fields with new Annotated examples * ✅ Add new tests for new Annotated examples for Body Fields * 🍱 Add new Annotated source examples for Schema Extra (Example Data) * 📝 Update docs for Schema Extra with Annotated * ✅ Add tests for new Annotated examples for Schema Extra * 🍱 Add new Annnotated source examples for Extra Data Types * 📝 Update docs with Annotated for Extra Data Types * ✅ Add tests for new Annotated examples for Extra Data Types * 🍱 Add new Annotated source examples for Cookie Parameters * 📝 Update docs for Cookie Parameters with Annotated examples * ✅ Add tests for new Annotated source examples in Cookie Parameters * 🍱 Add new Annotated examples for Header Params * 📝 Update docs with Annotated examples for Header Parameters * ✅ Add tests for new Annotated examples for Header Params * 🍱 Add new Annotated examples for Form Data * 📝 Update Annotated docs for Form Data * ✅ Add tests for new Annotated examples in Form Data * 🍱 Add new Annotated source examples for Request Files * 📝 Update Annotated docs for Request Files * ✅ Test new Annotated examples for Request Files * 🍱 Add new Annotated source examples for Request Forms and Files * ✅ Add tests for new Anotated examples for Request Forms and Files * 🍱 Add new Annotated source examples for Dependencies and Advanced Dependencies * ✅ Add tests for new Annotated dependencies * 📝 Add new docs for using Annotated with dependencies including type aliases * 📝 Update docs for Classes as Dependencies with Annotated * 📝 Update docs for Sub-dependencies with Annotated * 📝 Update docs for Dependencies in path operation decorators with Annotated * 📝 Update docs for Global Dependencies with Annotated * 📝 Update docs for Dependencies with yield with Annotated * 🎨 Update format in example for dependencies with Annotated * 🍱 Add source examples with Annotated for Security * ✅ Add tests for new Annotated examples for security * 📝 Update docs for Security - First Steps with Annotated * 📝 Update docs for Security: Get Current User with Annotated * 📝 Update docs for Simple OAuth2 with Password and Bearer with Annotated * 📝 Update docs for OAuth2 with Password (and hashing), Bearer with JWT tokens with Annotated * 📝 Update docs for Request Forms and Files with Annotated * 🍱 Add new source examples for Bigger Applications with Annotated * ✅ Add new tests for Bigger Applications with Annotated * 📝 Update docs for Bigger Applications - Multiple Files with Annotated * 🍱 Add source examples for background tasks with Annotated * 📝 Update docs for Background Tasks with Annotated * ✅ Add test for Background Tasks with Anotated * 🍱 Add new source examples for docs for Testing with Annotated * 📝 Update docs for Testing with Annotated * ✅ Add tests for Annotated examples for Testing * 🍱 Add new source examples for Additional Status Codes with Annotated * ✅ Add tests for new Annotated examples for Additional Status Codes * 📝 Update docs for Additional Status Codes with Annotated * 📝 Update docs for Advanced Dependencies with Annotated * 📝 Update docs for OAuth2 scopes with Annotated * 📝 Update docs for HTTP Basic Auth with Annotated * 🍱 Add source examples with Annotated for WebSockets * ✅ Add tests for new Annotated examples for WebSockets * 📝 Update docs for WebSockets with new Annotated examples * 🍱 Add source examples with Annotated for Settings and Environment Variables * 📝 Update docs for Settings and Environment Variables with Annotated * 🍱 Add new source examples for testing dependencies with Annotated * ✅ Add tests for new examples for testing dependencies * 📝 Update docs for testing dependencies with new Annotated examples * ✅ Update and fix marker for Python 3.9 test * 🔧 Update Ruff ignores for source examples in docs * ✅ Fix some tests in the grid for Python 3.9 (incorrectly testing 3.10) * 🔥 Remove source examples and tests for (non existent) docs section about Annotated, as it's covered in all the rest of the docs
2026-10-26 11:49:56 -04:00 · 2023-03-18 13:29:59 +01:00
1 parent f63b3ad53e
commit 9eaed2eb37
@@ -0,0 +1,93 @@
+from typing import Union
+
+from fastapi import (
+    Cookie,
+    Depends,
+    FastAPI,
+    Query,
+    WebSocket,
+    WebSocketException,
+    status,
+)
+from fastapi.responses import HTMLResponse
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
+            <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
+            <button onclick="connect(event)">Connect</button>
+            <hr>
+            <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+        var ws = null;
+            function connect(event) {
+                var itemId = document.getElementById("itemId")
+                var token = document.getElementById("token")
+                ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
+                ws.onmessage = function(event) {
+                    var messages = document.getElementById('messages')
+                    var message = document.createElement('li')
+                    var content = document.createTextNode(event.data)
+                    message.appendChild(content)
+                    messages.appendChild(message)
+                };
+                event.preventDefault()
+            }
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+async def get_cookie_or_token(
+    websocket: WebSocket,
+    session: Annotated[Union[str, None], Cookie()] = None,
+    token: Annotated[Union[str, None], Query()] = None,
+):
+    if session is None and token is None:
+        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
+    return session or token
+
+
+@app.websocket("/items/{item_id}/ws")
+async def websocket_endpoint(
+    *,
+    websocket: WebSocket,
+    item_id: str,
+    q: Union[int, None] = None,
+    cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
+):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(
+            f"Session cookie or query token value is: {cookie_or_token}"
+        )
+        if q is not None:
+            await websocket.send_text(f"Query parameter q is: {q}")
+        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
@@ -0,0 +1,92 @@
+from typing import Annotated
+
+from fastapi import (
+    Cookie,
+    Depends,
+    FastAPI,
+    Query,
+    WebSocket,
+    WebSocketException,
+    status,
+)
+from fastapi.responses import HTMLResponse
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
+            <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
+            <button onclick="connect(event)">Connect</button>
+            <hr>
+            <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+        var ws = null;
+            function connect(event) {
+                var itemId = document.getElementById("itemId")
+                var token = document.getElementById("token")
+                ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
+                ws.onmessage = function(event) {
+                    var messages = document.getElementById('messages')
+                    var message = document.createElement('li')
+                    var content = document.createTextNode(event.data)
+                    message.appendChild(content)
+                    messages.appendChild(message)
+                };
+                event.preventDefault()
+            }
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+async def get_cookie_or_token(
+    websocket: WebSocket,
+    session: Annotated[str | None, Cookie()] = None,
+    token: Annotated[str | None, Query()] = None,
+):
+    if session is None and token is None:
+        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
+    return session or token
+
+
+@app.websocket("/items/{item_id}/ws")
+async def websocket_endpoint(
+    *,
+    websocket: WebSocket,
+    item_id: str,
+    q: int | None = None,
+    cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
+):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(
+            f"Session cookie or query token value is: {cookie_or_token}"
+        )
+        if q is not None:
+            await websocket.send_text(f"Query parameter q is: {q}")
+        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
@@ -0,0 +1,92 @@
+from typing import Annotated, Union
+
+from fastapi import (
+    Cookie,
+    Depends,
+    FastAPI,
+    Query,
+    WebSocket,
+    WebSocketException,
+    status,
+)
+from fastapi.responses import HTMLResponse
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
+            <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
+            <button onclick="connect(event)">Connect</button>
+            <hr>
+            <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+        var ws = null;
+            function connect(event) {
+                var itemId = document.getElementById("itemId")
+                var token = document.getElementById("token")
+                ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
+                ws.onmessage = function(event) {
+                    var messages = document.getElementById('messages')
+                    var message = document.createElement('li')
+                    var content = document.createTextNode(event.data)
+                    message.appendChild(content)
+                    messages.appendChild(message)
+                };
+                event.preventDefault()
+            }
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+async def get_cookie_or_token(
+    websocket: WebSocket,
+    session: Annotated[Union[str, None], Cookie()] = None,
+    token: Annotated[Union[str, None], Query()] = None,
+):
+    if session is None and token is None:
+        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
+    return session or token
+
+
+@app.websocket("/items/{item_id}/ws")
+async def websocket_endpoint(
+    *,
+    websocket: WebSocket,
+    item_id: str,
+    q: Union[int, None] = None,
+    cookie_or_token: Annotated[str, Depends(get_cookie_or_token)],
+):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(
+            f"Session cookie or query token value is: {cookie_or_token}"
+        )
+        if q is not None:
+            await websocket.send_text(f"Query parameter q is: {q}")
+        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
@@ -0,0 +1,89 @@
+from fastapi import (
+    Cookie,
+    Depends,
+    FastAPI,
+    Query,
+    WebSocket,
+    WebSocketException,
+    status,
+)
+from fastapi.responses import HTMLResponse
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <label>Item ID: <input type="text" id="itemId" autocomplete="off" value="foo"/></label>
+            <label>Token: <input type="text" id="token" autocomplete="off" value="some-key-token"/></label>
+            <button onclick="connect(event)">Connect</button>
+            <hr>
+            <label>Message: <input type="text" id="messageText" autocomplete="off"/></label>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+        var ws = null;
+            function connect(event) {
+                var itemId = document.getElementById("itemId")
+                var token = document.getElementById("token")
+                ws = new WebSocket("ws://localhost:8000/items/" + itemId.value + "/ws?token=" + token.value);
+                ws.onmessage = function(event) {
+                    var messages = document.getElementById('messages')
+                    var message = document.createElement('li')
+                    var content = document.createTextNode(event.data)
+                    message.appendChild(content)
+                    messages.appendChild(message)
+                };
+                event.preventDefault()
+            }
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+async def get_cookie_or_token(
+    websocket: WebSocket,
+    session: str | None = Cookie(default=None),
+    token: str | None = Query(default=None),
+):
+    if session is None and token is None:
+        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
+    return session or token
+
+
+@app.websocket("/items/{item_id}/ws")
+async def websocket_endpoint(
+    websocket: WebSocket,
+    item_id: str,
+    q: int | None = None,
+    cookie_or_token: str = Depends(get_cookie_or_token),
+):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(
+            f"Session cookie or query token value is: {cookie_or_token}"
+        )
+        if q is not None:
+            await websocket.send_text(f"Query parameter q is: {q}")
+        await websocket.send_text(f"Message text was: {data}, for item ID: {item_id}")
@@ -0,0 +1,81 @@
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <h2>Your ID: <span id="ws-id"></span></h2>
+        <form action="" onsubmit="sendMessage(event)">
+            <input type="text" id="messageText" autocomplete="off"/>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+            var client_id = Date.now()
+            document.querySelector("#ws-id").textContent = client_id;
+            var ws = new WebSocket(`ws://localhost:8000/ws/${client_id}`);
+            ws.onmessage = function(event) {
+                var messages = document.getElementById('messages')
+                var message = document.createElement('li')
+                var content = document.createTextNode(event.data)
+                message.appendChild(content)
+                messages.appendChild(message)
+            };
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)
+
+    async def send_personal_message(self, message: str, websocket: WebSocket):
+        await websocket.send_text(message)
+
+    async def broadcast(self, message: str):
+        for connection in self.active_connections:
+            await connection.send_text(message)
+
+
+manager = ConnectionManager()
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+@app.websocket("/ws/{client_id}")
+async def websocket_endpoint(websocket: WebSocket, client_id: int):
+    await manager.connect(websocket)
+    try:
+        while True:
+            data = await websocket.receive_text()
+            await manager.send_personal_message(f"You wrote: {data}", websocket)
+            await manager.broadcast(f"Client #{client_id} says: {data}")
+    except WebSocketDisconnect:
+        manager.disconnect(websocket)
+        await manager.broadcast(f"Client #{client_id} left the chat")