לדלג לתוכן

WebSockets

When defining WebSockets, you normally declare a parameter of type WebSocket and with it you can read data from the client and send data to it.

It is provided directly by Starlette, but you can import it from fastapi:

from fastapi import WebSocket

Tip

When you want to define dependencies that should be compatible with both HTTP and WebSockets, you can define a parameter that takes an HTTPConnection instead of a Request or a WebSocket.

fastapi.WebSocket 

WebSocket(<span data-autorefs-optional="fastapi.WebSocket(scope)">scope</span>, <span data-autorefs-optional="fastapi.WebSocket(receive)">receive</span>, <span data-autorefs-optional="fastapi.WebSocket(send)">send</span>)

Bases: HTTPConnection

PARAMETER DESCRIPTION
scope

TYPE: Scope

receive

TYPE: Receive

send

TYPE: Send

Source code in starlette/websockets.py 
24
25
26
27
28
29
30
def __init__(self, scope: Scope, receive: Receive, send: Send) -> None:
    super().__init__(scope)
    assert scope["type"] == "websocket"
    self._receive = receive
    self._send = send
    self.client_state = WebSocketState.CONNECTING
    self.application_state = WebSocketState.CONNECTING

scope instance-attribute 

scope = scope

app property 

app

url property 

url

base_url property 

base_url

headers property 

headers

query_params property 

query_params

path_params property 

path_params

cookies property 

cookies

client property 

client

state property 

state

client_state instance-attribute 

client_state = CONNECTING

application_state instance-attribute 

application_state = CONNECTING

url_for 

url_for(<span data-autorefs-optional="fastapi.WebSocket.url_for(name)">name</span>, /, <span data-autorefs-optional="fastapi.WebSocket.url_for(**path_params)">**path_params</span>)
PARAMETER DESCRIPTION
name

TYPE: str

**path_params

TYPE: Any DEFAULT: {}

Source code in starlette/requests.py 
185
186
187
188
def url_for(self, name: str, /, **path_params: typing.Any) -> URL:
    router: Router = self.scope["router"]
    url_path = router.url_path_for(name, **path_params)
    return url_path.make_absolute_url(base_url=self.base_url)

receive async 

receive()

Receive ASGI websocket messages, ensuring valid state transitions.

Source code in starlette/websockets.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
async def receive(self) -> Message:
    """
    Receive ASGI websocket messages, ensuring valid state transitions.
    """
    if self.client_state == WebSocketState.CONNECTING:
        message = await self._receive()
        message_type = message["type"]
        if message_type != "websocket.connect":
            raise RuntimeError(
                'Expected ASGI message "websocket.connect", '
                f"but got {message_type!r}"
            )
        self.client_state = WebSocketState.CONNECTED
        return message
    elif self.client_state == WebSocketState.CONNECTED:
        message = await self._receive()
        message_type = message["type"]
        if message_type not in {"websocket.receive", "websocket.disconnect"}:
            raise RuntimeError(
                'Expected ASGI message "websocket.receive" or '
                f'"websocket.disconnect", but got {message_type!r}'
            )
        if message_type == "websocket.disconnect":
            self.client_state = WebSocketState.DISCONNECTED
        return message
    else:
        raise RuntimeError(
            'Cannot call "receive" once a disconnect message has been received.'
        )

send async 

send(<span data-autorefs-optional="fastapi.WebSocket.send(message)">message</span>)

Send ASGI websocket messages, ensuring valid state transitions.

PARAMETER DESCRIPTION
message

TYPE: Message

