bokeh.protocol¶

bokeh.protocol.exceptions¶

Provide named exceptions having to do with handling Bokeh Protocol messages.

exception MessageError[source]¶

Indicate an error in constructing a Bokeh Message object.

This exception usually indicates that the JSON fragments of a message cannot be decoded at all.

exception ProtocolError[source]¶

Indicate an error in processing wire protocol fragments.

This exception indicates that decoded message fragments cannot be properly assembled.

exception ValidationError[source]¶

Indicate an error validating wire protocol fragments.

This exception typically indicates that a binary message fragment was received when a text fragment was expected, or vice-versa.

bokeh.protocol.message¶

Provide a base class for all Bokeh Server Protocol message types.

Boker messages are comprised of a sequence of JSON fragments. Specified as Python JSON-like data, messages have the general form:

[
    # these are required
    b'{header}',        # serialized header dict
    b'{metadata}',      # serialized metadata dict
    b'{content},        # serialized content dict

    # these are optional, and come in pairs; header contains num_buffers
    b'{buf_header}',    # serialized buffer header dict
    b'array'            # raw buffer payload data
    ...
]

The header fragment will have the form:

header = {
    # these are required
    'msgid'       : <str> # a unique id for the message
    'msgtype'     : <str> # a message type, e.g. 'ACK', 'PATCH-DOC', etc

    # these are optional
    'num_buffers' : <int> # the number of additional buffers, if any
}

The metadata fragment may contain any arbitrary information. It is not processed by Bokeh for any purpose, but may be useful for external monitoring or instrumentation tools.

The content fragment is defined by the specific message type.

class Message(header, metadata, content)[source]¶

The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks

__init__(header, metadata, content)[source]¶

Initialize a new message from header, metadata, and content dictionaries.

To assemble a message from existing JSON fragments, use the assemble method.

To create new messages with automatically generated headers, use subclass create methods.

Parameters:	header (JSON-like) – metadata (JSON-like) – content (JSON-like) –

add_buffer(buf_header, buf_payload)[source]¶

Associate a buffer header and payload with this message.

Parameters:	buf_header (JSON) – a buffer header buf_payload (JSON or bytes) – a buffer payload
Returns:	None
Raises:	MessageError

classmethod assemble(header_json, metadata_json, content_json)[source]¶

Creates a new message, assembled from JSON fragments.

Parameters:	header_json (JSON) – metadata_json (JSON) – content_json (JSON) –
Returns:	Message subclass
Raises:	MessageError

assemble_buffer(buf_header, buf_payload)[source]¶

Add a buffer header and payload that we read from the socket.

This differs from add_buffer() because we’re validating vs. the header’s num_buffers, instead of filling in the header.

Parameters:	buf_header (JSON) – a buffer header buf_payload (JSON or bytes) – a buffer payload
Returns:	None
Raises:	ProtocolError

classmethod create_header(request_id=None)[source]¶

Return a message header fragment dict.

Parameters:	request_id (str or None) – Message ID of the message this message replies to
Returns:	a message header
Return type:	dict

send(conn)[source]¶

Send the message on the given connection.

Parameters:	conn (WebSocketHandler) – a WebSocketHandler to send messages
Returns:	number of bytes sent
Return type:	int

write_buffers(conn, locked=True)[source]¶

Write any buffer headers and payloads to the given connection.

Parameters:	conn (object) – May be any object with a write_message method. Typically, a Tornado WSHandler or WebSocketClientConnection locked (bool) –
Returns:	number of bytes sent
Return type:	int

complete¶

Returns whether all required parts of a message are present.

Returns:	True if the message is complete, False otherwise
Return type:	bool

bokeh.protocol.messages¶

register(cls)[source]¶

Decorator to add a Message (and its revision) to the Protocol index.

Example

@register
class some_msg_1(Message):

    msgtype  = 'SOME-MSG'
    revision = 1

    @classmethod
    def create(cls, **metadata):
        header = cls.create_header()
        content = {}
        return cls(header, metadata, content)

bokeh.protocol.receiver¶

Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.

class Receiver(protocol)[source]¶

Receive wire message fragments and assemble complete Bokeh server message objects.

On MessageError or ValidationError, the receiver will reset its state and attempt to consume a new message.

The fragment received can be either bytes or unicode, depending on the transport’s semantics (WebSocket allows both).

[
    # these are required
    b'{header}',        # serialized header dict
    b'{metadata}',      # serialized metadata dict
    b'{content},        # serialized content dict

    # these are optional, and come in pairs; header contains num_buffers
    b'{buf_header}',    # serialized buffer header dict
    b'array'            # raw buffer payload data
    ...
]

The header fragment will have the form:

header = {
    # these are required
    'msgid'       : <str> # a unique id for the message
    'msgtype'     : <str> # a message type, e.g. 'ACK', 'PATCH-DOC', etc

    # these are optional
    'num_buffers' : <int> # the number of additional buffers, if any
}

The metadata fragment may contain any arbitrary information. It is not processed by Bokeh for any purpose, but may be useful for external monitoring or instrumentation tools.

The content fragment is defined by the specific message type.

__init__(protocol)[source]¶

Configure a Receiver with a specific Bokeh protocol version.

Parameters:	protocol (Protocol) – A Bokeh protocol object to use to assemble colleted message fragments.

consume(fragment, callback=None)[source]¶

Consume individual protocol message fragments.

Parameters:	fragment (JSON) – A message fragment to assemble. When a complete message is assembled, the receiver state will reset to begin consuming a new message. callback (callable, optional) – Argument required by return_future decorator

bokeh.protocol.versions¶

Provide definitions for Bokeh WebSocket prototol versions.

A protocol specification is a sequence of tuples of the form:

(
    (<message_type>, <revision>),
    (<message_type>, <revision>),
    ...
)

Where <message_type> is string that identifies a message type, e.g, 'ACK', 'SERVER-INFO-REQ', etc. and <revision> is an integer that identifies what revision of the message this version of the protocol uses.

A protocol version is a string of the form '<major>.<minor>'. The guidelines for updating the major or minor version are:

<major>

bump when new messages are added or deleted (and reset minor version to zero)

<minor>

bump when existing message revisions change

spec¶

A mapping of protocol versions to protocol specifications.

{
    "1.0" : (
        ("ACK", 1),
        ("OK", 1),
        ("ERROR", 1),
        ("EVENT", 1),
        ('SERVER-INFO-REPLY', 1),
        ('SERVER-INFO-REQ', 1),
        ('PULL-DOC-REQ', 1),
        ('PULL-DOC-REPLY', 1),
        ('PUSH-DOC', 1),
        ('PATCH-DOC', 1)
    ),
}