bokeh.protocol¶
Implement and provide message protocols for communication between Bokeh Servers and clients.
-
class
Protocol
(version)[source]¶ Provide a message factory for a given version of the Bokeh Server message protocol.
Parameters: version (str) – a string identifying a protocol version, e.g. “1.0”
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.
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
- buf_header (
-
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
- header_json (
-
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
- buf_header (
-
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
-
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)
ACK
¶
EVENT
¶
ERROR
¶
-
class
error_1
(header, metadata, content)[source]¶ Define the
ERROR
message (revision 1) for reporting error conditions back to a Bokeh server.The
content
fragment of for this message is has the form:{ 'text' : <error message text> # this is optional 'traceback' : <traceback text> }
OK
¶
PATCH-DOC
¶
-
class
patch_doc_1
(header, metadata, content)[source]¶ Define the
PATCH-DOC
message (revision 1) for sending Document patch events between remote documents.The
content
fragment of for this message is has the form:{ 'events' : <protocol document events> 'references' : <model references> }
-
process_document_events
(events, use_buffers=True)[source]¶ Create a JSON string describing a patch to be applied as well as any optional buffers.
Parameters: events – list of events to be translated into patches Returns: JSON string which can be applied to make the given updates to obj as well as any optional buffers Return type: str, list
PULL-DOC-REPLY
¶
-
class
pull_doc_reply_1
(header, metadata, content)[source]¶ Define the
PULL-DOC-REPLY
message (revision 1) for replying to Document pull requests from clientsThe
content
fragment of for this message is has the form:{ 'doc' : <Document JSON> }
PULL-DOC-REQ
¶
PUSH-DOC
¶
SERVER-INFO-REPLY
¶
-
class
server_info_reply_1
(header, metadata, content)[source]¶ Define the
SERVER-INFO-REPLY
message (revision 1) for replying to Server info requests from clients.The
content
fragment of for this message is has the form:{ 'version_info' : { 'bokeh' : <bokeh library version> 'server' : <bokeh server version> } }
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
orValidationError
, 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.
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) ), }