🔍 Code Extractor

DocHandler is a Tornado request handler that serves HTML pages for Bokeh sessions, combining session management with document rendering capabilities.

Purpose

This class handles HTTP GET requests to serve Bokeh document pages in a web application. It inherits from BkDocHandler (Bokeh's document handler) and SessionPrefixHandler to manage session prefixes. The handler retrieves or creates a Bokeh session, sets it as the current document in the application state, generates an HTML page with embedded resources, and returns it to the client. It's a critical component in serving interactive Bokeh/Panel applications through a web server.

Source Code

class DocHandler(BkDocHandler, SessionPrefixHandler):

    @authenticated
    async def get(self, *args, **kwargs):
        with self._session_prefix():
            session = await self.get_session()
            state.curdoc = session.document
            try:
                resources = Resources.from_bokeh(self.application.resources())
                page = server_html_page_for_session(
                    session, resources=resources, title=session.document.title,
                    template=session.document.template,
                    template_variables=session.document.template_variables
                )
            finally:
                state.curdoc = None
        self.set_header("Content-Type", 'text/html')
        self.write(page)

Parameters

Parameter Details

bases: Inherits from BkDocHandler (Bokeh's base document handler providing core document serving functionality) and SessionPrefixHandler (provides session prefix management through _session_prefix() context manager)

*args: Variable positional arguments passed to the get method, typically from Tornado's routing system

**kwargs: Variable keyword arguments passed to the get method, may include request parameters and routing information

Return Value

The get method is an async coroutine that doesn't explicitly return a value but writes HTML content directly to the HTTP response via self.write(). The HTML page contains the rendered Bokeh session with all necessary JavaScript and CSS resources embedded.

Class Interface

Methods

Attributes

Dependencies

• tornado
• bokeh
• param

Required Imports

from tornado.web import authenticated
from bokeh.server.views.doc_handler import DocHandler as BkDocHandler
from bokeh.resources import Resources
from bokeh.embed.server import server_html_page_for_session

Conditional/Optional Imports

These imports are only needed under specific conditions:

from state import state

from resources import Resources

Usage Example

# This class is typically used as part of a Tornado/Bokeh server setup
# It's registered as a URL handler in the application routing

from tornado.web import Application
from bokeh.server.server import Server

# Define a Bokeh application function
def make_doc(doc):
    # Add content to the document
    pass

# Create server with custom DocHandler
apps = {'/app': make_doc}
server = Server(apps, port=5006)

# The DocHandler is automatically used when accessing /app
# Users navigate to http://localhost:5006/app to trigger the handler
# The handler will:
# 1. Authenticate the user
# 2. Get or create a session
# 3. Render the Bokeh document as HTML
# 4. Return the page to the browser

Best Practices

• This handler should only be instantiated by Tornado's application framework, not manually created
• The @authenticated decorator ensures only authenticated users can access the document
• The _session_prefix() context manager must be properly implemented in SessionPrefixHandler base class
• state.curdoc is set temporarily during page generation and always cleaned up in the finally block to prevent state leakage
• The handler manages session lifecycle automatically through get_session()
• Resources are obtained from the application's configured resources to ensure consistency
• The Content-Type header is explicitly set to text/html before writing the response
• This is an async handler, so it must be used in an async Tornado application context
• Session state is thread-safe due to the context manager pattern used
• Error handling should be implemented at the application level as this handler doesn't catch exceptions beyond the finally block

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class AutoloadJsHandler 68.2% similar

  A custom Tornado request handler that generates and serves the Bokeh autoload JavaScript chunk for embedding Bokeh applications in web pages.

  From: /tf/active/vicechatdev/patches/server.py

• class RootHandler 64.5% similar

  A custom Tornado request handler that extends Bokeh's RootHandler to handle root URL requests with authentication and conditional redirection based on index file extensions.

  From: /tf/active/vicechatdev/patches/server.py

• class SessionPrefixHandler 63.1% similar

  A mixin class that provides a context manager for temporarily modifying URL prefix-related state variables during request handling in a Bokeh server application.

  From: /tf/active/vicechatdev/patches/server.py

• function server_html_page_for_session 60.4% similar

  Generates a complete HTML page for a Bokeh server session by bundling resources and rendering document roots with session token.

  From: /tf/active/vicechatdev/patches/server.py

• function init_doc 59.1% similar

  Initializes a Bokeh document by registering session information and setting up document lifecycle event handlers for Panel applications.

  From: /tf/active/vicechatdev/patches/server.py