构建应用程序#

到目前为止，使用 Bokeh 服务器创建交互式数据可视化的最灵活方式是创建 Bokeh 应用程序，并使用 bokeh serve 命令来提供它们。然后，Bokeh 服务器使用应用程序代码为所有连接的浏览器创建会话和文档。

../../../_images/bokeh_serve.svg — Bokeh 服务器（左）使用应用程序代码来创建 Bokeh 文档。来自浏览器（右）的每个新连接都会导致服务器为该会话创建一个新文档。#

Bokeh 服务器在每次新连接时执行应用程序代码，并创建一个新的 Bokeh 文档，将其同步到浏览器。应用程序代码还设置了回调，这些回调应在属性（如小部件值）发生更改时运行。

您可以通过多种方式提供应用程序代码。

单模块格式#

考虑以下完整示例。

# myapp.py

from random import random

from bokeh.layouts import column
from bokeh.models import Button
from bokeh.palettes import RdYlBu3
from bokeh.plotting import figure, curdoc

# create a plot and style its properties
p = figure(x_range=(0, 100), y_range=(0, 100), toolbar_location=None)
p.border_fill_color = 'black'
p.background_fill_color = 'black'
p.outline_line_color = None
p.grid.grid_line_color = None

# add a text renderer to the plot (no data yet)
r = p.text(x=[], y=[], text=[], text_color=[], text_font_size="26px",
           text_baseline="middle", text_align="center")

i = 0

ds = r.data_source

# create a callback that adds a number in a random location
def callback():
    global i

    # BEST PRACTICE --- update .data in one step with a new dict
    new_data = dict()
    new_data['x'] = ds.data['x'] + [random()*70 + 15]
    new_data['y'] = ds.data['y'] + [random()*70 + 15]
    new_data['text_color'] = ds.data['text_color'] + [RdYlBu3[i%3]]
    new_data['text'] = ds.data['text'] + [str(i)]
    ds.data = new_data

    i = i + 1

# add a button widget and configure with the call back
button = Button(label="Press Me")
button.on_event('button_click', callback)

# put the button and plot in a layout and add to the document
curdoc().add_root(column(button, p))

上面的代码没有指定任何输出或连接方法。它是一个创建和更新对象的简单脚本。bokeh 命令行工具允许您在处理数据后指定输出选项。例如，您可以运行 bokeh json myapp.py 来获取应用程序的 JSON 序列化版本。但是，要在 Bokeh 服务器上运行该应用程序，请使用以下命令

bokeh serve --show myapp.py

--show 选项将导致您的默认浏览器在新标签页中打开正在运行的应用程序的地址，在本例中为

https://127.0.0.1:5006/myapp

如果您只有一个应用程序，服务器根目录将重定向到它。否则，您将看到服务器根目录下运行的所有应用程序的索引

https://127.0.0.1:5006/

您可以使用 --disable-index 选项禁用此索引。同样，您可以使用 --disable-index-redirect 选项禁用重定向。

除了从单个 Python 文件创建 Bokeh 应用程序外，您还可以从目录创建应用程序。

目录格式#

您可以通过创建和填充包含应用程序文件的文件系统目录来创建 Bokeh 应用程序。要启动名为 myapp 的目录中的应用程序，您可以执行 bokeh serve，如下所示

bokeh serve --show myapp

此目录必须包含一个 main.py 文件，该文件构造一个文档以供 Bokeh 服务器提供服务

myapp
   |
   +---main.py

以下是 Bokeh 服务器熟悉的目录应用程序结构

myapp
   |
   +---__init__.py
   +---app_hooks.py
   +---main.py
   +---request_handler.py
   +---static
   +---theme.yaml
   +---templates
        +---index.html

上面的某些文件和子目录是可选的。

