From a54ded224eb2f57ad5dc812e757cb2cc369ff8eb Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Tue, 29 Sep 2015 15:42:56 -0400 Subject: [PATCH] Conver to RST --- docs/source/extending/handlers.rst | 215 +++++++++++++++-------------- 1 file changed, 113 insertions(+), 102 deletions(-) diff --git a/docs/source/extending/handlers.rst b/docs/source/extending/handlers.rst index 43cb05920..62c38e747 100644 --- a/docs/source/extending/handlers.rst +++ b/docs/source/extending/handlers.rst @@ -1,101 +1,24 @@ -# Custom request handlers +Custom request handlers +======================= -The notebook webserver can be interacted with using a well -[defined RESTful API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyter-js-services/master/rest_api.yaml). -You can define custom RESTful API handlers in addition to the ones provided by -the notebook. As described below, to define a custom handler you need to first -write a notebook server extension. Then, in the extension, you can register the -custom handler. +The notebook webserver can be interacted with using a well `defined +RESTful +API `__. +You can define custom RESTful API handlers in addition to the ones +provided by the notebook. As described below, to define a custom handler +you need to first write a notebook server extension. Then, in the +extension, you can register the custom handler. -## Writing a notebook server extension +Writing a notebook server extension +----------------------------------- -The notebook webserver is written in Python, hence your server extension should -be written in Python too. Server extensions, like IPython extensions, are -Python modules that define a specially named load function, -`load_jupyter_server_extension`. This function is called when the extension is -loaded. +The notebook webserver is written in Python, hence your server extension +should be written in Python too. Server extensions, like IPython +extensions, are Python modules that define a specially named load +function, ``load_jupyter_server_extension``. This function is called +when the extension is loaded. -```Python -def load_jupyter_server_extension(nb_server_app): - """ - Called when the extension is loaded. - - Args: - nb_server_app (NotebookWebApplication): handle to the Notebook webserver instance. - """ - pass -``` - -To get the notebook server to load your custom extension, you'll need to add it -to the list of extensions to be loaded. You can do this using the config system. -`NotebookApp.server_extensions` is a config variable which is an array of -strings, each a Python module to be imported. Because this variable is notebook -config, you can set it two different ways, using config files or via the -command line. - -For example, to get your extension to load via the command line add a double -dash before the variable name, and put the Python array in double quotes. If -your package is "mypackage" and module is "mymodule", this would look like -`jupyter notebook --NotebookApp.server_extensions="['mypackage.mymodule']"` [2]. -Basically the string should be Python importable. - -Alternatively, you can have your extension loaded regardless of the command line -args by setting the variable in the Jupyter config file. The default location -of the Jupyter config file is -`~/.jupyter/profile_default/jupyter_notebook_config.py`. Then, inside the -config file, you can use Python to set the variable. For example, the following -config does the same as the previous command line example [1]. - -```python -c = get_config() -c.NotebookApp.server_extensions = [ - 'mypackage.mymodule' -] -``` - -Before continuing, it's a good idea to verify that your extension is being -loaded. Use a print statement to print something unique. Launch the notebook -server and you should see your statement printed to the console. - -## Registering custom handlers - -Once you've defined a server extension, you can register custom handlers because -you have a handle to the Notebook server app instance (`nb_server_app` above). -However, you first need to define your custom handler. To declare a custom -handler, inherit from `notebook.base.handlers.IPythonHandler`. The example -below[1] is a Hello World handler: - -```Python -from notebook.base.handlers import IPythonHandler - -class HelloWorldHandler(IPythonHandler): - def get(self): - self.finish('Hello, world!') -``` - -The Jupyter Notebook server use [Tornado](http://www.tornadoweb.org/en/stable/) -as its web framework. For more information on how to implement request handlers, -refer to the [Tornado documentation on the matter](http://www.tornadoweb.org/en/stable/web.html#request-handlers). - -After defining the handler, you need to register the handler with the -Notebook server. See the following example: - -```python -web_app = nb_server_app.web_app -host_pattern = '.*$' -route_pattern = url_path_join(web_app.settings['base_url'], '/hello') -web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) -``` - -Putting this together with the extension code, the example looks like: - -```python -from notebook.utils import url_path_join -from notebook.base.handlers import IPythonHandler - -class HelloWorldHandler(IPythonHandler): - def get(self): - self.finish('Hello, world!') +.. code:: python def load_jupyter_server_extension(nb_server_app): """ @@ -104,12 +27,100 @@ class HelloWorldHandler(IPythonHandler): Args: nb_server_app (NotebookWebApplication): handle to the Notebook webserver instance. """ - web_app = nb_server_app.web_app - host_pattern = '.*$' - route_pattern = url_path_join(web_app.settings['base_url'], '/hello') - web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) -``` + pass -References: -1. [Peter Parente's Mindtrove](http://mindtrove.info/#nb-server-exts) -2. [Matthias Bussonnier's Jupyter Book](https://github.com/Carreau/jupyter-book) \ No newline at end of file +To get the notebook server to load your custom extension, you'll need to +add it to the list of extensions to be loaded. You can do this using the +config system. ``NotebookApp.server_extensions`` is a config variable +which is an array of strings, each a Python module to be imported. +Because this variable is notebook config, you can set it two different +ways, using config files or via the command line. + +For example, to get your extension to load via the command line add a +double dash before the variable name, and put the Python array in +double quotes. If your package is "mypackage" and module is +"mymodule", this would look like +``jupyter notebook --NotebookApp.server_extensions="['mypackage.mymodule']"`` +[2]. +Basically the string should be Python importable. + +Alternatively, you can have your extension loaded regardless of the +command line args by setting the variable in the Jupyter config file. +The default location of the Jupyter config file is +``~/.jupyter/profile_default/jupyter_notebook_config.py``. Then, inside +the config file, you can use Python to set the variable. For example, +the following config does the same as the previous command line example +[1]. + +.. code:: python + + c = get_config() + c.NotebookApp.server_extensions = [ + 'mypackage.mymodule' + ] + +Before continuing, it's a good idea to verify that your extension is +being loaded. Use a print statement to print something unique. Launch +the notebook server and you should see your statement printed to the +console. + +Registering custom handlers +--------------------------- + +Once you've defined a server extension, you can register custom handlers +because you have a handle to the Notebook server app instance +(``nb_server_app`` above). However, you first need to define your custom +handler. To declare a custom handler, inherit from +``notebook.base.handlers.IPythonHandler``. The example below[1] is a +Hello World handler: + +.. code:: python + + from notebook.base.handlers import IPythonHandler + + class HelloWorldHandler(IPythonHandler): + def get(self): + self.finish('Hello, world!') + +The Jupyter Notebook server use +`Tornado `__ as its web framework. +For more information on how to implement request handlers, refer to the +`Tornado documentation on the +matter `__. + +After defining the handler, you need to register the handler with the +Notebook server. See the following example: + +.. code:: python + + web_app = nb_server_app.web_app + host_pattern = '.*$' + route_pattern = url_path_join(web_app.settings['base_url'], '/hello') + web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) + +Putting this together with the extension code, the example looks like: + +.. code:: python + + from notebook.utils import url_path_join + from notebook.base.handlers import IPythonHandler + + class HelloWorldHandler(IPythonHandler): + def get(self): + self.finish('Hello, world!') + + def load_jupyter_server_extension(nb_server_app): + """ + Called when the extension is loaded. + + Args: + nb_server_app (NotebookWebApplication): handle to the Notebook webserver instance. + """ + web_app = nb_server_app.web_app + host_pattern = '.*$' + route_pattern = url_path_join(web_app.settings['base_url'], '/hello') + web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) + +References: 1. `Peter Parente's +Mindtrove `__ 2. `Matthias +Bussonnier's Jupyter Book `__