Virtual Socket implementation, unifies all the Transports into one single interface, and abstracts the work of the long-polling methods.

This module also has the default_error_handler implementation. You can define your own so that the error messages are logged or sent in a different way

copyright:2012, Alexandre Bourget <>
moduleauthor:Alexandre Bourget <>
class socketio.virtsocket.Socket(server, config, error_handler=None)[source]

Bases: object

Virtual Socket implementation, checks heartbeats, writes to local queues for message passing, holds the Namespace objects, dispatches de packets to the underlying namespaces.

This is the abstraction on top of the different transports. It’s like if you used a WebSocket only...


Use this to be explicit when specifying a Global Namespace (an endpoint with no name, not ‘/chat’ or anything.


Returns whether the state is CONNECTED or not.


Detach this socket from the server. This should be done in conjunction with kill(), once all the jobs are dead, detach the socket for garbage collection.


Calling this method will call the disconnect() method on all the active Namespaces that were open, killing all their jobs and sending ‘disconnect’ packets for each of them.

Normally, the Global namespace (endpoint = ‘’) has special meaning, as it represents the whole connection,

Parameters:silent – when True, pass on the silent flag to the Namespace disconnect() calls.
error(error_name, error_message, endpoint=None, msg_id=None, quiet=False)[source]

Send an error to the user, using the custom or default ErrorHandler configured on the [TODO: Revise this] Socket/Handler object.

  • error_name – is a simple string, for easy association on the client side
  • error_message – is a human readable message, the user will eventually see
  • endpoint – set this if you have a message specific to an end point
  • msg_id – set this if your error is relative to a specific message
  • quiet – way to make the error handler quiet. Specific to the handler. The default handler will only log, with quiet.

Grab a message to send it to the browser


Get multiple messages, in case we’re going through the various XHR-polling methods, on which we can pack more than one message if the rate is high, and encode the payload for the HTTP channel.


Grab a message, to process it by the server and dispatch calls


This makes the heart beat for another X seconds. Call this when you get a heartbeat packet in.

This clear the heartbeat disconnect timeout (resets for X seconds).

static json_dumps(data)
static json_loads(data)

This function must/will be called when a socket is to be completely shut down, closed by connection timeout, connection error or explicit disconnection from the client.

It will call all of the Namespace’s disconnect() methods so that you can shut-down things properly.


Writes to the client’s pipe, to end up in the browser


Writes to the server’s pipe, to end up in in the Namespaces


This removes a Namespace object from the socket.

This is usually called by disconnect().


Low-level interface to queue a packet on the wire (encoded as wire protocol

spawn(fn, *args, **kwargs)[source]

Spawn a new Greenlet, attached to this Socket instance.

It will be monitored by the “watcher” method

socketio.virtsocket.default_error_handler(socket, error_name, error_message, endpoint, msg_id, quiet)[source]

This is the default error handler, you can override this when calling socketio.socketio_manage().

It basically sends an event through the socket with the ‘error’ name.

See documentation for Socket.error().

Parameters:quiet – if quiet, this handler will not send a packet to the user, but only log for the server developer.