一个 __init__.py 文件，用于将此目录标记为包。您可以进行相对于包的导入，例如 from . import mymod 和 from .mymod import func。
一个 request_handler.py 文件，允许您声明一个可选函数来处理 HTTP 请求，并返回会话令牌包含的项目字典，如请求处理程序钩子中所述。
一个 app_hooks.py 文件，允许您在应用程序执行的不同阶段触发可选的回调，如生命周期钩子和请求处理程序钩子中所述。
一个 static 子目录，您可以使用它来提供与此应用程序关联的静态资源。
一个 theme.yaml 文件，您可以在其中声明 Bokeh 应用于模型类型的默认属性。
一个 templates 子目录，其中包含一个 index.html Jinja 模板文件。该目录可能包含 index.html 引用的其他 Jinja 模板。该模板应具有与 FILE 模板相同的参数。有关更多信息，请参阅自定义应用程序的 Jinja 模板。

在执行 main.py 时，Bokeh 服务器确保标准 __file__ 模块属性按您的预期工作。因此，您可以随意在目录中包含数据文件或自定义用户定义的模型。

Bokeh 还会将应用程序目录 sys.path 添加到应用程序目录中，以方便导入 Python 模块。但是，如果目录中存在 __init__.py，则可以将应用程序用作包，并进行标准包相对导入。

这是一个更完善的目录树的示例

myapp
   |
   +---__init__.py
   |
   +---app_hooks.py
   +---data
   |    +---things.csv
   |
   +---helpers.py
   +---main.py
   |---models
   |    +---custom.js
   |
   +---request_handler.py
   +---static
   |    +---css
   |    |    +---special.css
   |    |
   |    +---images
   |    |    +---foo.png
   |    |    +---bar.png
   |    |
   |    +---js
   |        +---special.js
   |
   |---templates
   |    +---index.html
   |
   +---theme.yaml

在这种情况下，您的代码可能类似于以下内容

from os.path import dirname, join
from .helpers import load_data

load_data(join(dirname(__file__), 'data', 'things.csv'))

从 models/custom.js 加载自定义模型的 JavaScript 实现的代码也类似。

自定义应用程序的 Jinja 模板#

目录格式部分提到您可以覆盖默认的 Jinja 模板，Bokeh 服务器使用该模板生成面向用户的 HTML。

这使您可以使用 CSS 和 JavaScript 来调整应用程序在浏览器中的外观。

有关 Jinja 模板如何工作的更多详细信息，请参阅 Jinja 项目文档。

在模板中嵌入图形#

要在模板代码中引用 Bokeh 图形，您需要设置其 name 属性，并将图形添加到 Bokeh 应用程序主线程的当前文档根目录中，即 main.py。

from bokeh.plotting import curdoc

# templates can refer to a configured name value
plot = figure(name="bokeh_jinja_figure")

curdoc().add_root(plot)

然后，您可以在相应的 Jinja 模板中使用该名称，通过 roots 模板参数引用该图形，如下所示

{% extends base %}

{% block contents %}
<div>
    {{ embed(roots.bokeh_jinja_figure) }}
</div>
{% endblock %}

定义自定义变量#

您可以使用 curdoc().template_variables 字典将自定义变量传递给模板，如下所示

# set a new single key/value pair
curdoc().template_variables["user_id"] = user_id

# or update multiple pairs at once
curdoc().template_variables.update(first_name="Mary", last_name="Jones")

然后，您可以在相应的 Jinja 模板中引用这些变量。

{% extends base %}

{% block contents %}
<div>
    <p> Hello {{ user_id }}, AKA '{{ last_name }}, {{ first_name }}'! </p>
</div>
{% endblock %}

访问 HTTP 请求#

在为应用程序创建会话时，Bokeh 将会话上下文作为 curdoc().session_context 提供。会话上下文最有用的功能是使 Tornado HTTP 请求对象作为 session_context.request 可用于应用程序。由于与 --num-procs 的不兼容性，HTTP 请求不可直接访问。相反，只有 arguments 属性完整可用，并且只有 cookies 和 headers 的子集允许通过 --include-headers、--exclude-headers、--include-cookies 和 --exclude-cookies 参数来访问。尝试访问 request 上的任何其他属性都会导致错误。

