.. image:: https://travis-ci.org/invisibleroads/socketIO-client.svg?branch=master :target: https://travis-ci.org/invisibleroads/socketIO-client

socketIO-client-2

Here is a socket.io <http://socket.io>_ client library for Python. You can use it to write test code for your socket.io server.

Please note that this version implements socket.io protocol 1.x <https://github.com/automattic/socket.io-protocol>, which is not backwards compatible. If you want to communicate using socket.io protocol 0.9 <https://github.com/learnboost/socket.io-spec> (which is compatible with gevent-socketio <https://github.com/abourget/gevent-socketio>), please use socketIO-client 0.5.6 <https://pypi.python.org/pypi/socketIO-client/0.5.6>.

Installation

Install the package in an isolated environment. ::

mkvirtualenv your_env_name
pip install socketIO-client-2

Usage

Activate isolated environment. ::

workon your_env_name

Launch your socket.io server or this provided test server. ::

# Get package folder
PACKAGE_FOLDER=`python -c "import os, socketIO_client;\
    print(os.path.dirname(socketIO_client.__file__))"`
# Install the server dependencies
cd $PACKAGE_FOLDER/tests/
npm install
# Start socket.io server
DEBUG=* node $PACKAGE_FOLDER/tests/serve.js
# Start proxy server in a separate terminal on the same machine
DEBUG=* node $PACKAGE_FOLDER/tests/proxy.js
# To run the tests in a third terminal
cd $PACKAGE_FOLDER
nosetests --with-coverage --cover-package=socketIO_client tests/

For debugging information, run these commands first. ::

import logging
logging.getLogger('requests').setLevel(logging.WARNING)
logging.basicConfig(level=logging.DEBUG)

Emit. ::

from socketIO_client import SocketIO, LoggingNamespace

with SocketIO('localhost', 8000, LoggingNamespace) as socketIO:
    socketIO.emit('aaa')
    socketIO.wait(seconds=1)

Emit with callback. ::

from socketIO_client import SocketIO, LoggingNamespace

def on_bbb_response(*args):
    print('on_bbb_response', args)

with SocketIO('localhost', 8000, LoggingNamespace) as socketIO:
    socketIO.emit('bbb', {'xxx': 'yyy'}, on_bbb_response)
    socketIO.wait_for_callbacks(seconds=1)

Define events. ::

from socketIO_client import SocketIO, LoggingNamespace

def on_aaa_response(*args):
    print('on_aaa_response', args)

socketIO = SocketIO('localhost', 8000, LoggingNamespace)
socketIO.on('aaa_response', on_aaa_response)
socketIO.emit('aaa')
socketIO.wait(seconds=1)

Define events in a namespace. ::

from socketIO_client import SocketIO, BaseNamespace

class Namespace(BaseNamespace):

    def on_aaa_response(self, *args):
        print('on_aaa_response', args)
        self.emit('bbb')

socketIO = SocketIO('localhost', 8000, Namespace)
socketIO.emit('aaa')
socketIO.wait(seconds=1)

Define standard events. ::

from socketIO_client import SocketIO, BaseNamespace

class Namespace(BaseNamespace):

    def on_connect(self):
        print('[Connected]')

socketIO = SocketIO('localhost', 8000, Namespace)
socketIO.wait(seconds=1)

Define different namespaces on a single socket. ::

from socketIO_client import SocketIO, BaseNamespace

class ChatNamespace(BaseNamespace):

    def on_aaa_response(self, *args):
        print('on_aaa_response', args)

class NewsNamespace(BaseNamespace):

    def on_aaa_response(self, *args):
        print('on_aaa_response', args)

socketIO = SocketIO('localhost', 8000)
chat_namespace = socketIO.define(ChatNamespace, '/chat')
news_namespace = socketIO.define(NewsNamespace, '/news')

chat_namespace.emit('aaa')
news_namespace.emit('aaa')
socketIO.wait(seconds=1)

Connect via SSL. ::

from socketIO_client import SocketIO

SocketIO('https://localhost', verify=False)

Specify params, headers, cookies, proxies thanks to the requests <http://python-requests.org>_ library. ::

from socketIO_client import SocketIO
from base64 import b64encode

SocketIO(
    localhost', 8000,
    params={'q': 'qqq'},
    headers={'Authorization': 'Basic ' + b64encode('username:password')},
    cookies={'a': 'aaa'},
    proxies={'https': 'https://proxy.example.com:8080'})

Wait forever. ::

from socketIO_client import SocketIO

socketIO = SocketIO('localhost', 8000)
socketIO.wait()

Contributing

I am following the git-flow <http://nvie.com/posts/a-successful-git-branching-model/> model put forward by Vincent Driessen. Therefore I ask that you make pull requests to the develop branch. Also, I am supporting Python 2.6, 2.7, and 3.4 so please make sure that your changes are compatible with all three versions. Travis-CI is setup to automatically run the tests with all three Python versions on pull-requests so if you add tests to cover any changes you made then you should be able to see if they are compatible.

License

This software is available under the MIT License.

Credits

• Guillermo Rauch <https://github.com/rauchg>_ wrote the socket.io specification <https://github.com/automattic/socket.io-protocol>_.
• Hiroki Ohtani <https://github.com/liris>_ wrote websocket-client <https://github.com/liris/websocket-client>_.
• rod <http://stackoverflow.com/users/370115/rod>_ wrote a prototype for a Python client to a socket.io server <http://stackoverflow.com/questions/6692908/formatting-messages-to-send-to-socket-io-node-js-server-from-python-client>_.
• Alexandre Bourget <https://github.com/abourget>_ wrote gevent-socketio <https://github.com/abourget/gevent-socketio>_, which is a socket.io server written in Python.
• Paul Kienzle <https://github.com/pkienzle>, Zac Lee <https://github.com/zratic>, Josh VanderLinden <https://github.com/codekoala>, Ian Fitzpatrick <https://github.com/ifitzpatrick>, Lucas Klein <https://github.com/lukasklein>, Rui Chicoria <https://github.com/rchicoria>, Travis Odom <https://github.com/burstaholic>, Patrick Huber <https://github.com/stackmagic>, Brad Campbell <https://github.com/bradjc>, Daniel <https://github.com/dabidan>, Sean Arietta <https://github.com/sarietta>_ submitted code to expand support of the socket.io protocol.
• Bernard Pratz <https://github.com/guyzmo>, Francis Bull <https://github.com/franbull> wrote prototypes to support xhr-polling and jsonp-polling.
• Eric Chen <https://github.com/taiyangc>, Denis Zinevich <https://github.com/dzinevich>, Thiago Hersan <https://github.com/thiagohersan>, Nayef Copty <https://github.com/nayefc>, Jörgen Karlsson <https://github.com/jorgen-k>, Branden Ghena <https://github.com/brghena>, Tim Landscheidt <https://github.com/scfc>, Matt Porritt <https://github.com/mattporritt> suggested ways to make the connection more robust.
• Merlijn van Deen <https://github.com/valhallasw>, Frederic Sureau <https://github.com/fredericsureau>, Marcus Cobden <https://github.com/leth>, Drew Hutchison <https://github.com/drewhutchison>, wuurrd <https://github.com/wuurrd>, Adam Kecer <https://github.com/amfg>, Alex Monk <https://github.com/Krenair>, Vishal P R <https://github.com/vishalwy>, John Vandenberg <https://github.com/jayvdb>, Thomas Grainger <https://github.com/graingert> proposed changes that make the library more friendly and practical for you!