Source code for bokeh.application.handlers.handler
#-----------------------------------------------------------------------------# Copyright (c) Anaconda, Inc., and Bokeh Contributors.# All rights reserved.## The full license is in the file LICENSE.txt, distributed with this software.#-----------------------------------------------------------------------------''' Provide a base class for Bokeh Application handler classes.When a Bokeh server session is initiated, the Bokeh server asks the Applicationfor a new Document to service the session. To do this, the Application firstcreates a new empty Document, then it passes this new Document to the``modify_document`` method of each of its handlers. When all handlers haveupdated the Document, it is used to service the user session.Below is an example outline of a custom handler that might modify documentsbased off information in some database:.. code-block:: python class DatabaseHandler(Handler): """ A Bokeh Application handler to initialize Documents from a database """ def modify_document(self, doc: Document) -> None: # do some data base lookup here to generate 'plot' # add the plot to the document (i.e modify the document) doc.add_root(plot)'''#-----------------------------------------------------------------------------# Boilerplate#-----------------------------------------------------------------------------from__future__importannotationsimportlogging# isort:skiplog=logging.getLogger(__name__)#-----------------------------------------------------------------------------# Imports#-----------------------------------------------------------------------------# Standard library importsimportosimportsysimporttracebackfromtypingimportTYPE_CHECKING,Any# Bokeh importsfrom...documentimportDocumentfrom..applicationimportServerContext,SessionContextifTYPE_CHECKING:fromtornado.httputilimportHTTPServerRequestfrom.code_runnerimportCodeRunner#-----------------------------------------------------------------------------# Globals and constants#-----------------------------------------------------------------------------__all__=('Handler',)#-----------------------------------------------------------------------------# General API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Dev API#-----------------------------------------------------------------------------
[docs]classHandler:''' Provide a mechanism for Bokeh applications to build up new Bokeh Documents. '''_failed:bool_error:str|None_error_detail:str|None_static:str|Nonedef__init__(self)->None:self._failed=Falseself._error=Noneself._error_detail=Noneself._static=None# Properties --------------------------------------------------------------@propertydeferror(self)->str|None:''' If the handler fails, may contain a related error message. '''returnself._error@propertydeferror_detail(self)->str|None:''' If the handler fails, may contain a traceback or other details. '''returnself._error_detail@propertydeffailed(self)->bool:''' ``True`` if the handler failed to modify the doc '''returnself._failed@propertydefsafe_to_fork(self)->bool:returnTrue# Public methods ----------------------------------------------------------
[docs]defmodify_document(self,doc:Document)->None:''' Modify an application document in a specified manner. When a Bokeh server session is initiated, the Bokeh server asks the Application for a new Document to service the session. To do this, the Application first creates a new empty Document, then it passes this Document to the ``modify_document`` method of each of its handlers. When all handlers have updated the Document, it is used to service the user session. *Subclasses must implement this method* Args: doc (Document) : A Bokeh Document to update in-place Returns: Document '''raiseNotImplementedError("implement modify_document()")
[docs]defon_server_loaded(self,server_context:ServerContext)->None:''' Execute code when the server is first started. Subclasses may implement this method to provide for any one-time initialization that is necessary after the server starts, but before any sessions are created. Args: server_context (ServerContext) : '''pass
[docs]defon_server_unloaded(self,server_context:ServerContext)->None:''' Execute code when the server cleanly exits. (Before stopping the server's ``IOLoop``.) Subclasses may implement this method to provide for any one-time tear down that is necessary before the server exits. Args: server_context (ServerContext) : .. warning:: In practice this code may not run, since servers are often killed by a signal. '''pass
[docs]asyncdefon_session_created(self,session_context:SessionContext)->None:''' Execute code when a new session is created. Subclasses may implement this method to provide for any per-session initialization that is necessary before ``modify_doc`` is called for the session. Args: session_context (SessionContext) : '''pass
[docs]asyncdefon_session_destroyed(self,session_context:SessionContext)->None:''' Execute code when a session is destroyed. Subclasses may implement this method to provide for any per-session tear-down that is necessary when sessions are destroyed. Args: session_context (SessionContext) : '''pass
[docs]defprocess_request(self,request:HTTPServerRequest)->dict[str,Any]:''' Processes incoming HTTP request returning a dictionary of additional data to add to the session_context. Args: request: HTTP request Returns: A dictionary of JSON serializable data to be included on the session context. '''return{}
[docs]defstatic_path(self)->str|None:''' Return a path to app-specific static resources, if applicable. '''ifself.failed:returnNoneelse:returnself._static
[docs]defurl_path(self)->str|None:''' Returns a default URL path, if applicable. Handlers subclasses may optionally implement this method, to inform the Bokeh application what URL it should be installed at. If multiple handlers specify ``url_path`` the Application will use the value from the first handler in its list of handlers. '''returnNone
defhandle_exception(handler:Handler|CodeRunner,e:Exception)->None:''' Record an exception and details on a Handler. '''handler._failed=Truehandler._error_detail=traceback.format_exc()_,_,exc_traceback=sys.exc_info()filename,line_number,func,txt=traceback.extract_tb(exc_traceback)[-1]basename=os.path.basename(filename)handler._error=f"{e}\nFile {basename!r}, line {line_number}, in {func}:\n{txt}"#-----------------------------------------------------------------------------# Private API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Code#-----------------------------------------------------------------------------