Source code for bokeh.application.handlers.function

''' Provide a Bokeh Application Handler to build up documents by running
a specified Python function.

This Handler is not used by the Bokeh server command line tool, but is often
useful if users wish to embed the Bokeh server programmatically:

.. code-block:: python

    def make_doc(doc):

        # do work to modify the document, add plots, widgets, etc.

        return doc

    app = Application(FunctionHandler(make_doc))

    server = Server({'/bkapp': app}, io_loop=IOLoop.current())

    server.start()

For complete examples of this technique, see
:bokeh-tree:`examples/howto/server_embed`

'''
from __future__ import absolute_import, print_function

from .handler import Handler
from bokeh.util.callback_manager import _check_callback

[docs]class FunctionHandler(Handler):
    ''' A Handler that accepts a plain python function to use for modifying
    Bokeh Documents.

    For example, the following code configures a handler with a function that
    adds an empty plot to a Document:

    .. code-block:: python

        def add_empty_plot(doc):
            p = figure(x_range=(0,10), y_range=(0, 10))
            doc.add_root(p)
            return doc

        handler = FunctionHandler(add_empty_plot)

    This handler could be configured on an Application, and the Application
    would run this function every time a new session is created.

    '''

[docs]    def __init__(self, func):
        '''

        Args:
            func (callable) : a function to modify and return a Bokeh Document.
                The function should have the form:

                .. code-block:: python

                    def func(doc):
                        # modify doc
                        return doc

                and it  should return the passed-in document after making any
                modifications in-place.

        '''
        super(FunctionHandler, self).__init__()

        _check_callback(func, ('doc',))

        self._func = func
        self._safe_to_fork = True

[docs]    def modify_document(self, doc):
        ''' Execute the configured ``func`` to modify the document.

        After this method is first executed, ``safe_to_fork`` will return
        ``False``.

        '''
        self._func(doc)
        self._safe_to_fork = False

    @property
    def safe_to_fork(self):
        ''' Whether it is still safe for the Bokeh server to fork new workers.

        ``False`` if ``modify_doc`` has already been called.

        '''
        return self._safe_to_fork