notebook-restified 0.1.0

简介

notebook_restified 是一个库，它将Jupyter笔记本视为具有 输入参数 和适合用作REST端点或其他笔记本内回调函数的 返回值 的独立函数。换句话说，notebook_restified 尝试在Jupyter框架中实现 模型-视图-控制器 上下文。它利用 papermill 读取和参数化笔记本文件，并受到 ipython_blocking 部分目标灵感的启发。

注意事项

此库及其中的思想仍在开发中。这被视为一个alpha（或最多beta）版本，语法可能会改变！我相信这里的想法是可靠的，并将经得起时间的考验，但实现仍在变化。

笔记本生命周期

根据我的经验，许多工作流程实现遵循类似模式。它们从笔记本开始，迁移到可能被认为是“生产”的东西，这可能或可能没有Jupyter/笔记本连接。希望这一部分能与你在企业组织中使用Jupyter的经验产生共鸣。

首先，笔记本作者在“便签”风格的笔记本中探索问题空间：查询API以获取数据、清理和合并数据、回答有关数据的问题。在此阶段，在代码单元中定义用户输入变量。应用程序逻辑是线性的、同步的，并分成小型的输入/输出单元，以便更好地理解每个步骤。笔记本的“结果”没有严格定义。

其次，笔记本作者使用Markdown单元格和解释性工具（例如toc2）来记录工作流程。用户输入、应用程序逻辑和笔记本的结果自第一步以来没有变化。现在笔记本已准备好供公众使用，并且章节（输入是什么，结论是什么，工作流程中的步骤是什么）更加明确地列出。

第三，笔记本作者将笔记本重构为“仪表板”模式（例如voila），这意味着用户不应该看到或与代码交互。这种模式对代码感到害怕的客户或需要经过同行评审/合规性评审然后成为“不可变”的笔记本非常有吸引力。

在第三步中，用户输入来自ipywidgets表单，而不是在代码单元中定义。应用程序逻辑被重构为回调函数，而不是线性/同步/内省的。尽管生成结果的代码不是交互式的，但笔记本的结果本质上是交互式的。

可选地，第三步可能是将原始笔记本的应用程序逻辑重构为REST端点。用户输入是URL参数或POST的正文。"用户"（通常是其他程序/服务）当然看不到代码。笔记本的结果（Web应用？）非常严格地定义，并且不是交互式的。

最后，当第三步出现问题时或笔记本作者想要添加新功能时，他们会“撤销重构”，从仪表板/REST API实现回到更交互式/内省的模式，以在重构之前确定问题。

notebook_restified试图在三种我们使用笔记本的一般方式之间穿梭：交互模式、小部件化仪表板以及作为REST API。

Binder演示

即将推出更多演示。

安装

notebook_restified在Pypi上，可以使用pip进行安装

pip install notebook_restified

要启用Jupyter服务器上的/restified/端点并将笔记本作为REST端点执行，请使用以下命令启用服务器扩展

jupyter serverextension enable notebook_restified --sys-prefix

模型

notebook_restified的核心是将笔记本视为MVC（模型-视图-控制器）意义上的模型。在交互模式下，模型笔记本与任何其他Jupyter笔记本没有区别：内省的、探索性的、解释性的。模型笔记本中不应包含任何小部件/用户界面/用户交互代码——这些代码保留给可以在仪表板模式下运行的视图笔记本。或者，模型笔记本可以执行为REST端点。

模型笔记本应具有单元标签（见下文），它们参数化笔记本，定义不应在REST/回调函数模式下执行的单元，以及笔记本的“返回”值。到目前为止，有三种模型执行实现：PythonModel和KernelModel。

PythonModel使用exec和eval在代码单元上执行笔记本。使用PythonModel的好处是它在与使用它的视图笔记本相同的内核中运行，因此可以从视图笔记本传递全局变量到模型笔记本。

KernelModel通过启动新的Jupyter内核并在其中运行代码来执行笔记本。使用KernelModel的好处是它是语言无关的。

请参阅Binder示例进行实际演示，但一般来说，模型的语法如下

import notebook_restified
model = notebook_restified.KernelModel('model.ipynb')
params = {'x' : 42, 'string' : 'foo'}
result = model.execute(params)

单元标签

notebook_restified中用于控制笔记本执行方式的标签有三个。

• parameters 用于使用 papermill 库对笔记本进行参数化。在任何定义将要被 execute_notebook(nb_path, params) 或在 /restified/ 端点中的 URL 参数覆盖的变量的单元格中包含此标签。
• skip 用于表示在以 REST 方式运行笔记本或使用 execute_notebook 时不应运行的单元格——信息性图形、内省细节、print 语句等。
• return 是从 execute_notebook 或通过 eval 调用的 RESTful 执行（JSON 编码）最终返回的内容，因此应该是一个非常简单的单元格，不包含 if 语句、赋值等。

restified 端点

当服务器扩展启用时，可以通过将笔记本 URL 中的 /notebooks/ 替换为 /restified/ 来将任何笔记本作为 REST 端点调用。使用 GET 传递任何 parameters 作为 URL 参数，或使用 POST 以 JSON 编码的体传递。

关于笔记本调用笔记本的看法

我通常同意 Joel Grus 关于 将一个笔记本导入另一个笔记本 的观点（视频，图片）。如果一个函数或类在一个笔记本中编写，导入到另一个笔记本中，并在那里使用，那么这对我来说是一个红旗。Python 有包和包结构的理念，没有必要通过将可重用代码放在笔记本中而不是包（.py 文件）中来绕过这个概念。notebook_restified 不从笔记本 A 导入代码到笔记本 B，而是将笔记本作为函数执行。

关于重构的看法

在将代码重构到包中与在回调函数或 Web 应用程序中执行该代码或使用 notebook_restified 在回调函数或 Web 应用程序中在笔记本之间，确实存在一个灰色区域。在我看来，使用的计算方法是可读性和可理解性。在某些方面，包更好（更好的版本控制、单元测试、README/readthedocs）。在其他方面，笔记本可能更好（目录扩展、交互性）。

特定于任务的工作流程，并从丰富的关于传统手法的文档中受益，是 notebook_restified 而不是重构代码的完美候选人。