Skip to main content

WebSockets state-machine based protocol implementation

Project description

Pure Python, pure state-machine WebSocket implementation

Build status Documentation Status Code coverage

This repository contains a pure-Python implementation of a WebSocket protocol stack. It’s written from the ground up to be embeddable in whatever program you choose to use, ensuring that you can communicate via WebSockets, as defined in RFC6455, regardless of your programming paradigm.

This repository does not provide a parsing layer, a network layer, or any rules about concurrency. Instead, it’s a purely in-memory solution, defined in terms of data actions and WebSocket frames. RFC6455 and Compression Extensions for WebSocket via RFC7692 are fully supported.

wsproto supports Python 2.7 and 3.5 or higher.

To install it, just run:

$ pip install wsproto

Usage

Let’s assume you have some form of network socket available. wsproto client connections automatically generate a HTTP request to initiate the WebSocket handshake. To create a WebSocket client connection:

from wsproto.connection import WSConnection, ConnectionType
ws = WSConnection(ConnectionType.CLIENT, host='echo.websocket.org', resource='/')

To create a WebSocket server connection:

from wsproto.connection import WSConnection, ConnectionType
ws = WSConnection(ConnectionType.SERVER)

Every time you send a message, or call a ping, or simply if you receive incoming data, wsproto might respond with some outgoing data that you have to send:

some_socket.send(ws.bytes_to_send())

Both connection types need to receive incoming data:

ws.receive_bytes(some_byte_string_of_data)

And wsproto will issue events if the data contains any WebSocket messages or state changes:

for event in ws.events():
    if isinstance(event, ConnectionRequested):
        # only client connections get this event
        ws.accept(event)
    elif isinstance(event, ConnectionClosed):
        # guess nobody wants to talk to us any more...
    elif isinstance(event, TextReceived):
        print('We got a text!', event.data)
    elif isinstance(event, TextReceived):
        print('We got a text!', event.data)

Take a look at our docs for a full list of events <https://wsproto.readthedocs.io/en/latest/api.html#events>!

Testing

It passes the autobahn test suite completely and strictly in both client and server modes and using permessage-deflate.

If wsaccel is installed (optional), then it will be used to speed things up.

If you want to run the compliance tests, go into the compliance directory and then to test client mode, in one shell run the Autobahn test server:

$ wstest -m fuzzingserver -s ws-fuzzingserver.json

And in another shell run the test client:

$ python test_client.py

And to test server mode, run the test server:

$ python test_server.py

And in another shell run the Autobahn test client:

$ wstest -m fuzzingclient -s ws-fuzzingclient.json

Documentation

Documentation is available at https://wsproto.readthedocs.io/en/latest/.

Contributing

wsproto welcomes contributions from anyone! Unlike many other projects we are happy to accept cosmetic contributions and small contributions, in addition to large feature requests and changes.

Before you contribute (either by opening an issue or filing a pull request), please read the contribution guidelines.

License

wsproto is made available under the MIT License. For more details, see the LICENSE file in the repository.

Authors

wsproto was created by @jeamland, and is maintained by the python-hyper community.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
wsproto-0.12.0-py2.py3-none-any.whl (21.0 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Sep 23, 2018
wsproto-0.12.0.tar.gz (45.3 kB) Copy SHA256 hash SHA256 Source None Sep 23, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page