# ws4py Package

## `ws4py` Package

`ws4py.__init__.``configure_logger`(stdout=True, filepath=None, level=20)

`ws4py.__init__.``format_addresses`(ws)

## `exc` Module

exception `ws4py.exc.``WebSocketException`

  Bases: `Exception`

exception `ws4py.exc.``ProtocolException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``FrameTooLargeException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``UnsupportedFrameTypeException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``UnsupportedFrameTypeException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``TextFrameEncodingException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``TextFrameEncodingException`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``InvalidBytesError`

  Bases: `ws4py.exc.WebSocketException`

exception `ws4py.exc.``StreamClosed`

  Bases: `Exception`

exception `ws4py.exc.``HandshakeError`(msg)

  Bases: `ws4py.exc.WebSocketException`

## `framing` Module

class `ws4py.framing.``Frame`(opcode=None, body=b'', masking_key=None, fin=0, rsv1=0, rsv2=0, rsv3=0)

  Bases: `object`

  Implements the framing protocol as defined by RFC 6455.

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10

      >>> test_mask = 'XXXXXX' # perhaps from os.urandom(4)
      >>> f = Frame(OPCODE_TEXT, 'hello world', masking_key=test_mask, fin=1)
      >>> bytes = f.build()
      >>> bytes.encode('hex')
      '818bbe04e66ad6618a06d1249105cc6882'
      >>> f = Frame()
      >>> f.parser.send(bytes[0])
      1
      >>> f.parser.send(bytes[1])
      4

  See also

  Data Framing http://tools.ietf.org/html/rfc6455#section-5.2

  `parser`
  `build`()

    Builds a frame from the instance’s attributes and returns its bytes representation.

  `mask`(data)

    Performs the masking or unmasking operation on data using the simple masking algorithm:

  `unmask`(data)

    Performs the masking or unmasking operation on data using the simple masking algorithm:

## `manager` Module

The manager module provides a selected classes to handle websocket’s execution.

Initially the rationale was to:

- Externalize the way the CherryPy server had been setup as its websocket management was too tightly coupled with the plugin implementation.
- Offer a management that could be used by other server or client implementations.
- Move away from the threaded model to the event-based model by relying on select or epoll (when available).

A simple usage for handling websocket clients:

    from ws4py.client import WebSocketBaseClient
    from ws4py.manager import WebSocketManager

    m = WebSocketManager()

    class EchoClient(WebSocketBaseClient):
        def handshake_ok(self):
            m.add(self)  # register the client once the handshake is done

        def received_message(self, msg):
            print str(msg)

    m.start()

    client = EchoClient('ws://localhost:9000/ws')
    client.connect()

    m.join()  # blocks forever

Managers are not compulsory but hopefully will help your workflow. For clients, you can still rely on threaded, gevent or tornado based implementations of course.

class `ws4py.manager.``SelectPoller`(timeout=0.1)

  Bases: `object`

  A socket poller that uses the select implementation to determines which file descriptors have data available to read.

  It is available on all platforms.

  `release`()

    Cleanup resources.

  `register`(fd)

    Register a new file descriptor to be part of the select polling next time around.

  `unregister`(fd)

    Unregister the given file descriptor.

  `poll`()

    Polls once and returns a list of ready-to-be-read file descriptors.

class `ws4py.manager.``EPollPoller`(timeout=0.1)

  Bases: `object`

  An epoll poller that uses the `epoll` implementation to determines which file descriptors have data available to read.

  Available on Unix flavors mostly.

  `release`()

    Cleanup resources.

  `register`(fd)

    Register a new file descriptor to be part of the select polling next time around.

  `unregister`(fd)

    Unregister the given file descriptor.

  `poll`()

    Polls once and yields each ready-to-be-read file-descriptor

class `ws4py.manager.``KQueuePoller`(timeout=0.1)

  Bases: `object`

  An epoll poller that uses the `epoll` implementation to determines which file descriptors have data available to read.

  Available on Unix flavors mostly.

  `release`()

    Cleanup resources.

  `register`(fd)

    Register a new file descriptor to be part of the select polling next time around.

  `unregister`(fd)

    Unregister the given file descriptor.

  `poll`()

    Polls once and yields each ready-to-be-read file-descriptor

class `ws4py.manager.``WebSocketManager`(poller=None)

  Bases: `threading.Thread`

  An event-based websocket manager. By event-based, we mean that the websockets will be called when their sockets have data to be read from.

  The manager itself runs in its own thread as not to be the blocking mainloop of your application.

  The poller’s implementation is automatically chosen with `epoll` if available else `select` unless you provide your own `poller`.

  `add`(websocket)

    Manage a new websocket.

    First calls its `opened()` method and register its socket against the poller for reading events.

  `remove`(websocket)

    Remove the given `websocket` from the manager.

    This does not call its `closed()` method as it’s out-of-band by your application or from within the manager’s run loop.

  `stop`()

    Mark the manager as terminated and releases its resources.

  `run`()

    Manager’s mainloop executed from within a thread.

    Constantly poll for read events and, when available, call related websockets’ once method to read and process the incoming data.

    If the `once()` method returns a False value, its `terminate()` method is also applied to properly close the websocket and its socket is unregistered from the poller.

    Note that websocket shouldn’t take long to process their data or they will block the remaining websockets with data to be handled. As for what long means, it’s up to your requirements.

  `close_all`(code=1001, message='Server is shutting down')

    Execute the `close()` method of each registered websockets to initiate the closing handshake. It doesn’t wait for the handshake to complete properly.

  `broadcast`(message, binary=False)

    Broadcasts the given message to all registered websockets, at the time of the call.

    Broadcast may fail on a given registered peer but this is silent as it’s not the method’s purpose to handle websocket’s failures.

## `messaging` Module

class `ws4py.messaging.``Message`(opcode, data=b'', encoding='utf-8')

  Bases: `object`

  A message is a application level entity. It’s usually built from one or many frames. The protocol defines several kind of messages which are grouped into two sets:

  - data messages which can be text or binary typed
  - control messages which provide a mechanism to perform in-band control communication between peers

  The `opcode` indicates the message type and `data` is the possible message payload.

  The payload is held internally as a a `bytearray` as they are faster than pure strings for append operations.

  Unicode data will be encoded using the provided `encoding`.

  `single`(mask=False)

    Returns a frame bytes with the fin bit set and a random mask.

    If `mask` is set, automatically mask the frame using a generated 4-byte token.

  `fragment`(first=False, last=False, mask=False)

    Returns a `ws4py.framing.Frame` bytes.

    The behavior depends on the given flags:

    - `first`: the frame uses `self.opcode` else a continuation opcode
    - `last`: the frame has its `fin` bit set
    - `mask`: the frame is masked using a automatically generated 4-byte token
  `completed`

    Indicates the the message is complete, meaning the frame’s `fin` bit was set.

  `extend`(data)

    Add more `data` to the message.

class `ws4py.messaging.``TextMessage`(text=None)

  Bases: `ws4py.messaging.Message`

  `is_binary`
  `is_text`

class `ws4py.messaging.``BinaryMessage`(bytes=None)

  Bases: `ws4py.messaging.Message`

  `is_binary`
  `is_text`

class `ws4py.messaging.``CloseControlMessage`(code=1000, reason='')

  Bases: `ws4py.messaging.Message`

class `ws4py.messaging.``PingControlMessage`(data=None)

  Bases: `ws4py.messaging.Message`

class `ws4py.messaging.``PongControlMessage`(data)

  Bases: `ws4py.messaging.Message`

## `streaming` Module

class `ws4py.streaming.``Stream`(always_mask=False, expect_masking=True)

  Bases: `object`

  Represents a websocket stream of bytes flowing in and out.

  The stream doesn’t know about the data provider itself and doesn’t even know about sockets. Instead the stream simply yields for more bytes whenever it requires them. The stream owner is responsible to provide the stream with those bytes until a frame can be interpreted.

      1
      2
      3
      4
      5
      6
      7
      8
      9

      >>> s = Stream()
      >>> s.parser.send(BYTES)
      >>> s.has_messages
      False
      >>> s.parser.send(MORE_BYTES)
      >>> s.has_messages
      True
      >>> s.message
      <TextMessage ... >

  Set `always_mask` to mask all frames built.

  Set `expect_masking` to indicate masking will be checked on all parsed frames.

  `message` = None

    Parsed test or binary messages. Whenever the parser reads more bytes from a fragment message, those bytes are appended to the most recent message.

  `pings` = None

    Parsed ping control messages. They are instances of `ws4py.messaging.PingControlMessage`

  `pongs` = None

    Parsed pong control messages. They are instances of `ws4py.messaging.PongControlMessage`

  `closing` = None

    Parsed close control messsage. Instance of `ws4py.messaging.CloseControlMessage`

  `errors` = None

    Detected errors while parsing. Instances of `ws4py.messaging.CloseControlMessage`

  `parser`
  `text_message`(text)

    Returns a `ws4py.messaging.TextMessage` instance ready to be built. Convenience method so that the caller doesn’t need to import the `ws4py.messaging.TextMessage` class itself.

  `binary_message`(bytes)

    Returns a `ws4py.messaging.BinaryMessage` instance ready to be built. Convenience method so that the caller doesn’t need to import the `ws4py.messaging.BinaryMessage` class itself.

  `has_message`

    Checks if the stream has received any message which, if fragmented, is now completed.

  `close`(code=1000, reason='')

    Returns a close control message built from a `ws4py.messaging.CloseControlMessage` instance, using the given status `code` and `reason` message.

  `ping`(data='')

    Returns a ping control message built from a `ws4py.messaging.PingControlMessage` instance.

  `pong`(data='')

    Returns a ping control message built from a `ws4py.messaging.PongControlMessage` instance.

  `receiver`()

    Parser that keeps trying to interpret bytes it is fed with as incoming frames part of a message.

    Control message are single frames only while data messages, like text and binary, may be fragmented accross frames.

    The way it works is by instanciating a `wspy.framing.Frame` object, then running its parser generator which yields how much bytes it requires to performs its task. The stream parser yields this value to its caller and feeds the frame parser.

    When the frame parser raises `StopIteration`, the stream parser tries to make sense of the parsed frame. It dispatches the frame’s bytes to the most appropriate message type based on the frame’s opcode.

    Overall this makes the stream parser totally agonstic to the data provider.

## `utf8validator` Module

class `ws4py.utf8validator.``Utf8Validator`

  Bases: `object`

  Incremental UTF-8 validator with constant memory consumption (minimal state).

  Implements the algorithm “Flexible and Economical UTF-8 Decoder” by Bjoern Hoehrmann (http://bjoern.hoehrmann.de/utf-8/decoder/dfa/).

  `UTF8VALIDATOR_DFA` = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 9, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 8, 8, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 10, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 4, 3, 3, 11, 6, 6, 6, 5, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 0, 1, 2, 3, 5, 8, 7, 1, 1, 1, 4, 6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, 1, 3, 1, 1, 1, 1, 1, 3, 1, 3, 1, 1, 1, 1, 1, 1, 1, 3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
  `UTF8_ACCEPT` = 0
  `UTF8_REJECT` = 1
  `decode`(b)

    Eat one UTF-8 octet, and validate on the fly.

    Returns UTF8_ACCEPT when enough octets have been consumed, in which case self.codepoint contains the decoded Unicode code point.

    Returns UTF8_REJECT when invalid UTF-8 was encountered.

    Returns some other positive integer when more octets need to be eaten.

  `reset`()

    Reset validator to start new incremental UTF-8 decode/validation.

  `validate`(ba)

    Incrementally validate a chunk of bytes provided as bytearray.

    Will return a quad (valid?, endsOnCodePoint?, currentIndex, totalIndex).

    As soon as an octet is encountered which renders the octet sequence invalid, a quad with valid? == False is returned. currentIndex returns the index within the currently consumed chunk, and totalIndex the index within the total consumed sequence that was the point of bail out. When valid? == True, currentIndex will be len(ba) and totalIndex the total amount of consumed bytes.

## `websocket` Module

class `ws4py.websocket.``Heartbeat`(websocket, frequency=2.0)

  Bases: `threading.Thread`

  Runs at a periodic interval specified by frequency by sending an unsolicitated pong message to the connected peer.

  If the message fails to be sent and a socket error is raised, we close the websocket socket automatically, triggering the closed handler.

  `stop`()
  `run`()

    Method representing the thread’s activity.

    You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class `ws4py.websocket.``WebSocket`(sock, protocols=None, extensions=None, environ=None, heartbeat_freq=None)

  Bases: `object`

  The `sock` is an opened connection resulting from the websocket handshake.

  If `protocols` is provided, it is a list of protocols negotiated during the handshake as is `extensions`.

  If `environ` is provided, it is a copy of the WSGI environ dictionnary from the underlying WSGI server.

  `stream` = None

    Underlying websocket stream that performs the websocket parsing to high level objects. By default this stream never masks its messages. Clients using this class should set the `stream.always_mask` fields to `True` and `stream.expect_masking` fields to `False`.

  `protocols` = None

    List of protocols supported by this endpoint. Unused for now.

  `extensions` = None

    List of extensions supported by this endpoint. Unused for now.

  `sock` = None

    Underlying connection.

  `client_terminated` = None

    Indicates if the client has been marked as terminated.

  `server_terminated` = None

    Indicates if the server has been marked as terminated.

  `reading_buffer_size` = None

    Current connection reading buffer size.

  `environ` = None

    WSGI environ dictionary.

  `heartbeat_freq` = None

    At which interval the heartbeat will be running. Set this to 0 or None to disable it entirely.

  `local_address`

    Local endpoint address as a tuple

  `peer_address`

    Peer endpoint address as a tuple

  `opened`()

    Called by the server when the upgrade handshake has succeeded.

  `close`(code=1000, reason='')

    Call this method to initiate the websocket connection closing by sending a close frame to the connected peer. The `code` is the status code representing the termination’s reason.

    Once this method is called, the `server_terminated` attribute is set. Calling this method several times is safe as the closing frame will be sent only the first time.

    See also

    Defined Status Codes http://tools.ietf.org/html/rfc6455#section-7.4.1

  `closed`(code, reason=None)

    Called when the websocket stream and connection are finally closed. The provided `code` is status set by the other point and `reason` is a human readable message.

    See also

    Defined Status Codes http://tools.ietf.org/html/rfc6455#section-7.4.1

  `terminated`

    Returns `True` if both the client and server have been marked as terminated.

  `connection`
  `close_connection`()

    Shutdowns then closes the underlying connection.

  `ping`(message)

    Send a ping message to the remote peer. The given message must be a unicode string.

  `ponged`(pong)

    Pong message, as a `messaging.PongControlMessage` instance, received on the stream.

  `received_message`(message)

    Called whenever a complete `message`, binary or text, is received and ready for application’s processing.

    The passed message is an instance of `messaging.TextMessage` or `messaging.BinaryMessage`.

    Note

    You should override this method in your subclass.

  `unhandled_error`(error)

    Called whenever a socket, or an OS, error is trapped by ws4py but not managed by it. The given error is an instance of socket.error or OSError.

    Note however that application exceptions will not go through this handler. Instead, do make sure you protect your code appropriately in received_message or send.

    The default behaviour of this handler is to log the error with a message.

  `send`(payload, binary=False)

    Sends the given `payload` out.

    If `payload` is some bytes or a bytearray, then it is sent as a single message not fragmented.

    If `payload` is a generator, each chunk is sent as part of fragmented message.

    If `binary` is set, handles the payload as a binary message.

  `once`()

    Performs the operation of reading from the underlying connection in order to feed the stream of bytes.

    Because this needs to support SSL sockets, we must always read as much as might be in the socket at any given time, however process expects to have itself called with only a certain number of bytes at a time. That number is found in self.reading_buffer_size, so we read everything into our own buffer, and then from there feed self.process.

    Then the stream indicates whatever size must be read from the connection since it knows the frame payload length.

    It returns False if an error occurred at the socket level or during the bytes processing. Otherwise, it returns True.

  `terminate`()

    Completes the websocket by calling the closed method either using the received closing code and reason, or when none was received, using the special 1006 code.

    Finally close the underlying connection for good and cleanup resources by unsetting the environ and stream attributes.

  `process`(bytes)

    Takes some bytes and process them through the internal stream’s parser. If a message of any kind is found, performs one of these actions:

    - A closing message will initiate the closing handshake
    - Errors will initiate a closing handshake
    - A message will be passed to the `received_message` method
    - Pings will see pongs be sent automatically
    - Pongs will be passed to the `ponged` method

    The process should be terminated when this method returns `False`.

  `run`()

    Performs the operation of reading from the underlying connection in order to feed the stream of bytes.

    We start with a small size of two bytes to be read from the connection so that we can quickly parse an incoming frame header. Then the stream indicates whatever size must be read from the connection since it knows the frame payload length.

    Note that we perform some automatic opererations:

    - On a closing message, we respond with a closing message and finally close the connection
    - We respond to pings with pong messages.
    - Whenever an error is raised by the stream parsing, we initiate the closing of the connection with the appropiate error code.

    This method is blocking and should likely be run in a thread.

class `ws4py.websocket.``EchoWebSocket`(sock, protocols=None, extensions=None, environ=None, heartbeat_freq=None)

  Bases: `ws4py.websocket.WebSocket`

  The `sock` is an opened connection resulting from the websocket handshake.

  If `protocols` is provided, it is a list of protocols negotiated during the handshake as is `extensions`.

  If `environ` is provided, it is a copy of the WSGI environ dictionnary from the underlying WSGI server.

  `received_message`(message)

    Automatically sends back the provided `message` to its originating endpoint.

## Subpackages

- client Package
  - `client` Package
  - `geventclient` Module
  - `threadedclient` Module
  - `tornadoclient` Module
- server Package
  - `cherrypyserver` Module
  - `geventserver` Module
  - `wsgirefserver` Module
  - `wsgitutils` Module