Source code in starlette/websockets.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
async def send(self, message: Message) -> None:
    """
    Send ASGI websocket messages, ensuring valid state transitions.
    """
    if self.application_state == WebSocketState.CONNECTING:
        message_type = message["type"]
        if message_type not in {"websocket.accept", "websocket.close"}:
            raise RuntimeError(
                'Expected ASGI message "websocket.accept" or '
                f'"websocket.close", but got {message_type!r}'
            )
        if message_type == "websocket.close":
            self.application_state = WebSocketState.DISCONNECTED
        else:
            self.application_state = WebSocketState.CONNECTED
        await self._send(message)
    elif self.application_state == WebSocketState.CONNECTED:
        message_type = message["type"]
        if message_type not in {"websocket.send", "websocket.close"}:
            raise RuntimeError(
                'Expected ASGI message "websocket.send" or "websocket.close", '
                f"but got {message_type!r}"
            )
        if message_type == "websocket.close":
            self.application_state = WebSocketState.DISCONNECTED
        try:
            await self._send(message)
        except IOError:
            self.application_state = WebSocketState.DISCONNECTED
            raise WebSocketDisconnect(code=1006)
    else:
        raise RuntimeError('Cannot call "send" once a close message has been sent.')

accept async 

accept(<span data-autorefs-optional="fastapi.WebSocket.accept(subprotocol)">subprotocol</span>=None, <span data-autorefs-optional="fastapi.WebSocket.accept(headers)">headers</span>=None)
PARAMETER DESCRIPTION
subprotocol

TYPE: str | None DEFAULT: None

headers

TYPE: Iterable[tuple[bytes, bytes]] | None DEFAULT: None

Source code in starlette/websockets.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
async def accept(
    self,
    subprotocol: str | None = None,
    headers: typing.Iterable[tuple[bytes, bytes]] | None = None,
) -> None:
    headers = headers or []

    if self.client_state == WebSocketState.CONNECTING:
        # If we haven't yet seen the 'connect' message, then wait for it first.
        await self.receive()
    await self.send(
        {"type": "websocket.accept", "subprotocol": subprotocol, "headers": headers}
    )

receive_text async 

receive_text()
Source code in starlette/websockets.py 
113
114
115
116
117
118
119
120
async def receive_text(self) -> str:
    if self.application_state != WebSocketState.CONNECTED:
        raise RuntimeError(
            'WebSocket is not connected. Need to call "accept" first.'
        )
    message = await self.receive()
    self._raise_on_disconnect(message)
    return typing.cast(str, message["text"])

receive_bytes async 

receive_bytes()
Source code in starlette/websockets.py 
122
123
124
125
126
127
128
129
async def receive_bytes(self) -> bytes:
    if self.application_state != WebSocketState.CONNECTED:
        raise RuntimeError(
            'WebSocket is not connected. Need to call "accept" first.'
        )
    message = await self.receive()
    self._raise_on_disconnect(message)
    return typing.cast(bytes, message["bytes"])

receive_json async 

receive_json(<span data-autorefs-optional="fastapi.WebSocket.receive_json(mode)">mode</span>='text')
PARAMETER DESCRIPTION
mode

TYPE: str DEFAULT: 'text'

Source code in starlette/websockets.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
async def receive_json(self, mode: str = "text") -> typing.Any:
    if mode not in {"text", "binary"}:
        raise RuntimeError('The "mode" argument should be "text" or "binary".')
    if self.application_state != WebSocketState.CONNECTED:
        raise RuntimeError(
            'WebSocket is not connected. Need to call "accept" first.'
        )
    message = await self.receive()
    self._raise_on_disconnect(message)

    if mode == "text":
        text = message["text"]
    else:
        text = message["bytes"].decode("utf-8")
    return json.loads(text)

iter_text async 

iter_text()
Source code in starlette/websockets.py 
147
148
149
150
151
152
async def iter_text(self) -> typing.AsyncIterator[str]:
    try:
        while True:
            yield await self.receive_text()
    except WebSocketDisconnect:
        pass

iter_bytes async 

iter_bytes()
Source code in starlette/websockets.py 
154
155
156
157
158
159
async def iter_bytes(self) -> typing.AsyncIterator[bytes]:
    try:
        while True:
            yield await self.receive_bytes()
    except WebSocketDisconnect:
        pass

iter_json async 

iter_json()
Source code in starlette/websockets.py 
161
162
163
164
165
166
async def iter_json(self) -> typing.AsyncIterator[typing.Any]:
    try:
        while True:
            yield await self.receive_json()
    except WebSocketDisconnect:
        pass

send_text async 

