bokeh.client.session#

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

使用案例#

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

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

class ClientSession(session_id: ID | None = None, websocket_url: str = 'ws://localhost: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://localhost:5006/ws', io_loop: IOLoop | None = None, arguments: dict[str, str] | None = None, max_message_size: int = 20971520)[源代码]#

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

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

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

Parameters:

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

请注意，只有在拉取新会话时才应提供这些参数。如果session_id不为None，或者已经存在一个具有session_id的会话，这些参数将不会产生任何效果。
max_message_size (int, optional) – 配置Tornado的最大WebSocket消息大小。 (默认值: 20 MB)

check_connection_errors() → None[source]#

当连接无法建立时，引发错误。

应在调用connect之后使用。

Returns:: 无

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

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

force_roundtrip() → None[source]#

强制向服务器发送往返请求/回复，有时需要避免竞争条件。主要用于测试。

在测试套件之外，此方法会损害性能，不应被需要。

Returns:: 无

pull() → None[source]#

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

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

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

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

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

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

注意

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

Parameters:: 文档 (Document, 可选) – 将与服务器文档保持同步的文档。如果为None，则使用session.document或创建一个新文档。

request_server_info() → ServerInfo[source]#

请求有关服务器的信息。

Returns:: 服务器属性的字典。

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

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

Parameters:

obj (UIElement 对象, 可选) – 要显示的布局（行/列）、绘图或小部件对象。该对象将被添加到会话的文档中。
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。

Parameters:

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

请注意，只有在拉取新会话时才应提供这些参数。如果session_id不为None，或者已经存在一个具有session_id的会话，这些参数将不会产生任何效果。
max_message_size (int, optional) – 配置Tornado的最大WebSocket消息大小。 (默认值: 20 MB)

Returns:

一个新的 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。

Parameters:

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

Returns:

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在浏览器中显示一个新的会话。

Parameters:

session_id (string, optional) – 会话的名称，None 表示自动生成一个随机的会话名称（默认值：None）
url – (str, 可选): 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'，则打开一个新窗口。