Implement and provide message protocols for communication between Bokeh Servers and clients.
Protocol
Provide a message factory for the Bokeh Server message protocol.
assemble
Create a Message instance assembled from json fragments.
header_json (JSON) –
JSON
metadata_json (JSON) –
content_json (JSON) –
message
create
Create a new Message instance for the given type.
msgtype (str) –
Provide named exceptions having to do with handling Bokeh Protocol messages.
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.
ProtocolError
Indicate an error in processing wire protocol fragments.
This exception indicates that decoded message fragments cannot be properly assembled.
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.
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
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.
metadata
The content fragment is defined by the specific message type.
content
Message
The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks
__init__
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.
header (JSON-like) –
metadata (JSON-like) –
content (JSON-like) –
add_buffer
Associate a buffer header and payload with this message.
buf_header (JSON) – a buffer header
buf_payload (JSON or bytes) – a buffer payload
None
MessageError –
Creates a new message, assembled from JSON fragments.
Message subclass
assemble_buffer
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.
ProtocolError –
create_header
Return a message header fragment dict.
request_id (str or None) – Message ID of the message this message replies to
a message header
dict
send
Send the message on the given connection.
conn (WebSocketHandler) – a WebSocketHandler to send messages
number of bytes sent
int
write_buffers
Write any buffer headers and payloads to the given connection.
conn (object) – May be any object with a write_message method. Typically, a Tornado WSHandler or WebSocketClientConnection
write_message
WSHandler
WebSocketClientConnection
locked (bool) –
complete
Returns whether all required parts of a message are present.
True if the message is complete, False otherwise
bool
ACK
ack
Define the ACK message for acknowledging successful client connection to a Bokeh server.
The content fragment of for this message is empty.
Create an ACK message
Any keyword arguments will be put into the message metadata fragment as-is.
ERROR
error
Define the ERROR message 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> }
Create an ERROR message
request_id (str) – The message ID for the message the precipitated the error.
text (str) – The text of any error message or traceback, etc.
Any additional keyword arguments will be put into the message metadata fragment as-is.
OK
ok
Define the OK message for acknowledging successful handling of a previous message.
Create an OK message
request_id (str) – The message ID for the message the precipitated the OK.
PATCH-DOC
patch_doc
Define the PATCH-DOC message for sending Document patch events between remote documents.
{ 'events' : <protocol document events> 'references' : <model references> }
apply_to_document
Create a PATCH-DOC message
events (list) – A list of patch events to apply to a document
process_document_events
Create a JSON string describing a patch to be applied as well as any optional buffers.
events – list of events to be translated into patches
JSON string which can be applied to make the given updates to obj as well as any optional buffers
str, list
PULL-DOC-REPLY
pull_doc_reply
Define the PULL-DOC-REPLY message for replying to Document pull requests from clients
{ 'doc' : <Document JSON> }
Create an PULL-DOC-REPLY message
request_id (str) – The message ID for the message that issues the pull request
document (Document) – The Document to reply with
PULL-DOC-REQ
pull_doc_req
Define the PULL-DOC-REQ message for requesting a Bokeh server reply with a new Bokeh Document.
Create an PULL-DOC-REQ message
PUSH-DOC
push_doc
Define the PUSH-DOC message for pushing Documents from clients to a Bokeh server.
push_to_document
SERVER-INFO-REPLY
server_info_reply
Define the SERVER-INFO-REPLY message for replying to Server info requests from clients.
{ 'version_info' : { 'bokeh' : <bokeh library version> 'server' : <bokeh server version> } }
Create an SERVER-INFO-REPLY message
request_id (str) – The message ID for the message that issues the info request
SERVER-INFO-REQ
server_info_req
Define the SERVER-INFO-REQ message for requesting a Bokeh server provide information about itself.
Create an SERVER-INFO-REQ message
Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.
Receiver
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).
Configure a Receiver with a specific Bokeh protocol.
protocol (Protocol) – A Bokeh protocol object to use to assemble collected message fragments.
consume
Consume individual protocol message fragments.
fragment (JSON) – A message fragment to assemble. When a complete message is assembled, the receiver state will reset to begin consuming a new message.