WebSockets — pulsar 1.6.1 documentation (original) (raw)

The pulsar.apps.ws contains WSGI middleware for handling the WebSocket protocol. Web sockets allow for bidirectional communication between the browser and server. Pulsar implementation uses the WSGI middlewareWebSocket for the handshake and a class derived fromWS handler for the communication part.

This is a Web Socket handler which echoes all received messages back to the client:

from pulsar.apps import wsgi, ws

class EchoWS(ws.WS):

def on_message(self, websocket, message):
    websocket.write(message)

To create a valid WebSocket middleware initialise as follow:

wm = ws.WebSocket('/bla', EchoWS()) app = wsgi.WsgiHandler(middleware=(..., wm)) wsgi.WSGIServer(callable=app).start()

API¶

WebSocket handler¶

class pulsar.apps.ws. WS[source]¶

A web socket handler for both servers and clients.

It implements the asynchronous message passing for aWebSocketProtocol. On the server, the communication is started by theWebSocket middleware after a successful handshake.

Override on_message() to handle incoming string messages andon_bytes() to handle incoming bytes messages.

You can also override on_open() and on_close() to perform specific tasks when the websocket is opened or closed.

These methods accept as first parameter theWebSocketProtocol created during the handshake.

on_open(websocket)[source]¶

Invoked when a new websocket is opened.

A web socket is opened straight after the upgrade headers are sent (servers) or received (clients).

on_message(websocket, message)[source]¶

Handles incoming messages on the WebSocket.

This method should be overwritten

on_bytes(websocket, body)[source]¶

Handles incoming bytes.

on_ping(websocket, message)[source]¶

Handle incoming ping message.

By default it writes back the message as a pong frame.

on_pong(websocket, body)[source]¶

Handle incoming pong message.

on_close(websocket)[source]¶

Invoked when the websocket is closed.

WebSocket¶

class pulsar.apps.ws.websocket. WebSocket(route, handle, parser_factory=None, **kwargs)[source]¶

A specialised Router for a websocket handshake.

Once the handshake is successful, the protocol consumer is upgraded to WebSocketProtocol and messages are handled by the handle attribute, an instance of WS.

See http://tools.ietf.org/html/rfc6455 for the websocket server protocol and http://www.w3.org/TR/websockets/ for details on the JavaScript interface.

parser_factory¶

A factory of websocket frame parsers

protocol_class¶

alias of WebSocketProtocol

parser_factory(version=None, kind=0, extensions=None, protocols=None, pyparser=False)

Create a new FrameParser instance.

WebSocket protocol¶

class pulsar.apps.ws.websocket. WebSocketProtocol(handshake, handler, parser, loop=None)[source]¶

A ProtocolConsumer for websocket servers and clients.

handshake¶

The original handshake response/request.

handler¶

A websocket handler WS.

parser¶

A websocket FrameParser.

close_reason¶

A tuple of (code, reason) or None.

Available when a close frame is received.

cfg¶

The Config container for this protocol.

write(message, opcode=None, encode=True, **kw)[source]¶

Write a new message into the wire.

It uses the encode() method of the websocket parser.

ping(message=None)[source]¶

Write a ping frame.

pong(message=None)[source]¶

Write a pong frame.

write_close(code=None)[source]¶

Write a close frame with code.