bokeh.client.session#

提供一个会话对象，用于在外部 Python 客户端中为 Bokeh 服务器服务 Bokeh 文档。

用例#

客户端会话有两个主要用途

在 Bokeh 服务器应用程序周围实施自动化测试基础设施。
在传递到特定查看器之前，创建和自定义 Bokeh 服务器应用程序的特定会话（在 *Bokeh 服务器中运行*)。

class ClientSession(session_id: ID | None = None, websocket_url: str = 'ws://127.0.0.1:5006/ws', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520)[source]#

表示与服务器端会话的 websocket 连接。

每个服务器会话存储一个文档，该文档与该 ClientSession 实例的相应文档保持同步。连接双方上的更新将自动传播到另一方，只要连接处于打开状态。

ClientSession 对象可以用作上下文管理器（通常应该这样做），以便会话正确关闭

with pull_session(url=app_url) as mysession:
    # customize session here
    script = server_session(session_id=mysession.id, url=app_url)
    return render_template("embed.html", script=script, template="Flask")

如果您不以这种方式使用 ClientSession，则需要确保调用 mysession.close()。

__init__(session_id: ID | None = None, websocket_url: str = 'ws://127.0.0.1:5006/ws', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520)[source]#

连接到服务器上的特定命名会话。

创建会话后，始终立即调用 pull() 或 push()（在调用这些函数之前，session.document 将为 None）。

push_session() 和 pull_session() 函数将构造一个 ClientSession，并在一步中进行推送或拉取，因此它们是获取 ClientSession 的好方法。

参数：

session_id (str) – 会话的名称，或者为 None 以生成一个
websocket_url (str) – 要连接到的 Websocket URL
io_loop (IOLoop, 可选) – 用于 websocket 的 IOLoop
arguments (dict[str, str], 可选) –
要作为 HTTP 请求参数传递给 Bokeh 应用程序代码的键值对字典（默认值：None）

请注意，仅当拉取新会话时才应提供此参数。如果 session_id 不为 None，或者已经存在具有 session_id 的会话，则这些参数将无效。
max_message_size (int, 可选) – 配置 Tornado 最大 websocket 消息大小。（默认值：20 MB）

check_connection_errors() → None[source]#

如果连接未建立，则引发错误。

应该在调用 connect 后使用。

返回:: None

close(why: str = 'closed') → None[source]#: 关闭与服务器的连接。

connect() → None[source]#: 连接到配置 URL 上的 Bokeh 服务器。

force_roundtrip() → None[source]#

强制与服务器进行一次往返请求/回复，有时需要避免竞争条件。主要用于测试。

在测试套件之外，此方法会影响性能，通常不需要。

返回:: None

pull() → None[source]#

获取服务器的状态并将其设置为 session.document。

如果此方法被多次调用，session.document 将是相同的对象实例，但其内容会被覆盖。

在拉取之前会自动调用 connect()。

push(document: Document | None = None) → None[source]#

将给定的文档推送到服务器并将其记录为 session.document。

如果此方法被多次调用，则文档必须相同（或为 None 表示 session.document）。

注意

在推送之前会自动调用 connect()。

参数：: document (Document, optional) – 将与服务器文档保持同步的文档。None 表示使用 session.document 或创建一个新文档。

request_server_info() → ServerInfo[source]#

请求有关服务器的信息。

返回:: 一个包含服务器属性的字典。

show(obj: UIElement | None = None, browser: str | None = None, new: Literal['tab', 'window'] = 'tab') → None[source]#

打开一个显示此会话的浏览器。

参数：

obj (UIElement object, optional) – 要显示的布局（行/列）、绘图或小部件对象。该对象将被添加到会话的文档中。
browser (str, optional) – 要显示的浏览器（默认：None）。对于支持此功能的系统，browser 参数允许指定要显示的浏览器，例如“safari”、“firefox”、“opera”、“windows-default”（有关详细信息，请参阅标准库中的 webbrowser 模块文档）。
new (str, optional) – 新文件输出模式（默认：“tab”）。对于基于文件的输出，打开或提升显示当前输出文件的浏览器窗口。如果 new 为 ‘tab’，则打开一个新标签页。如果 new 为 ‘window’，则打开一个新窗口。

property connected: bool#: 此会话当前是否已连接。

property document: Document#

一个 Document，它将与服务器上的相应 Document 保持同步。

此值在 pull() 或 push() 成功后初始化。在此之前，它将为 None。

property id: ID#: 此会话的唯一 ID。

property token: str#: 用于对会话进行身份验证的 JWT 令牌。

pull_session(session_id: ID | None = None, url: str = 'default', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520) → ClientSession[source]#

通过加载当前服务器端文档来创建一个会话。

