自定义Bundler扩展

Notebook服务器支持写入 Bundler扩展 转换、打包和下载/部署Notebook文件。作为开发人员,您只需要编写一个python函数来实现bundler。Notebook服务器自动生成 File -> Download asFile -> Deploy as Notebook前端的菜单项触发bundler。

以下是一些可以使用Bundler扩展实现的示例:

  • 将Notebook文件转换为HTML文档并将其作为日志发布到博客网站上

  • 创建当前Notebook环境的快照,并将该Definition PlusNotebook捆绑到zip下载中

  • 将Notebook部署为独立的交互式Notebook dashboard

要实现bundler扩展,必须执行以下所有操作:

  • 在python包中声明bundler扩展元数据

  • 写一篇 bundle 响应捆绑请求的函数

  • 指导用户如何启用/禁用Bundler扩展

以下各节详细描述了这些步骤。

声明Bundler元数据

您必须通过实现 _jupyter_bundlerextensions_paths 功能。只要在启用bundler扩展时可以导入,此函数就可以位于包中的任何位置。(见 启用/禁用Bundler扩展

# in mypackage.hello_bundler

def _jupyter_bundlerextension_paths():
    """Example "hello world" bundler extension"""
    return [{
        'name': 'hello_bundler',                    # unique bundler name
        'label': 'Hello Bundler',                   # human-readable menu item label
        'module_name': 'mypackage.hello_bundler',   # module containing bundle()
        'group': 'deploy'                           # group under 'deploy' or 'download' menu
    }]

请注意,返回值是一个列表。通过返回列表中的多个词典,您允许用户同时启用/禁用绑定器集。

写作 bundle 功能

在运行时,具有给定标签的菜单项出现在 File -> Deploy asFile -> Download as 菜单取决于 group 元数据中的值。当用户单击菜单项时,将打开一个新的浏览器选项卡,并且Notebook服务器将调用 bundle 功能在 module_name 在元数据中指定。

您必须实现 bundle 与以下示例的签名匹配的函数:

# in mypackage.hello_bundler

def bundle(handler, model):
    """Transform, convert, bundle, etc. the notebook referenced by the given
    model.

    Then issue a Tornado web response using the `handler` to redirect
    the user's browser, download a file, show a HTML page, etc. This function
    must finish the handler response before returning either explicitly or by
    raising an exception.

    Parameters
    ----------
    handler : tornado.web.RequestHandler
        Handler that serviced the bundle request
    model : dict
        Notebook model from the configured ContentManager
    """
    handler.finish('I bundled {}!'.format(model['path']))

你的 bundle 函数可以自由地对请求执行它想要的任何操作,并以任何方式响应。例如,它可以从请求中读取其他查询参数,发出重定向到另一个站点,运行本地进程(例如, nbconvert )向其他服务发出HTTP请求等。

呼叫方 bundle 函数是 @tornado.gen.coroutine 装饰并用 torando.gen.maybe_future . 此行为意味着您可以像上面的示例一样同步处理Web请求,或者使用 @tornado.gen.coroutineyield ,如下面的示例所示。

from tornado import gen

@gen.coroutine
def bundle(handler, model):
  # simulate a long running IO op (e.g., deploying to a remote host)
  yield gen.sleep(10)

  # now respond
  handler.finish('I spent 10 seconds bundling {}!'.format(model['path']))

当捆绑操作长期运行时,您应该选择第二种异步方法,否则,如果同步处理,将阻塞Notebook服务器主循环。

有关菜单项“单击以绑定函数调用”中数据流的详细信息,请参阅 Bundler调用详细信息 .

启用/禁用Bundler扩展

Notebook服务器包括用于启用和禁用Bundler扩展的命令行界面(CLI)。

您应该记录启用和禁用bundler的基本命令。一个可能的命令用于启用 hello_bundler 示例如下:

jupyter bundlerextension enable --py mypackage.hello_bundler --sys-prefix

以上更新了当前conda/virtualenv环境中的Notebook电脑配置文件 (--sys-prefix )和返回的元数据 mypackage.hellow_bundler._jupyter_bundlerextension_paths 功能。

稍后禁用bundler扩展的相应命令如下:

jupyter bundlerextension disable --py mypackage.hello_bundler --sys-prefix

如需更多帮助,请使用 bundlerextension 子命令,运行以下命令。

jupyter bundlerextension --help

输出描述了用于列出启用的bundler、为单个用户配置bundler、在系统范围内配置bundler等的选项。

示例:IPythonNotebook包(.zip)

这个 hello_bundler 本文档中的示例以简洁的名义过于简单。有关更有意义的示例,请参见 notebook/bundler/zip_bundler.pynotebook/bundler/tarball_bundler.py . 您可以让他们这样尝试:

jupyter bundlerextension enable --py notebook.bundler.zip_bundler --sys-prefix
jupyter bundlerextension enable --py notebook.bundler.tarball_bundler --sys-prefix

Bundler调用详细信息

对bundler扩展的支持来自中的python模块 notebook/bundler 和中的javascript notebook/static/notebook/js/menubar.js . 各个组件之间的数据流大致如下:

  1. 用户打开Notebook文档

  2. Notebook前端javascript加载Notebook配置

  3. bundler前端JS为配置中的所有bundler扩展创建菜单项

  4. 用户单击bundler菜单项

  5. JS单击处理程序打开一个新的浏览器窗口/选项卡 <notebook base_url>/bundle/<path/to/notebook>?bundler=<name> (即HTTP GET请求)

  6. bundle处理程序验证Notebook路径和bundler name

  7. 捆绑处理程序将请求委托给 bundle bundler的函数 module_name

  8. bundle 函数完成HTTP请求