bokeh-django

支持使用Django运行Bokeh应用

简介

Bokeh和Django都是可以独立使用来构建和托管Web应用的Web框架。它们各自都有其优势，而bokeh_django包的目的就是将这两个框架集成，以便可以将它们的优势结合起来。

安装

pip install bokeh-django

配置

本文档假设您已经启动了一个Django项目。

bokeh-django允许您在Django项目中定义路由（URL），这些路由将映射到Bokeh应用或嵌入到由Django渲染的模板中的Bokeh应用。然而，在定义路由之前，需要先完成几个配置步骤。

1. 配置INSTALLED_APPS

   在settings.py文件中确保将channels和bokeh_django添加到INSTALLED_APPS列表中

   INSTALLED_APPS = [
       ...,
       'channels',
       'bokeh_django',
   ]
   

2. 设置ASGI应用

   默认情况下，Django项目将配置为使用WSGI应用，但startproject命令也应该创建了一个asgi.py文件。

   在settings.py中，将WSGI_APPLICATION设置改为ASGI_APPLICATION，并相应地修改路径。它看起来应该像这样

   ASGI_APPLICATION = 'mysite.asgi.application'
   

   接下来，修改asgi.py文件的内容，从bokeh_django应用配置中获取URL模式。类似以下的内容将有效

   from channels.auth import AuthMiddlewareStack
   from channels.routing import ProtocolTypeRouter, URLRouter
   from django.apps import apps
   
   bokeh_app_config = apps.get_app_config('bokeh_django')
   
   application = ProtocolTypeRouter({
      'websocket': AuthMiddlewareStack(URLRouter(bokeh_app_config.routes.get_websocket_urlpatterns())),
      'http': AuthMiddlewareStack(URLRouter(bokeh_app_config.routes.get_http_urlpatterns())),
   })
   

3. 配置静态文件

   Bokeh和Django都有多种配置服务静态资源的方法。本文档将描述几种可能的配置方法。

   Bokeh的resources设置可以设置为几个值之一（例如server、inline、cdn），默认为cdn。如果此设置设置为inline或cdn，则Bokeh资源将独立于Django资源提供服务。然而，如果Bokeh的resources设置设置为server，则Bokeh资源将以与Django静态资源相同的方式由Django服务器提供服务，因此Django必须配置为能够找到Bokeh资源。

   要指定Bokeh的resources设置，请将以下内容添加到Django的settings.py文件中

   from bokeh.settings import settings as bokeh_settings
   
   bokeh_settings.resources = 'server'
   

   如果Bokeh的resources设置设置为server，那么我们必须将Bokeh资源的位置添加到STATICFILES_DIRS设置中

   from bokeh.settings import settings as bokeh_settings, bokehjsdir
   
   STATICFILES_DIRS = [
       ...,
       bokehjsdir(),
   ]
   

   Django可以通过使用staticfiles应用自动找到和收集静态文件，或者可以显式地将静态文件URL模式添加到urls.py文件中的urlpatterns列表中。

   要显式添加静态文件urlpatterns，请将以下内容添加到urls.py文件中

   from django.contrib.staticfiles.urls import staticfiles_urlpatterns
   from bokeh_django import static_extensions
   
   urlpatterns = [
       ...,
       *static_extensions(),
       *staticfiles_urlpatterns(),
   ]
   

   请确保在static_extensions之前列出staticfiles_urlpatterns。

   或者，您可以通过将'django.contrib.staticfiles',添加到INSTALLED_APPS来配置staticfiles应用。

   INSTALLED_APPS = [
       ...,
       'django.contrib.staticfiles',
       'channels',
       'bokeh_django',
   ]
   

   接下来，将bokeh_django.static.BokehExtensionFinder添加到STATICFILES_FINDERS设置中。默认的STATICFILES_FINDERS有两个项。如果您通过将STATICFILES_FINDERS设置添加到您的settings.py文件来覆盖默认设置，那么请确保除了BokehExtensionFinder之外，还要列出两个默认值

   STATICFILES_FINDERS = (
       "django.contrib.staticfiles.finders.FileSystemFinder",
       "django.contrib.staticfiles.finders.AppDirectoriesFinder",
       'bokeh_django.static.BokehExtensionFinder',
   )
   

