Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Refer examples for more details :


This client provides following functionality

  • Easy to setup and use
  • Can be used for extensive unit-testing of all server side functions
  • Support for emitting and listening to remote events
  • Automatic reconnection
  • Pub/sub
  • Authentication (JWT)
  • Support for python2.x.x / python3.x.x

To install use

    sudo pip install socketclusterclient


Create instance of Socket class by passing url of socketcluster-server end-point

    //Create a socket instance
    socket = Socketcluster.socket("ws://localhost:8000/socketcluster/") 

Important Note : Default url to socketcluster end-point is always ws://

Registering basic listeners

Different functions are given as an argument to register listeners

        from socketclusterclient import Socketcluster
        import logging
        logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
        def onconnect(socket):
  "on connect got called")
        def ondisconnect(socket):
  "on disconnect got called")
        def onConnectError(socket, error):
  "On connect error got called")
        def onSetAuthentication(socket, token):
  "Token received " + token)
        def onAuthentication(socket, isauthenticated):
  "Authenticated is " + str(isauthenticated))
        if __name__ == "__main__":
            socket = Socketcluster.socket("ws://localhost:8000/socketcluster/")
            socket.setBasicListener(onconnect, ondisconnect, onConnectError)
            socket.setAuthenticationListener(onSetAuthentication, onAuthentication)

Connecting to server

  • For connecting to server:
    //This will send websocket handshake request to socketcluster-server
  • By default reconnection to server is disabled (since latest release) , to enable it and configure delay for connection
    //This will set automatic-reconnection to server with delay of 2 seconds and repeating it for infinitely
  • By default logging of messages in disabled (since latest release), to enable it

Emitting and listening to events

Event emitter

  • eventname is name of event and message can be String, boolean, int or JSON-object
    # socket.emit("chat", "Hi")
  • To send event with acknowledgement
    socket.emitack("chat", "Hi", ack)  
    def ack(eventname, error, object):
        print "Got ack data " + object + " and error " + error + " and eventname is " + eventname

Event Listener

  • For listening to events :

The object received can be String, Boolean, Long or JSONObject.

     # Receiver code without sending acknowledgement back
     socket.on("ping", message)
     def message(eventname, object):
         print "Got data " + object + " from eventname " + eventname
  • To send acknowledgement back to server
    # Receiver code with ack
    socket.onack("ping", messsageack)
    def messsageack(eventname, object, ackmessage):
        print "Got data " + object + " from eventname " + eventname
        ackmessage("this is error", "this is data")

Implementing Pub-Sub via channels

Creating channel

  • For creating and subscribing to channels:
    # without acknowledgement
    #with acknowledgement
    socket.subscribeack('yell', suback)
    def suback(channel, error, object):
        if error is '':
            print "Subscribed successfully to channel " + channel
  • For getting list of created channels :
        channels = socket.getsubscribedchannels()

Publishing event on channel

  • For publishing event :
       # without acknowledgement
       socket.publish('yell', 'Hi dudies')
       #with acknowledgement
       socket.publishack('yell', 'Hi dudies', puback)
       def puback(channel, error, object):
           if error is '':
               print "Publish sent successfully to channel " + channel

Listening to channel

  • For listening to channel event :
        socket.onchannel('yell', channelmessage)
        def channelmessage(key, object):
            print "Got data " + object + " from key " + key

Un-subscribing to channel

         # without acknowledgement
         # with acknowledgement
         socket.unsubscribeack('yell', unsuback) 
         def unsuback(channel, error, object):
              if error is '':
                   print "Unsubscribed to channel " + channel 

Disable SSL Certificate Verification

        socket = Socketcluster.socket("wss://localhost:8000/socketcluster/")
        socket.connect(sslopt={"cert_reqs": ssl.CERT_NONE})

HTTP proxy

Support websocket access via http proxy. The proxy server must allow "CONNECT" method to websocket port. Default squid setting is "ALLOWED TO CONNECT ONLY HTTPS PORT".

        socket = Socketcluster.socket("wss://localhost:8000/socketcluster/")
        socket.connect(http_proxy_host="proxy_host_name", http_proxy_port=3128)
  • To have custom settings over internal logger, you can get logger instance and apply necessary settings over it.
        sclogger = socket.getlogger()

Please follow logging tutorial over here :