bokeh.protocol¶
Implement and provide message protocols for communication between Bokeh Servers and clients.
-
class
bokeh.protocol.
Protocol
(version)¶ 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” -
assemble
(header_json, metadata_json, content_json)¶ Create a Message instance assembled from json fragments.
Parameters: - header_json (
JSON
) – - metadata_json (
JSON
) – - content_json (
JSON
) –
Returns: message
- header_json (
-
bokeh.protocol.exceptions¶
Provide named exceptions having to do with handling Bokeh Protocol messages.
-
exception
bokeh.protocol.exceptions.
MessageError
¶ 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
bokeh.protocol.exceptions.
ProtocolError
¶ Indicate an error in processing wire protocol fragments.
This exception indicates that decoded message fragments cannot be properly assembled.
-
exception
bokeh.protocol.exceptions.
ValidationError
¶ 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
bokeh.protocol.message.
Message
(header, metadata, content)¶ The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks
-
add_buffer
(buf_header, buf_payload)¶ 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)¶ 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)¶ 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)¶ 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
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ Write any buffer headers and payloads to the given connection.
Parameters: Returns: number of bytes sent
Return type:
-
bokeh.protocol.messages¶
-
bokeh.protocol.messages.
register
(cls)¶ 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
¶
-
class
bokeh.protocol.messages.ack.
ack_1
(header, metadata, content)¶ Define the
ACK
message (revision 1) for acknowledging successful client connection to a Bokeh server.The
content
fragment of for this message is empty.-
classmethod
create
(**metadata)¶ Create an
ACK
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
-
classmethod
EVENT
¶
ERROR
¶
-
class
bokeh.protocol.messages.error.
error_1
(header, metadata, content)¶ 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> }
-
classmethod
create
(request_id, text, **metadata)¶ Create an
ERROR
messageParameters: Any additional keyword arguments will be put into the message
metadata
fragment as-is.
-
classmethod
OK
¶
-
class
bokeh.protocol.messages.ok.
ok_1
(header, metadata, content)¶ Define the
OK
message (revision 1) for acknowledging successful handling of a previous message.The
content
fragment of for this message is empty.
PATCH-DOC
¶
-
class
bokeh.protocol.messages.patch_doc.
patch_doc_1
(header, metadata, content)¶ 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> }
-
apply_to_document
(doc, setter=None)¶
-
-
bokeh.protocol.messages.patch_doc.
process_document_events
(events, use_buffers=True)¶ 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
bokeh.protocol.messages.pull_doc_reply.
pull_doc_reply_1
(header, metadata, content)¶ 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> }
-
classmethod
create
(request_id, document, **metadata)¶ Create an
PULL-DOC-REPLY
messageParameters: Any additional keyword arguments will be put into the message
metadata
fragment as-is.
-
classmethod
PULL-DOC-REQ
¶
-
class
bokeh.protocol.messages.pull_doc_req.
pull_doc_req_1
(header, metadata, content)¶ Define the
PULL-DOC-REQ
message (revision 1) for requesting a Bokeh server reply with a new Bokeh Document.The
content
fragment of for this message is empty.-
classmethod
create
(**metadata)¶ Create an
PULL-DOC-REQ
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
-
classmethod
PUSH-DOC
¶
-
class
bokeh.protocol.messages.push_doc.
push_doc_1
(header, metadata, content)¶ Define the
PUSH-DOC
message (revision 1) for pushing Documents from clients to a Bokeh server.The
content
fragment of for this message is has the form:{ 'doc' : <Document JSON> }
-
classmethod
create
(document, **metadata)¶
-
push_to_document
(doc)¶ Raises: ProtocolError
-
classmethod
SERVER-INFO-REPLY
¶
-
class
bokeh.protocol.messages.server_info_reply.
server_info_reply_1
(header, metadata, content)¶ 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> } }
SERVER-INFO-REQ
¶
-
class
bokeh.protocol.messages.server_info_req.
server_info_req_1
(header, metadata, content)¶ Define the
SERVER-INFO-REQ
message (revision 1) for requesting a Bokeh server provide information about itself.The
content
fragment of for this message is empty.-
classmethod
create
(**metadata)¶ Create an
SERVER-INFO-REQ
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
-
classmethod
bokeh.protocol.receiver¶
Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.
-
class
bokeh.protocol.receiver.
Receiver
(protocol)¶ 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.-
consume
(*args, **kwargs)¶ 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
- fragment (
-
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
-
bokeh.protocol.versions.
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) ), }