bokeh.protocol

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

class Protocol

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

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

创建从 JSON 片段组装而成的 Message 实例。

参数：

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

返回值：

消息

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

为给定类型创建新的 Message 实例。

参数：

msgtype (str)

bokeh.protocol.exceptions

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

exception MessageError

指示构建 Bokeh Message 对象时出错。

此异常通常表示消息的 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

从 header、metadata 和 content 字典初始化新消息。

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

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

参数：

• header (类 JSON)

• metadata (类 JSON)

• content (类 JSON)

add_buffer(buffer: Buffer) → None

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

参数：

buffer (Buffer) – 缓冲区

返回值：

无

引发:

MessageError –

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

创建一个新消息，由 JSON 片段组装而成。

参数：

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

返回值：

消息子类

引发:

MessageError –

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

添加我们从套接字读取的缓冲区头和有效负载。

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

参数：

• buf_header (JSON) – 缓冲区头

• buf_payload (JSON 或 bytes) – 缓冲区有效负载

返回值：

无

引发:

ProtocolError –

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

返回消息头片段字典。

参数：

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

返回值：

消息头

返回类型:

dict

async send(conn: WebSocketClientConnectionWrapper) → int

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

参数：

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

返回值：

发送的字节数

返回类型:

int

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

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

参数：

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

• locked (bool)

返回值：

发送的字节数

返回类型:

int

property complete: bool

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

返回值：

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

返回类型:

bool

bokeh.protocol.messages

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

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

此消息的content片段为空。

classmethod create(**metadata: Any) → ack

创建一个ACK消息

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

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

定义用于将错误条件报告回 Bokeh 服务器的ERROR消息。

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

{
    'text'      : <error message text>

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

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

创建一个ERROR消息

参数：

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

• text (str) – 任何错误消息或跟踪回溯等的文本。

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

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

定义用于确认先前消息成功处理的OK消息。

此消息的content片段为空。

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

创建一个OK消息

参数：

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消息

参数：

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消息

参数：

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

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

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

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

定义用于请求 Bokeh 服务器使用新的 Bokeh 文档进行回复的 PULL-DOC-REQ 消息。

此消息的content片段为空。

classmethod create(**metadata: Any) → pull_doc_req

创建 PULL-DOC-REQ 消息

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

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

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

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

{
    'doc' : <Document JSON>
}

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

push_to_document(doc: Document) → None

引发:

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 消息

参数：

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

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

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

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

此消息的content片段为空。

classmethod create(**metadata: Any) → server_info_req

创建 SERVER-INFO-REQ 消息

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

bokeh.protocol.receiver

将 WebSocket 线路消息片段组装成完整的 Bokeh 服务器消息对象，以便进行处理。

class Receiver(protocol: 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: Protocol) → None

使用特定的 Bokeh 协议配置接收器。

参数：

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

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

使用单个协议消息片段。

参数：

fragment (JSON) – 要组装的消息片段。当组装完成一条完整的消息时，接收器状态将重置以开始使用新消息。