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 连接。

每个服务器会话存储一个文档 (Document)，该文档与此 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, 可选) – 将与服务器文档保持同步的文档。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 对象, 可选) – 要显示的布局 (Row/Column)、绘图 (Plot) 或 Widget 对象。该对象将被添加到会话的文档中。
browser (str, 可选) – 要使用的浏览器 (默认值: None)。对于支持它的系统，browser 参数允许指定要显示的浏览器，例如 “safari”、“firefox”、“opera”、“windows-default”（有关更多详细信息，请参阅标准库中的 webbrowser 模块文档）。
new (str, 可选) – 新的文件输出模式 (默认值: “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, 可选) – 会话的名称，如果为 None 则自动生成一个随机名称 (默认值: None)
url – (str, 可选): Bokeh 服务器上 Bokeh 应用程序的 URL，也可以是 “default”，它将连接到默认应用程序 URL
io_loop (tornado.ioloop.IOLoop, 可选) – 用于 websocket 的 IOLoop
arguments (dict[str, str], 可选) –
要作为 HTTP 请求参数传递给 Bokeh 应用程序代码的键/值字典 (默认值: None)

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

返回:

连接到服务器的新 ClientSession

返回类型:

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