API¶
websockets
provides complete client and server implementations, as shown
in the getting started guide.
The process for opening and closing a WebSocket connection depends on which side you’re implementing.
On the client side, connecting to a server with
connect
yields a connection object that provides methods for interacting with the connection. Your code can open a connection, then send or receive messages.If you use
connect
as an asynchronous context manager, then websockets closes the connection on exit. If not, then your code is responsible for closing the connection.On the server side,
serve
starts listening for client connections and yields an server object that supports closing the server.Then, when clients connects, the server initializes a connection object and passes it to a handler coroutine, which is where your code can send or receive messages. This pattern is called inversion of control. It’s common in frameworks implementing servers.
When the handler coroutine terminates, websockets closes the connection. You may also close it in the handler coroutine if you’d like.
Once the connection is open, the WebSocket protocol is symmetrical, except for
low-level details that websockets manages under the hood. The same methods are
available on client connections created with connect
and
on server connections passed to the connection handler in the arguments.
At this point, websockets provides the same API — and uses the same code — for client and server connections. For convenience, common methods are documented both in the client API and server API.
All public APIs can be imported from the websockets
package, unless
noted otherwise. This convenience feature is incompatible with static code
analysis tools such as mypy, though.
Anything that isn’t listed in this API documentation is a private API. There’s no guarantees of behavior or backwards-compatibility for private APIs.