session.document 将是一个从服务器加载的新文档。在与服务器的连接保持打开状态时，在服务器端所做的更改将应用于此文档，并且在客户端所做的更改将同步到服务器。

如果您不打算修改 session.document，那么您可能不需要使用此函数；相反，您可以直接 show_session() 或 server_session()，而无需先将会话的文档下载到您的进程中。如果您不需要下载会话，那么避免下载会话效率更高。

在生产环境中，session_id 应该为每个浏览器标签页唯一，这样可以防止用户相互覆盖。使用可预测的会话 ID 或在用户之间共享会话 ID 既不可扩展也不安全。

对于在单台机器上运行的笔记本，为了方便起见，session_id 可以是类似 "default" 的可读文本。

如果您允许 pull_session() 生成一个唯一的 session_id，则可以使用返回的 ClientSession 上的 id 属性获取生成的 ID。

参数：

session_id (string, optional) – 会话的名称，None 表示自动生成一个随机名称（默认：None）
url – (str, optional): Bokeh 服务器上 Bokeh 应用程序的 URL，也可以是 “default”，这将连接到默认应用程序 URL
io_loop (tornado.ioloop.IOLoop, optional) – 用于 websocket 的 IOLoop
arguments (dict[str, str], 可选) –
要作为 HTTP 请求参数传递给 Bokeh 应用程序代码的键值对字典（默认值：None）

请注意，仅当拉取新会话时才应提供此参数。如果 session_id 不为 None，或者已经存在具有 session_id 的会话，则这些参数将无效。
max_message_size (int, 可选) – 配置 Tornado 最大 websocket 消息大小。（默认值：20 MB）

返回:

一个连接到服务器的新 ClientSession

Return type:

ClientSession

push_session(document: Document, session_id: ID | None = None, url: str = 'default', io_loop: IOLoop | None = None, max_message_size: int = 20971520) → ClientSession[source]#

通过将给定文档推送到服务器来创建一个会话，覆盖任何现有的服务器端文档。

返回的会话中的 session.document 将是您提供的文档。在与服务器的连接保持打开状态时，在服务器端所做的更改将应用于此文档，并且在客户端所做的更改将同步到服务器。

在生产环境中，session_id 应该为每个浏览器标签页唯一，这样可以防止用户相互覆盖。使用可预测的会话 ID 或在用户之间共享会话 ID 既不可扩展也不安全。

对于在单台机器上运行的笔记本，为了方便起见，session_id 可以是类似 "default" 的可读文本。

如果您允许 push_session() 生成一个唯一的 session_id，则可以使用返回的 ClientSession 上的 id 属性获取生成的 ID。

参数：

document – (bokeh.document.Document) 要推送并设置为 session.document 的文档
session_id – (string, optional) 会话的名称，None 表示自动生成一个随机名称（默认：None）
url – (str, optional): Bokeh 服务器上 Bokeh 应用程序的 URL，也可以是 “default”，这将连接到默认应用程序 URL
io_loop – (tornado.ioloop.IOLoop, optional) 用于 websocket 的 IOLoop
max_message_size (int, 可选) – 配置 Tornado 最大 websocket 消息大小。（默认值：20 MB）

返回:

ClientSession: 一个连接到服务器的新 ClientSession

show_session(session_id: ID | None = None, url: str = 'default', session: ClientSession | None = None, browser: str | None = None, new: Literal['same', 'window', 'tab'] = 'tab', controller: BrowserLike | None = None) → None[source]#

在浏览器中打开显示会话文档的页面。

如果你从 pull_session() 或 push_session 获取了会话，你可以使用 show_session(session=mysession)。如果你不需要自己打开与服务器的连接，你可以在浏览器中显示新会话，只需提供 url。

参数：

session_id (string, optional) – 会话的名称，None 表示自动生成一个随机名称（默认：None）
url – (str, optional): Bokeh 服务器上 Bokeh 应用程序的 URL，也可以是 “default”，这将连接到默认应用程序 URL
session (ClientSession, optional) – 从中获取会话 ID 和服务器 URL 的会话。如果你指定了它，你就无需指定 session_id 和 url。
browser (str, optional) – 要显示的浏览器（默认：None）。对于支持此功能的系统，browser 参数允许指定要显示的浏览器，例如“safari”、“firefox”、“opera”、“windows-default”（有关详细信息，请参阅标准库中的 webbrowser 模块文档）。
new (str, optional) – 新文件输出模式（默认：“tab”）。对于基于文件的输出，打开或提升显示当前输出文件的浏览器窗口。如果 new 为 ‘tab’，则打开一个新标签页。如果 new 为 ‘window’，则打开一个新窗口。