bokeh.protocol¶
Implement and provide message protocols for communication between Bokeh Servers and clients.
- class Protocol[source]¶
Provide a message factory for the Bokeh Server message protocol.
- assemble(header_json: str, metadata_json: str, content_json: str) bokeh.protocol.message.Message[Any] [source]¶
Create a Message instance assembled from json fragments.
- Parameters
header_json (
JSON
) –metadata_json (
JSON
) –content_json (
JSON
) –
- Returns
message
- create(msgtype: typing_extensions.Literal[ACK], **metadata: Any) bokeh.protocol.messages.ack.ack [source]¶
- create(msgtype: typing_extensions.Literal[ERROR], request_id: ID, text: str, **metadata: Any) bokeh.protocol.messages.error.error
- create(msgtype: typing_extensions.Literal[OK], request_id: ID, **metadata: Any) bokeh.protocol.messages.ok.ok
- create(msgtype: typing_extensions.Literal[PATCH - DOC], events: List[DocumentPatchedEvent], use_buffers: bool = ..., **metadata: Any) bokeh.protocol.messages.patch_doc.patch_doc
- create(msgtype: typing_extensions.Literal[PULL - DOC - REPLY], request_id: ID, document: Document, **metadata: Any) bokeh.protocol.messages.pull_doc_reply.pull_doc_reply
- create(msgtype: typing_extensions.Literal[PULL - DOC - REQ], **metadata: Any) bokeh.protocol.messages.pull_doc_req.pull_doc_req
- create(msgtype: typing_extensions.Literal[PUSH - DOC], document: Document, **metadata: Any) bokeh.protocol.messages.push_doc.push_doc
- create(msgtype: typing_extensions.Literal[SERVER - INFO - REPLY], request_id: ID, **metadata: Any) bokeh.protocol.messages.server_info_reply.server_info_reply
- create(msgtype: typing_extensions.Literal[SERVER - INFO - REQ], **metadata: Any) bokeh.protocol.messages.server_info_req.server_info_req
Create a new Message instance for the given type.
- Parameters
msgtype (str) –
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: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks
- __init__(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content) None [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: str, buf_payload: bytes) None [source]¶
Associate a buffer header and payload with this message.
- Parameters
buf_header (
JSON
) – a buffer headerbuf_payload (
JSON
or bytes) – a buffer payload
- Returns
None
- Raises
- classmethod assemble(header_json: str, metadata_json: str, content_json: str) bokeh.protocol.message.Message[bokeh.protocol.message.Content] [source]¶
Creates a new message, assembled from JSON fragments.
- Parameters
header_json (
JSON
) –metadata_json (
JSON
) –content_json (
JSON
) –
- Returns
Message subclass
- Raises
- assemble_buffer(buf_header: str, buf_payload: bytes) None [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 headerbuf_payload (
JSON
or bytes) – a buffer payload
- Returns
None
- Raises
- classmethod create_header(request_id: ID | None = None) Header [source]¶
Return a message header fragment dict.
- async send(conn: WebSocketClientConnectionWrapper) int [source]¶
Send the message on the given connection.
- Parameters
conn (WebSocketHandler) – a WebSocketHandler to send messages
- Returns
number of bytes sent
- Return type
bokeh.protocol.messages¶
- class ack(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
ACK
message for acknowledging successful client connection to a Bokeh server.The
content
fragment of for this message is empty.- classmethod create(**metadata: Any) bokeh.protocol.messages.ack.ack [source]¶
Create an
ACK
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
- class error(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
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> }
- classmethod create(request_id: ID, text: str, **metadata: Any) bokeh.protocol.messages.error.error [source]¶
Create an
ERROR
message- Parameters
Any additional keyword arguments will be put into the message
metadata
fragment as-is.
- class ok(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
OK
message for acknowledging successful handling of a previous message.The
content
fragment of for this message is empty.- classmethod create(request_id: ID, **metadata: Any) bokeh.protocol.messages.ok.ok [source]¶
Create an
OK
message- Parameters
request_id (str) – The message ID for the message the precipitated the OK.
Any additional keyword arguments will be put into the message
metadata
fragment as-is.
- class patch_doc(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
PATCH-DOC
message 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> }
- classmethod create(events: List[DocumentPatchedEvent], use_buffers: bool = True, **metadata: Any) patch_doc [source]¶
Create a
PATCH-DOC
message- Parameters
events (list) – A list of patch events to apply to a document
Any additional keyword arguments will be put into the message
metadata
fragment as-is.
- class pull_doc_reply(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
PULL-DOC-REPLY
message 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: ID, document: Document, **metadata: Any) pull_doc_reply [source]¶
Create an
PULL-DOC-REPLY
message- Parameters
Any additional keyword arguments will be put into the message
metadata
fragment as-is.
- class pull_doc_req(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
PULL-DOC-REQ
message for requesting a Bokeh server reply with a new Bokeh Document.The
content
fragment of for this message is empty.- classmethod create(**metadata: Any) bokeh.protocol.messages.pull_doc_req.pull_doc_req [source]¶
Create an
PULL-DOC-REQ
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
- class push_doc(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
PUSH-DOC
message for pushing Documents from clients to a Bokeh server.The
content
fragment of for this message is has the form:{ 'doc' : <Document JSON> }
- class server_info_reply(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
SERVER-INFO-REPLY
message 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> } }
- classmethod create(request_id: ID, **metadata: Any) bokeh.protocol.messages.server_info_reply.server_info_reply [source]¶
Create an
SERVER-INFO-REPLY
message- Parameters
request_id (str) – The message ID for the message that issues the info request
Any additional keyword arguments will be put into the message
metadata
fragment as-is.
- class server_info_req(header: bokeh.protocol.message.Header, metadata: Dict[str, Any], content: bokeh.protocol.message.Content)[source]¶
Define the
SERVER-INFO-REQ
message for requesting a Bokeh server provide information about itself.The
content
fragment of for this message is empty.- classmethod create(**metadata: Any) bokeh.protocol.messages.server_info_req.server_info_req [source]¶
Create an
SERVER-INFO-REQ
messageAny keyword arguments will be put into the message
metadata
fragment as-is.
bokeh.protocol.receiver¶
Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.
- class Receiver(protocol: 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.