bokeh.protocol

Implement and provide message protocols for communication between Bokeh Servers and clients.

class Protocol

Provide a message factory for the Bokeh Server message protocol.

assemble(header_json: str, metadata_json: str, content_json: str) → Message[Any]

Create a Message instance assembled from json fragments.

Parameters:

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

Returns:

message

create(msgtype: Literal['ACK'], **metadata: Any) → ack

create(msgtype: Literal['ERROR'], request_id: ID, text: str, **metadata: Any) → error

create(msgtype: Literal['OK'], request_id: ID, **metadata: Any) → ok

create(msgtype: Literal['PATCH-DOC'], events: list[DocumentPatchedEvent], **metadata: Any) → patch_doc

create(msgtype: Literal['PULL-DOC-REPLY'], request_id: ID, document: Document, **metadata: Any) → pull_doc_reply

create(msgtype: Literal['PULL-DOC-REQ'], **metadata: Any) → pull_doc_req

create(msgtype: Literal['PUSH-DOC'], document: Document, **metadata: Any) → push_doc

create(msgtype: Literal['SERVER-INFO-REPLY'], request_id: ID, **metadata: Any) → server_info_reply

create(msgtype: Literal['SERVER-INFO-REQ'], **metadata: Any) → 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

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

Indicate an error in processing wire protocol fragments.

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

exception 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 Message(header: Header, metadata: dict[str, Any], content: Content)

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

__init__(header: Header, metadata: dict[str, Any], content: Content) → None

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(buffer: Buffer) → None

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: str, metadata_json: str, content_json: str) → Message[Content]

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: BufferHeader, buf_payload: bytes) → None

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: ID | None = None) → Header

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

async send(conn: WebSocketClientConnectionWrapper) → int

Send the message on the given connection.

Parameters:

conn (WebSocketHandler) – a WebSocketHandler to send messages

Returns:

number of bytes sent

Return type:

int

async write_buffers(conn: WebSocketClientConnectionWrapper, locked: bool = True) → int

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

property complete: bool

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

class ack(header: Header, metadata: dict[str, Any], content: Content)

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) → ack

Create an ACK message

Any keyword arguments will be put into the message metadata fragment as-is.

class error(header: Header, metadata: dict[str, Any], content: Content)

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) → error

Create an ERROR message

Parameters:

• 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.

class ok(header: Header, metadata: dict[str, Any], content: Content)

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) → ok

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: Header, metadata: dict[str, Any], content: Content)

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>
}

apply_to_document(doc: Document, setter: Setter | None = None) → None

classmethod create(events: list[DocumentPatchedEvent], **metadata: Any) → patch_doc

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: Header, metadata: dict[str, Any], content: Content)

Define the PULL-DOC-REPLY message for replying to Document pull requests from clients

The 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

Create an PULL-DOC-REPLY message

Parameters:

• request_id (str) – The message ID for the message that issues the pull request

• document (Document) – The Document to reply with

Any additional keyword arguments will be put into the message metadata fragment as-is.

class pull_doc_req(header: Header, metadata: dict[str, Any], content: Content)

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) → pull_doc_req

Create an PULL-DOC-REQ message

Any keyword arguments will be put into the message metadata fragment as-is.

class push_doc(header: Header, metadata: dict[str, Any], content: Content)

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>
}

classmethod create(document: Document, **metadata: Any) → push_doc

push_to_document(doc: Document) → None

Raises:

ProtocolError –

class server_info_reply(header: Header, metadata: dict[str, Any], content: Content)

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) → server_info_reply

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: Header, metadata: dict[str, Any], content: Content)

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) → server_info_req

Create an SERVER-INFO-REQ message

Any 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)

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: Protocol) → None

Configure a Receiver with a specific Bokeh protocol.

Parameters:

protocol (Protocol) – A Bokeh protocol object to use to assemble collected message fragments.

async consume(fragment: str | bytes) → Message[Any] | None

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.