API reference#

websockets provides 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 you can use to shut down the server.

    Then, when a client 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 received in argument by the connection handler of serve().

Public API documented in the API reference are subject to the backwards-compatibility policy.

Anything that isn’t listed in the API reference is a private API. There’s no guarantees of behavior or backwards-compatibility for private APIs.

Convenience imports are incompatible with some development tools.

For convenience, most public APIs can be imported from the websockets package. However, this is incompatible with static code analysis.

It may break auto-completion and contextual documentation in IDEs, type checking with mypy, etc. If you’re using such tools, stick to the full import paths.