Modules

stargate

WebSocket support for pyramid is implemented as a view which handles the upgrade request and a resource which manages the persistent connected clients. Both should be subclassed to provide send and receive functionality desired

stargate.is_websocket(context, request)

Custom predicate to denote a websocket handshake

See [predicate_arguments] and the custom_predicate key word argument to repoze.bfg.configuration.Configurator.add_view()

WebSocketView and WebSocketAwareResource are also available in this namespace, and this is the prefered location to use them from

stargate.resource

This module supplies a class which can be subclassed or mixed in and used in conjunction with WebSocketView. It provides functionality for adding and removing websockets as listeners for events

class stargate.resource.WebSocketAwareResource

An object in a pyramid:traversal graph that handles websockets

It is designed to be persistent and to route messages to attached clients

add_listener(ws)

Adds a eventlet.websocket.WebSocket the the set of listeners

listeners = None

A set of attached websockets

remove_listener(ws)

Removes ws from the set of listeners

send(message)

Sends message to all sockets in the set of listeners

It will clear up any websockets that are no longer connected

stargate.view

exception stargate.view.IncorrectlyConfigured

Exception to use in place of an assertion error

class stargate.view.WebSocketView(request)

A view for handling websockets

This view handles both the upgrade request and the ongoing socket communiction.

handle_upgrade()

Completes the upgrade request sent by the browser

Sends the headers required to set up to websocket connection back to the browser and then hands off to handle_websocket().

See [websocket_protocol]

Returns:webob.exc.HTTPBadRequest if handshake fails

handle_websocket(websocket)

Handles the connection after setup and handshake is done

Hands off to handler() until the socket is closed and then ensures a correct webob.Response is returned after the socket is closed

Parameters:websocket – A WebSocket

handler(websocket)

Handles the interaction with the websocket after being set up

This is the method to override in subclasses to receive and send messages over the websocket connection

Parameters:websocket – A WebSocket

stargate.factory

This module provides a paste [server_factory] to run pyramid inside an eventlet wsgi server

See Paste Deploy for more details.

stargate.factory.server_factory(global_conf, host, port)

Implements the [server_factory] api to provide an eventlet wsgi server

stargate.handshake

The handshake module contains implementations of different websocket spec versions’ handshakes.

The WebSocket spec had a major revision at version 76 [ws76] on May 6th 2010. This module is an attempt to insulate downstream application programmers from those changes

exception stargate.handshake.HandShakeFailed

Raised when the handshake fails

exception stargate.handshake.InvalidOrigin

Raised when the websocket request doesn’t have a valid origin

stargate.handshake.build_location_url(headers)

Construct a websocket url for given headers

Parameters:headers – webob.headers.EnvironHeaders

stargate.handshake.handshake_pre76(headers, base_response)

The websocket handshake as described in version 75 of the spec [ws75]

Parameters:

• headers – The request headers from websocket_handshake()
• base_response – The headers common across different spec versions

stargate.handshake.handshake_v76(headers, base_response)

The websocket handshake as described in version 76 of the spec [ws76]

Parameters:

• headers – The request headers from websocket_handshake()
• base_response – The headers common across different spec versions

stargate.handshake.websocket_handshake(headers, allowed_origins=None)

Perform the websocket handshake

This function does the part of the handshake that is common across spec versions and then hands off to the spec specific implementations.

See: handshake_pre76()

Parameters:headers (webob.headers.EnvironHeaders) – The websocket upgrade request headers (headers attribute from webob.Request) Raises :HandShakeFailed, InvalidOrigin Returns:A string to send back to the client

References

[server_factory]

(1, 2) http://pythonpaste.org/deploy/#paste-server-factory

[websocket_protocol]

http://en.wikipedia.org/wiki/Web_Sockets#WebSocket_Protocol_Handshake

[predicate_arguments]

http://docs.repoze.org/bfg/1.3/narr/views.html#predicate-arguments