Welcome to asyncwebsockets’s documentation!¶

asyncwebsockets is a Python 3.6+ library for interacting with websockets over the internet from asynchronous code. asyncwebsockets is designed around anyio, allowing it to work with multiple async backends without any modifications.

asyncwebsockets supports client and server mode.

Installation¶

To install the latest stable version:

$ pip install asyncwebsockets

To install the latest development version:

$ pip install git+https://github.com/Fuyukai/asyncwebsockets.git#egg=asyncwebsockets

Basic Usage¶

Client connection¶

To open a new websocket connection to a server, use open_websocket():

This async context manager returns a new Websocket, which is the main object used for communication with the server.

You can use create_websocket() if using a context manager is inconvenient, but then you’re responsible for closing it.

The functions create_websocket_client() and open_websocket.client() accept an existing socket instead of a URL.

Server connection¶

Likewise, create_websocket_server() and open_websocket.server() accept an existing socket to act as a Websocket server.

asyncwebsockets does not provide server equivalents of open_websocket() or create_websocket(); use whatever method is most convenient for your code.

Data transfer¶

After being established, a Websocket connection is bidirectional and does no longer distinguish between client and server roles.

You get new events from the websocket by async iteration over the websocket object:

async for evt in websocket:
    print(type(evt))  # handle event appropriately

See the wsproto.events documentation for message types.

You can send data (strings or bytes) to the websocket in response with ClientWebsocket.send_message():

from wsproto.events import TextMessage

async for evt in websocket:
   if isinstance(evt, TextMessage):
      await websocket.send("Thanks for saying '%s'!" % (evt.data,))

await Websocket.send(data, final=True)[source]¶: Sends some data down the connection.

In short, you receive TextMessage or ByteMessage messages, depending on the payload. You can also filter for Message instances, and discern between strings and bytes by checking the type of the .data attribute.

Finally, the websocket can be closed with the usage of ClientWebsocket.close():

await websocket.close(1000, reason="Goodbye!")

await Websocket.close(code=1006, reason='Connection closed')[source]¶: Closes the websocket.

Event Listing¶

Events are the standard wsproto events.

Changelog¶

0.5.0¶

Add server mode

Add ability to take over an existing socket

0.4.0¶

Adapt to current wsproto design

0.3.0¶

Redesign API, again, hopefully for the last time.

0.2.0¶

Redesign API significantly.

0.1.0¶

Initial release.

Navigation