您可以启用其他请求属性，如请求处理程序钩子中所述。

以下代码访问请求 arguments 以提供变量 N 的值，该值可以控制绘图点的数量。

# request.arguments is a dict that maps argument names to lists of strings,
# for example, the query string ?N=10 results in {'N': [b'10']}

args = curdoc().session_context.request.arguments

try:
  N = int(args.get('N')[0])
except:
  N = 200

警告

请求对象使检查值（如 arguments）变得容易。但是，调用任何 Tornado 方法（如 finish()）或直接写入 request.connection 是不受支持的，并且会导致未定义的行为。

请求处理程序钩子#

为了在完整的 Tornado HTTP 请求可能不可用的情况下提供额外信息，您可以定义自定义处理程序钩子。

为此，请在目录格式中创建一个应用程序，并在目录中包含一个名为 request_handler.py 的文件。此文件必须包含一个 process_request 函数。

def process_request(request):
    '''If present, this function executes when an HTTP request arrives.'''
    return {}

然后，该过程将 Tornado HTTP 请求传递给处理程序，处理程序返回 curdoc().session_context.token_payload 的字典。这使您可以解决一些 --num-procs 问题并提供额外信息。

回调和事件#

在专门深入探讨 Bokeh 服务器上下文中的回调和事件之前，值得讨论回调的一般不同用例。

浏览器中的 JavaScript 回调#

无论您是否使用 Bokeh 服务器，您都可以创建在浏览器中使用 CustomJS 和其他方法执行的回调。有关更多信息和示例，请参阅 JavaScript 回调。

CustomJS 回调 永远不会 执行 Python 代码，即使您将 Python 回调转换为 JavaScript 也是如此。CustomJS 回调仅在浏览器的 JavaScript 解释器内部执行，这意味着它们只能与 JavaScript 数据和函数（如 BokehJS 模型）进行交互。

带有 Jupyter 交互器的 Python 回调#

当使用 Jupyter 笔记本时，您可以使用 Jupyter 交互器快速创建简单的 GUI 表单。对 GUI 小部件的更新会触发在 Jupyter 的 Python 内核中执行的 Python 回调。通常，让这些回调调用 push_notebook() 以将更新推送到显示的绘图非常有用。有关更多信息，请参阅 Jupyter 交互器。

注意

您可以使用 push_notebook() 将绘图更新从 Python 推送到 BokehJS。对于双向通信，请在笔记本中嵌入 Bokeh 服务器。例如，这允许范围和选择更新触发 Python 回调。有关更多详细信息，请参阅 examples/server/api/notebook_embed.ipynb

从线程更新#

您可以在单独的线程中进行阻塞计算。但是，您必须通过下一个刻度回调来调度文档更新。此回调会在 Tornado 事件循环的下一次迭代中尽快执行，并自动获取必要的锁以安全地更新文档状态。

警告

从另一个线程对文档执行的唯一安全操作是 add_next_tick_callback() 和 remove_next_tick_callback()

请记住，直接从另一个线程发出对文档状态的更新（无论是通过其他文档方法还是设置 Bokeh 模型属性）都存在数据和协议损坏的风险。

为了允许所有线程访问同一文档，请保存 curdoc() 的本地副本。下面的示例说明了此过程。

import time
from functools import partial
from random import random
from threading import Thread

from bokeh.models import ColumnDataSource
from bokeh.plotting import curdoc, figure

# only modify from a Bokeh session callback
source = ColumnDataSource(data=dict(x=[0], y=[0]))

# This is important! Save curdoc() to make sure all threads
# see the same document.
doc = curdoc()

async def update(x, y):
    source.stream(dict(x=[x], y=[y]))

def blocking_task():
    while True:
        # do some blocking computation
        time.sleep(0.1)
        x, y = random(), random()

        # but update the document from a callback
        doc.add_next_tick_callback(partial(update, x=x, y=y))

p = figure(x_range=[0, 1], y_range=[0,1])
l = p.scatter(marker='circle', x='x', y='y', source=source)