send_text(<span data-autorefs-optional="fastapi.WebSocket.send_text(data)">data</span>)
PARAMETER DESCRIPTION
data

TYPE: str

Source code in starlette/websockets.py 
168
169
async def send_text(self, data: str) -> None:
    await self.send({"type": "websocket.send", "text": data})

send_bytes async 

send_bytes(<span data-autorefs-optional="fastapi.WebSocket.send_bytes(data)">data</span>)
PARAMETER DESCRIPTION
data

TYPE: bytes

Source code in starlette/websockets.py 
171
172
async def send_bytes(self, data: bytes) -> None:
    await self.send({"type": "websocket.send", "bytes": data})

send_json async 

send_json(<span data-autorefs-optional="fastapi.WebSocket.send_json(data)">data</span>, <span data-autorefs-optional="fastapi.WebSocket.send_json(mode)">mode</span>='text')
PARAMETER DESCRIPTION
data

TYPE: Any

mode

TYPE: str DEFAULT: 'text'

Source code in starlette/websockets.py 
174
175
176
177
178
179
180
181
async def send_json(self, data: typing.Any, mode: str = "text") -> None:
    if mode not in {"text", "binary"}:
        raise RuntimeError('The "mode" argument should be "text" or "binary".')
    text = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    if mode == "text":
        await self.send({"type": "websocket.send", "text": text})
    else:
        await self.send({"type": "websocket.send", "bytes": text.encode("utf-8")})

close async 

close(<span data-autorefs-optional="fastapi.WebSocket.close(code)">code</span>=1000, <span data-autorefs-optional="fastapi.WebSocket.close(reason)">reason</span>=None)
PARAMETER DESCRIPTION
code

TYPE: int DEFAULT: 1000

reason

TYPE: str | None DEFAULT: None

Source code in starlette/websockets.py 
183
184
185
186
async def close(self, code: int = 1000, reason: str | None = None) -> None:
    await self.send(
        {"type": "websocket.close", "code": code, "reason": reason or ""}
    )

When a client disconnects, a WebSocketDisconnect exception is raised, you can catch it.

You can import it directly form fastapi:

from fastapi import WebSocketDisconnect

fastapi.WebSocketDisconnect 

WebSocketDisconnect(<span data-autorefs-optional="fastapi.WebSocketDisconnect(code)">code</span>=1000, <span data-autorefs-optional="fastapi.WebSocketDisconnect(reason)">reason</span>=None)

Bases: Exception

PARAMETER DESCRIPTION
code

TYPE: int DEFAULT: 1000

reason

TYPE: Optional[str] DEFAULT: None

Source code in starlette/websockets.py 
18
19
20
def __init__(self, code: int = 1000, reason: typing.Optional[str] = None) -> None:
    self.code = code
    self.reason = reason or ""

code instance-attribute 

code = code

reason instance-attribute 

reason = reason or ''

WebSockets - additional classes

Additional classes for handling WebSockets.

Provided directly by Starlette, but you can import it from fastapi:

from fastapi.websockets import WebSocketDisconnect, WebSocketState

fastapi.websockets.WebSocketDisconnect 

WebSocketDisconnect(<span data-autorefs-optional="fastapi.websockets.WebSocketDisconnect(code)">code</span>=1000, <span data-autorefs-optional="fastapi.websockets.WebSocketDisconnect(reason)">reason</span>=None)

Bases: Exception

PARAMETER DESCRIPTION
code

TYPE: int DEFAULT: 1000

reason

TYPE: Optional[str] DEFAULT: None

Source code in starlette/websockets.py 
18
19
20
def __init__(self, code: int = 1000, reason: typing.Optional[str] = None) -> None:
    self.code = code
    self.reason = reason or ""

code instance-attribute 

code = code

reason instance-attribute 

reason = reason or ''

fastapi.websockets.WebSocketState

Bases: Enum

CONNECTING class-attribute instance-attribute 

CONNECTING = 0

CONNECTED class-attribute instance-attribute 

CONNECTED = 1

DISCONNECTED class-attribute instance-attribute 

DISCONNECTED = 2