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)

返回:

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

为给定类型创建新的 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) – 一个缓冲区

返回:

None

引发:

MessageError –

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

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

参数:

• header_json (JSON)

• metadata_json (JSON)

• content_json (JSON)

返回:

Message 子类

引发:

MessageError –

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

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

这与 add_buffer() 的不同之处在于，我们正在根据标头的 num_buffers 进行验证，而不是填写标头。

参数:

• buf_header (JSON) – 缓冲区标头

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

返回:

None

引发:

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)

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

此消息的 content 片段为空。

类方法 create(**metadata: Any) → ack

创建一个 ACK 消息

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

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

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

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

{
    'text'      : <error message text>

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

类方法 create(request_id: ID, text: str, **metadata: Any) → error

创建一个 ERROR 消息

参数:

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

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

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

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

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

此消息的 content 片段为空。

类方法 create(request_id: ID, **metadata: Any) → ok

创建一个 OK 消息

参数:

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

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

类 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

类方法 create(events: list[DocumentPatchedEvent], **metadata: Any) → patch_doc

创建一个 PATCH-DOC 消息

参数:

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

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

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

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

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

{
    'doc' : <Document JSON>
}

类方法 create(request_id: ID, document: Document, **metadata: Any) → pull_doc_reply

创建一个 PULL-DOC-REPLY 消息

参数:

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

• document (Document) – 要回复的文档

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

类 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

引发:

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)

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

此消息的 content 片段为空。

classmethod create(**metadata: Any) → server_info_req

创建 SERVER-INFO-REQ 消息

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

bokeh.protocol.receiver

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

class Receiver(protocol: Protocol)

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

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

接收到的 fragment 可以是字节或 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 协议配置 Receiver。

参数:

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

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

消费单个协议消息片段。

参数:

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