doc.add_root(p)

thread = Thread(target=blocking_task)
thread.start()

要查看此示例的实际效果，请将上面的代码保存到 Python 文件中，例如 testapp.py，然后执行以下命令

bokeh serve --show testapp.py

警告

目前，在向文档添加下一个刻度回调时没有锁定。Bokeh 将来应该对回调方法进行更细粒度的锁定，但目前最好让每个线程向文档添加不超过一个回调。

从解锁的回调更新#

通常，Bokeh 会话回调会递归锁定文档，直到它们启动的所有后续工作都完成为止。但是，您可能希望使用 Tornado 的 ThreadPoolExecutor 在异步回调中从回调驱动阻塞计算。这要求您使用 without_document_lock() 装饰器来抑制正常的锁定行为。

与上面的线程示例一样，所有更新文档状态的操作都必须通过下一个刻度回调。

以下示例演示了一个应用程序，该应用程序从一个解锁的 Bokeh 会话回调驱动阻塞计算。它屈服于线程池执行器上运行的阻塞函数，然后使用下一个刻度回调进行更新。该示例还通过具有不同更新速率的标准锁定会话回调简单地更新状态。

import asyncio
import time
from concurrent.futures import ThreadPoolExecutor
from functools import partial

from bokeh.document import without_document_lock
from bokeh.models import ColumnDataSource
from bokeh.plotting import curdoc, figure

source = ColumnDataSource(data=dict(x=[0], y=[0], color=["blue"]))

i = 0

doc = curdoc()

executor = ThreadPoolExecutor(max_workers=2)

def blocking_task(i):
    time.sleep(1)
    return i

# the unlocked callback uses this locked callback to safely update
async def locked_update(i):
    source.stream(dict(x=[source.data['x'][-1]+1], y=[i], color=["blue"]))

# this unlocked callback will not prevent other session callbacks from
# executing while it is running
@without_document_lock
async def unlocked_task():
    global i
    i += 1
    res = await asyncio.wrap_future(executor.submit(blocking_task, i), loop=None)
    doc.add_next_tick_callback(partial(locked_update, i=res))

async def update():
    source.stream(dict(x=[source.data['x'][-1]+1], y=[i], color=["red"]))

p = figure(x_range=[0, 100], y_range=[0, 20])
l = p.scatter(marker='circle', x='x', y='y', color='color', source=source)

doc.add_periodic_callback(unlocked_task, 1000)
doc.add_periodic_callback(update, 200)
doc.add_root(p)

与之前一样，您可以通过保存到 Python 文件并在其上运行 bokeh serve 来运行此示例。

生命周期钩子#

您可能希望在服务器或会话运行时的特定点执行代码。Bokeh 通过一组生命周期钩子启用此功能。要使用这些钩子，请在目录格式中创建您的应用程序，并在目录中包含一个名为 app_hooks.py 的指定文件。在此文件中，您可以包含以下任何或全部按惯例命名的函数

def on_server_loaded(server_context):
    # If present, this function executes when the server starts.
    pass

def on_server_unloaded(server_context):
    # If present, this function executes when the server shuts down.
    pass

def on_session_created(session_context):
    # If present, this function executes when the server creates a session.
    pass

def on_session_destroyed(session_context):
    # If present, this function executes when the server closes a session.
    pass

您还可以在正在提供的 Document 上直接定义 on_session_destroyed 生命周期钩子。这使得在用户关闭会话后进行清理变得容易，例如执行数据库连接关闭等操作，而无需捆绑单独的文件。要声明这样的回调，请定义一个函数并使用 Document.on_session_destroyed 方法注册它

doc = Document()

def cleanup_session(session_context):
    # This function executes when the user closes the session.
    pass

doc.on_session_destroyed(cleanup_session)

除了上面的生命周期钩子之外，您还可以定义请求钩子来访问用户发出的 HTTP 请求。有关更多信息，请参阅请求处理程序钩子。