Skip to main content

Simple websocket implementation in python using asyncio

Project description

Simple websocket implementation in python

PyPI version Python version


$ pip install simple_ws


To test the library, clone repo, open two command windows and cd into the python-WS directory

  • Run python -m http.server 8000
  • Run python in the other window
  • Open http://localhost:8000 in a browser


from simple_ws import WebSocket

class WSHandler(WebSocket):
    def on_message(self, msg, target_client):
        for client in self.clients:
            if client.is_open():

    def on_open(self, client):
        print("Client connected!")

    def on_close(self, client):
        print("Client left...")

    def on_ping(self, client):
        print("Recieved ping!")

    def on_pong(self, client):
        print("Recieved pong!")

host = ''
port = 8080

ws = WSHandler(host, port)

WebSocket parameters

parameter type default descriptio n
host String   Host domain
port Integer   Port number for websocket
ping Boolean True Whether server should ping client in a given intervall, will close connection if pong is not received
ping_int ervall Integer 5 How often should server ping client in seconds, has no effect if ping is set to false
compress ion Boolean True Whether messages should be compressed
max_fram e_size Integer 8192 Max size for a single websocket frame. If payload exceeds limit, the message will be split in several parts
buffer_s ize Integer 4096 Max network buffer size



on_open(self, client)

Called when the server opens a connection to a new client (client).

def on_open(self, client):
    # Executes when opening a connection

on_close(self, client)

Called when the server closes a connection to a client (client).

def on_close(self, client):
    # Executes when closing a connection

on_message(self, msg, client)

Called when the server has received a message (msg) from a client (client). The message can be in either binary or text format.

def on_message(self, msg, client):
    # Executes when server recieves a messages from client

on_ping(self, client)

Called when the server sends a ping to a client (client).

def on_ping(self, client):
    # Executes when ping is sent to a client

on_pong(self, client)

Called when the server receives a pong from a client (client).

def on_pong(self, client):
    # Executes when pong is received from a client


write_message(self, msg, binary=False)

Sends a message payload (msg) to the client. If binary=True, the message gets sent as binary data.

# Text message
client.write_message("Hello world")

# Binary message
client.write_message(b"0x00", binary=True)


Returns True if the connection has gone through handshake, and is currently open.

close(self, status, reason)

Sends a close frame to the client, and closes the connection after either a response, or after 1 second. Status and reason are not currently implemented. Will ultimately result in WebSocket.on_close being fired.

client.close(1002, "Pong not recieved")


  1. Write more tests
  2. Add support for payload in ping and pong frames
  3. Error handling
  4. Clean up classes
  5. Implement close status and reason
  6. Implement all compression configurations
  7. Add more configurability/remove hardcoded constants
  8. Implement connection limit


MIT License

Project details

Download files

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

Files for simple_ws, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size simple_ws-0.3.1.tar.gz (7.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page