定义路由

Bokeh应用通过路由或URL与Django集成。

在一个Django应用中，由ROOT_URLCONF设置指定的文件（例如urls.py）必须定义urlpatterns，它是一个django.url.path和/或django.url.re_path对象的序列。当将Django应用与Bokeh集成时，urls.py文件还必须定义bokeh_apps作为一个bokeh_django路由对象的序列。这应该使用bokeh_django.document和/或bokeh_django.autoload函数来完成。

文档

定义路由的第一种方式是使用bokeh_django.document，它定义了一个指向Bokeh应用的路由（可以是文件路径或函数）。

from bokeh_django import document
from .views import my_bokeh_app_function

bokeh_apps = [
    document('url-pattern/', '/path/to/bokeh/app.py'),
    document('another-url-pattern/', my_bokeh_app_function)   
]

当使用document路由时，Django将直接将URL路由到Bokeh应用，并且所有的渲染将由Bokeh处理。

目录

创建document路由的另一种方法是使用bokeh_django.directory自动为目录中找到的所有bokeh应用创建document路由。在这种情况下，文件名将用作URL模式。

from bokeh_django import directory

bokeh_apps = directory('/path/to/bokeh/apps/')

自动加载

为了更全面地集成到Django应用程序中，可以使用autoload来创建路由。这允许将Bokeh应用程序嵌入到由Django渲染的模板中。这的优点是可以利用视图和模板中的Django功能，但设置稍微复杂一些。需要配置五个组件以协同工作：Bokeh处理器、Django视图、模板、Django URL路径和Bokeh URL路由。

Bokeh处理器

处理器是一个函数（或任何可调用对象），它接受一个bokeh.document.Document对象，并使用要嵌入的Bokeh内容配置它。这是通过将Bokeh对象添加为文档根来完成的

from bokeh.document import Document
from bokeh.layouts import column
from bokeh.models import Slider

def bokeh_handler(doc: Document) -> None:
 slider = Slider(start=0, end=30, value=0, step=1, title="Example")
 doc.add_root(column(slider))

处理器还可以嵌入Panel对象。在这种情况下，将文档传递给Panel对象的server_doc方法

import panel as pn
def panel_handler(doc: Document) -> None:
   pn.Row().server_doc(doc)

Django视图

视图是一个Django函数，它接受一个request对象并返回一个response。嵌入Bokeh应用程序的视图必须创建一个bokeh.embed.server_document，并在渲染响应时将其传递到模板的上下文中。

from bokeh.embed import server_document
from django.shortcuts import render

def view_function(request):
    script = server_document(request.build_absolute_uri())
    return render(request, "embed.html", dict(script=script))

模板

模板文档是Django HTML模板（例如"embed.html"），将由Django渲染。它可以非常复杂，但至少必须渲染从上下文中传递的script。

<!doctype html>
<html lang="en">  
<body>
  {{ script|safe }}
</body>
</html>

Django URL路径

Django URL路径是一个django.url.path或django.url.re_path对象，它包含在urlpatters序列中，将URL模式映射到Django视图，就像通常使用Django一样。

urlpatterns = [
    path("embedded-bokeh-app/", views.view_function),
]

Bokeh URL路由

Bokeh URL路由是一个bokeh_django.autoload对象，它包含在bokeh_apps序列中，将URL模式映射到Bokeh处理器。

from bokeh_django import autoload

bokeh_apps = [
    autoload("embedded-bokeh-app/", views.handler) 
]

请注意，URL模式应该与相应的Django URL路径中使用的URL模式相同。实际上，URL模式必须匹配Django视图中配置的server_document脚本的URL。通常，使用来自request对象的URL（例如script = server_document(request.build_absolute_uri())）是最简单的，这是相应Django URL路径的URL。