Utility to integrate Bokeh with Django Channels
Project description
bokeh-django
Support for running Bokeh apps with Django
Introduction
Both Bokeh and Django are web frameworks that can be used independently to build and host web applications. They each have their own strengths and the purpose of the bokeh_django
package is to integrate these two frameworks so their strengths can be used together.
Installation
pip install bokeh-django
Configuration
This documentation assumes that you have already started a Django project.
bokeh-django
enables you to define routes (URLs) in your Django project that will map to Bokeh applications or embed Bokeh applications into a template rendered by Django. However, before defining the routes there are several configuration steps that need to be completed first.
-
Configure
INSTALLED_APPS
:In the
settings.py
file ensure that bothchannels
andbokeh_django
are added to theINSTALLED_APPS
list:INSTALLED_APPS = [ ..., 'channels', 'bokeh_django', ]
-
Set Up an ASGI Application:
By default, the Django project will be configured to use a WSGI application, but the
startproject
command should have also created anasgi.py
file.In
settings.py
change theWSGI_APPLICATION
setting toASGI_APPLICATION
and modify the path accordingly. It should look something like this:ASGI_APPLICATION = 'mysite.asgi.application'
Next, modify the contents of the
asgi.py
file to get the URL patterns from thebokeh_django
app config. Something similar to this will work: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())), })
-
Configure Static Files:
Both Bokeh and Django have several ways of configuring serving static resources. This documentation will describe several possible configuration approaches.
The Bokeh
resources
setting can be set to one of several values (e.gserver
,inline
,cdn
), the default iscdn
. If this setting is set toinline
, orcdn
then Bokeh resources will be served independently of Django resources. However, if the Bokehresources
setting is set toserver
, then the Bokeh resources are served up by the Django server in the same way that the Django static resources are and so Django must be configured to be able to find the Bokeh resources.To specify the Bokeh
resources
setting add the following to the Djangosettings.py
file:from bokeh.settings import settings as bokeh_settings bokeh_settings.resources = 'server'
If the Bokeh
resources
setting is set toserver
then we must add the location of the Bokeh resources to theSTATICFILES_DIRS
setting:from bokeh.settings import settings as bokeh_settings, bokehjsdir STATICFILES_DIRS = [ ..., bokehjsdir(), ]
Django can be configured to automatically find and collect static files using the
staticfiles
app, or the static file URL patterns can be explicitly added to the list ofurlpatterns
in theurls.py
file.To explicitly add the static file
urlpatterns
add the following to theurls.py
file:from django.contrib.staticfiles.urls import staticfiles_urlpatterns from bokeh_django import static_extensions urlpatterns = [ ..., *static_extensions(), *staticfiles_urlpatterns(), ]
Be sure that the
static_extensions
are listed before thestaticfiles_urlpatterns
.Alternatively, you can configure the
staticfiles
app by adding'django.contrib.staticfiles',
toINSTALLED_APPS
:INSTALLED_APPS = [ ..., 'django.contrib.staticfiles', 'channels', 'bokeh_django', ]
Next add
bokeh_django.static.BokehExtensionFinder
to theSTATICFILES_FINDERS
setting. The default value forSTATICFILES_FINDERS
has two items. If you override the default by adding theSTATICFILES_FINDERS
setting to yoursettings.py
file, then be sure to also list the two default values in addition to theBokehExtensionFinder
:STATICFILES_FINDERS = ( "django.contrib.staticfiles.finders.FileSystemFinder", "django.contrib.staticfiles.finders.AppDirectoriesFinder", 'bokeh_django.static.BokehExtensionFinder', )
Define Routes
Bokeh applications are integrated into Django through routing or URLs.
In a Django app, the file specified by the ROOT_URLCONF
setting (e.g. urls.py
) must define urlpatterns
which is a sequence of django.url.path
and/or django.url.re_path
objects. When integrating a Django app with Bokeh, the urls.py
file must also define bokeh_apps
as a sequence of bokeh_django
routing objects. This should be done using the bokeh_djagno.document
and/or bokeh_django.autoload
functions.
Document
The first way to define a route is to use bokeh_django.document
, which defines a route to a Bokeh app (as either a file-path or a function).
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)
]
When using the document
route Django will route the URL directly to the Bokeh app and all the rendering will be handled by Bokeh.
Directory
An alternative way to create document
routes is to use bokeh_django.directory
to automatically create a document
route for all the bokeh apps found in a directory. In this case the file name will be used as the URL pattern.
from bokeh_django import directory
bokeh_apps = directory('/path/to/bokeh/apps/')
Autoload
To integrate more fully into a Django application routes can be created using autoload
. This allows the Bokeh application to be embedded in a template that is rendered by Django. This has the advantage of being able to leverage Django capabilities in the view and the template, but is slightly more involved to set up. There are five components that all need to be configured to work together: the Bokeh handler, the Django view, the template, the Django URL path, and the Bokeh URL route.
Bokeh Handler
The handler is a function (or any callable) that accepts a bokeh.document.Document
object and configures it with the Bokeh content that should be embedded. This is done by adding a Bokeh object as the document root:
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))
The handler can also embed a Panel object. In this case the document is passed in to the server_doc
method of the Panel object:
import panel as pn
def panel_handler(doc: Document) -> None:
pn.Row().server_doc(doc)
Django View
The view is a Django function that accepts a request
object and returns a response
. A view that embeds a Bokeh app must create a bokeh.embed.server_document
and pass it in the context to the template when rendering the response.
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))
Template
The template document is a Django HTML template (e.g. "embed.html"
) that will be rendered by Django. It can be as complex as desired, but at the very least must render the script
that was passed in from the context:
<!doctype html>
<html lang="en">
<body>
{{ script|safe }}
</body>
</html>
Django URL Path
The Django URL Path is a django.url.path
or django.url.re_path
object that is included in the urlpatters
sequence and that maps a URL pattern to the Django View as would normally be done with Django.
urlpatterns = [
path("embedded-bokeh-app/", views.view_function),
]
Bokeh URL Route
The Bokeh URL Route is a bokeh_django.autoload
object that is included in the bokeh_apps
sequence and that maps a URL pattern to the Bokeh handler.
from bokeh_django import autoload
bokeh_apps = [
autoload("embedded-bokeh-app/", views.handler)
]
Note that the URL pattern should be the same URL pattern that was used in the corresponding Django URL Path. In reality the URL pattern must match the URL that the server_document
script is configured with in the Django View. Normally, it is easiest to use the URL from the request
object (e.g. script = server_document(request.build_absolute_uri())
), which is the URL of the corresponding Django URL Path.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for bokeh_django-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3941e721b0f98ec81fd994fdc2fb11b669b1a62986bbe5cd2f596dc098e71936 |
|
MD5 | 0f881b982867e983e456a4b4eb975be8 |
|
BLAKE2b-256 | 57c644fec9fdab45d071003d5bda2335fc47f65d537a2b7e5982012d4da87af1 |