wspy

About

wspy is a standalone implementation of web sockets for Python, defined by RFC 6455. The incentive for creating this library is the absence of a layered implementation of web sockets outside the scope of web servers such as Apache or Nginx. wspy does not require any third-party programs or libraries outside Python's standard library. It provides low-level access to sockets, as well as high-level functionalities to easily set up a web server. Thus, it is both suited for quick server programming, as well as for more demanding applications that require low-level control over each frame being sent/received.

Her is a quick overview of the features in this library:

• Upgrading regular sockets to web sockets.
• Building custom frames.
• Messages, which are higher-level than frames (see "Basic usage").
• Connections, which hide the handling of control frames and automatically concatenate fragmented messages to individual payloads.
• HTTP authentication during handshake.
• An extendible server implementation.
• Secure sockets using SSL certificates (for 'wss://...' URLs).
• An API for implementing WebSocket extensions. Included implementations are deflate-frame and permessage-deflate.
• Asynchronous sockets with an EPOLL-based server.

Installation

Use Python's package manager:

easy_install wspy
pip install wspy

Basic usage

• The websocket class upgrades a regular socket to a web socket. A websocket instance is a single end point of a connection. A websocket instance sends and receives frames (Frame instances) as opposed to bytes (which are sent/received in a regular socket).

Server example:

    import wspy, socket
    sock = wspy.websocket()
    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    sock.bind(('', 8000))
    sock.listen(5)

    client = sock.accept()
    client.send(wspy.Frame(wspy.OPCODE_TEXT, 'Hello, Client!'))
    frame = client.recv()

Client example:

    import wspy
    sock = wspy.websocket(location='/my/path')
    sock.connect(('', 8000))
    sock.send(wspy.Frame(wspy.OPCODE_TEXT, 'Hello, Server!'))

• A Connection instance represents a connection between two end points, based on a websocket instance. A connection handles control frames properly, and sends/receives messages (Message instances, which are higher-level than frames). Messages are automatically converted to frames, and received frames are converted to messages. Fragmented messages (messages consisting of multiple frames) are also supported.

Example of an echo server (sends back what it receives):

    import socket
    import wspy

    class EchoConnection(wspy.Connection):
        def onopen(self):
            print 'Connection opened at %s:%d' % self.sock.getpeername()

        def onmessage(self, message):
            print 'Received message "%s"' % message.payload
            self.send(wspy.TextMessage(message.payload))

        def onclose(self, code, reason):
            print 'Connection closed'

    server = wspy.websocket()
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind(('', 8000))
    server.listen(5)

    while True:
        client, addr = server.accept()
        EchoConnection(client).receive_forever()

There are two types of messages: TextMessages and BinaryMessages. A TextMessage uses frames with opcode OPCODE_TEXT, and encodes its payload using UTF-8 encoding. A BinaryMessage just sends its payload as raw data. I recommend using TextMessage by default, and BinaryMessage only when necessary.

Note: For browser clients, you will probably want to use JSON encoding. This could, for example, be implemented as follows:

    import wspy, json

    def msg(**data):
        return wspy.TextMessage(json.dumps(data))

    # create some connection `conn`...

    conn.send(msg(foo='Hello, World!'))

Built-in servers

Threaded

The Server class is very basic. It starts a new thread with a Connection.receive_forever() loop for each client that connects. It also handles client crashes properly. By default, a Server instance only logs every event using Python's logging module. To create a custom server, The Server class should be extended and its event handlers overwritten. The event handlers are named identically to the Connection event handlers, but they also receive an additional client argument. The client argumetn is a modified Connection instance, so you can invoke send() and recv().

For example, the EchoConnection example above can be rewritten to:

  import wspy

  class EchoServer(wspy.Server):
      def onopen(self, client):
          print 'Client %s connected' % client

      def onmessage(self, client, message):
          print 'Received message "%s"' % message.payload
          client.send(wspy.TextMessage(message.payload))

      def onclose(self, client, code, reason):
          print 'Client %s disconnected' % client

  EchoServer(('', 8000)).run()

The server can be stopped by typing CTRL-C in the command line. The KeyboardInterrupt raised when this happens is caught by the server.

Asynchronous

The AsyncServer class has the same API as Server, but uses EPOLL instead of threads. This means that when you send a message, it is put into a queue to be sent later when the socket is ready. The client argument is againa modified Connection instance, with a non-blocking send() method (recv is still blocking, use the server's onmessage callback instead).

Extensions

TODO