bokeh.protocol

实现并提供用于Bokeh服务器和客户端之间通信的消息协议。

class Protocol

为Bokeh服务器消息协议提供一个消息工厂。

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

创建一个从json片段组装的消息实例。

Parameters:

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

Returns:

消息

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

为给定类型创建一个新的消息实例。

Parameters:

msgtype (str)

bokeh.protocol.exceptions

提供与处理Bokeh协议消息相关的命名异常。

exception MessageError

指示在构建Bokeh消息对象时出现错误。

此异常通常表示消息的JSON片段无法被解码。

exception ProtocolError

指示处理有线协议片段时出现错误。

此异常表示解码后的消息片段无法正确组装。

exception ValidationError

指示验证线路协议片段时出现错误。

此异常通常表示在预期接收文本片段时收到了二进制消息片段，反之亦然。

bokeh.protocol.message

为所有Bokeh服务器协议消息类型提供一个基类。

Boker 消息由一系列 JSON 片段组成。指定为类似 Python 的 JSON 数据，消息的一般形式为：

[
    # 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
    ...
]

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
}

metadata 片段可以包含任何任意信息。Bokeh 不会对其进行任何处理，但可能对外部监控或工具有用。

content 片段由特定的消息类型定义。

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

Message基类封装了创建、组装和验证Bokeh服务器消息的完整性。此外，它还提供了钩子

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

从头部、元数据和内容字典初始化一个新消息。

要从现有的JSON片段组装消息，请使用assemble方法。

要创建带有自动生成标题的新消息，请使用子类 create 方法。

Parameters:

• 头部 (类似JSON)

• 元数据 (类似JSON)

• 内容 (类似JSON)

add_buffer(buffer: Buffer) → None

将缓冲区头和有效负载与此消息关联。

Parameters:

buffer (Buffer) – 一个缓冲区

Returns:

无

Raises:

MessageError –

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

从JSON片段中创建一个新消息。

Parameters:

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

Returns:

消息子类

Raises:

MessageError –

assemble_buffer(buf_header: BufferHeader, buf_payload: bytes) → None

添加我们从套接字读取的缓冲头和数据负载。

这与 add_buffer() 不同，因为我们正在根据头部的 num_buffers 进行验证，而不是填充头部。

Parameters:

• buf_header (JSON) – 一个缓冲区头

• buf_payload (JSON 或 bytes) – 一个缓冲区的负载

Returns:

无

Raises:

ProtocolError –

classmethod create_header(request_id: ID | None = None) → Header

返回一个消息头片段字典。

Parameters:

request_id (str 或 None) – 此消息回复的消息的消息ID

Returns:

消息头

Return type:

dict

async send(conn: WebSocketClientConnectionWrapper) → int

在给定的连接上发送消息。

Parameters:

conn (WebSocketHandler) – 用于发送消息的WebSocketHandler

Returns:

发送的字节数

Return type:

int

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

将任何缓冲区头和有效载荷写入给定的连接。

Parameters:

• conn (object) – 可以是任何具有 write_message 方法的对象。通常， 是一个 Tornado WSHandler 或 WebSocketClientConnection

• 锁定 (bool)

Returns:

发送的字节数

Return type:

int

property complete: bool

返回消息的所有必需部分是否都存在。

Returns:

如果消息完整则为True，否则为False

Return type:

bool

bokeh.protocol.messages

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

定义ACK消息，用于确认客户端成功连接到Bokeh服务器。

此消息的content片段为空。

classmethod create(**metadata: Any) → ack

创建一个ACK消息

任何关键字参数都将原样放入消息的 metadata 片段中。

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

定义ERROR消息，用于将错误情况报告回Bokeh服务器。

此消息的 content 片段具有以下形式：

{
    'text'      : <error message text>

    # this is optional
    'traceback' : <traceback text>
}

classmethod create(request_id: ID, text: str, **metadata: Any) → error

创建一个ERROR消息

Parameters:

• request_id (str) – 导致错误的消息的消息ID。

• 文本 (str) – 任何错误信息或回溯等的文本。

任何额外的关键字参数将直接放入消息的 metadata 片段中。

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

定义OK消息，用于确认成功处理了前一条消息。

此消息的content片段为空。

classmethod create(request_id: ID, **metadata: Any) → ok

创建一个OK消息

Parameters:

request_id (str) – 导致OK的消息的消息ID。

任何额外的关键字参数将直接放入消息的metadata片段中。

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

定义PATCH-DOC消息，用于在远程文档之间发送文档补丁事件。

此消息的 content 片段具有以下形式：

{
    '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

创建一个PATCH-DOC消息

Parameters:

events (list) – 要应用于文档的补丁事件列表

任何额外的关键字参数将直接放入消息的 metadata 片段中。

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

定义PULL-DOC-REPLY消息，用于回复客户端的文档拉取请求

此消息的 content 片段具有以下形式：

{
    'doc' : <Document JSON>
}

classmethod create(request_id: ID, document: Document, **metadata: Any) → pull_doc_reply

创建一个PULL-DOC-REPLY消息

Parameters:

• request_id (str) – 发出拉取请求的消息的消息ID

• 文档 (Document) – 用于回复的文档

任何额外的关键字参数将直接放入消息的metadata片段中。

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

定义PULL-DOC-REQ消息，用于请求Bokeh服务器回复一个新的Bokeh文档。

此消息的content片段为空。

classmethod create(**metadata: Any) → pull_doc_req

创建一个PULL-DOC-REQ消息

任何关键字参数都将原样放入消息的 metadata 片段中。

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

定义PUSH-DOC消息，用于将文档从客户端推送到Bokeh服务器。

此消息的 content 片段具有以下形式：

{
    '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)

定义SERVER-INFO-REPLY消息，用于回复来自客户端的服务器信息请求。

此消息的 content 片段具有以下形式：

{
    'version_info' : {
        'bokeh'  : <bokeh library version>
        'server' : <bokeh server version>
    }
}

classmethod create(request_id: ID, **metadata: Any) → server_info_reply

创建一个SERVER-INFO-REPLY消息

Parameters:

request_id (str) – 发出信息请求的消息ID

任何额外的关键字参数将直接放入消息的metadata片段中。

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

定义SERVER-INFO-REQ消息，用于请求Bokeh服务器提供有关其自身的信息。

此消息的content片段为空。

classmethod create(**metadata: Any) → server_info_req

创建一个SERVER-INFO-REQ消息

任何关键字参数都将原样放入消息的 metadata 片段中。

bokeh.protocol.receiver

将WebSocket有线消息片段组装成可以处理的完整Bokeh服务器消息对象。

class Receiver(protocol: 协议)

接收有线消息片段并组装完整的Bokeh服务器消息对象。

在MessageError或ValidationError时，接收器将重置其状态并尝试消费新消息。

接收到的片段可以是字节或unicode，具体取决于传输的语义（WebSocket允许两者）。

[
    # 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
    ...
]

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
}

metadata 片段可以包含任何任意信息。Bokeh 不会对其进行任何处理，但可能对外部监控或工具有用。

content 片段由特定的消息类型定义。

__init__(protocol: 协议) → None

配置一个具有特定Bokeh协议的接收器。

Parameters:

protocol (Protocol) – 用于组装收集到的消息片段的Bokeh协议对象。

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

消费单个协议消息片段。

Parameters:

fragment (JSON) – 要组装的消息片段。当完整消息被组装时，接收者状态将重置以开始消费新消息。