应用 Jupyter Notebooks（应用 Jupytext 和 Papermill）主动生成报告

本文源码下载：笔记本来形容特定年份的世界人口和国内生产总值。应用简略：只需 year 在第一个单元格中更改变量，而后从新运行，即可取得所选年份的图表。但这须要手动干涉。如果能够主动执行更新并为每个可能的 year 参数值生成报告，将会更加不便（更一般而言，笔记本计算机不仅能够基于一些用户提供的参数，而且还能够通过与参数的连贯来更新其后果。数据库等）。

版本控制

在业余环境中，笔记本电脑是由数据科学家设计的，然而在生产环境中运行笔记本电脑的工作可能会由其余团队来解决。因而，一般而言，人们必须共享笔记本。最好通过版本控制系统来实现。

Jupyter 笔记本因其版本控制的难度而闻名。让咱们思考下面的笔记本，文件大小为 3 MB，其中大部分由嵌入式 Plotly 库奉献。如果咱们删除第二个代码单元的输入，笔记本将小于 80 KB。删除所有输入后，大小仅为 1.75 KB。这表明它的多少内容与纯代码无关！如果咱们不留神的话，笔记本中的代码更改将失落大量的二进制内容。
为了取得有意义的差别，咱们应用 Jupytext（免责申明：我是 Jupytext 的作者）。Jupytext 能够应用 pip 或装置 conda。重新启动笔记本服务器后，Jupyter 中将呈现一个 Jupytext 菜单：

咱们单击将笔记本与 Markdown 配对，保留笔记本 …，而后取得笔记本的两种示意模式：（world_fact.ipynb 具备输出和输入单元格）和 world_fact.md（仅具备输出单元格）。
Jupytext 将笔记本示意为 Markdown 文件与所有次要的 Markdown 编辑器和查看器兼容，包含 GitHub 和 VS Code。Markdown 版本例如由 GitHub 出现为：

如您所见，Markdown 文件不蕴含任何输入。实际上，因为咱们只须要共享笔记本代码，因而咱们不心愿在此阶段应用它。Markdown 文件还具备十分清晰的差别历史记录，这使笔记本的版本控制变得简略。

该 world_facts.md 文件由 Jupyter 当您保留在笔记本自动更新。反之亦然！如果 world_facts.md 应用文本编辑器进行批改，或者通过从版本控制系统中提取最新的内容进行批改，则在浏览器中刷新笔记本时，更改将显示在 Jupyter 中。

在咱们的版本控制系统中，咱们只须要跟踪 Markdown 文件（甚至能够显式疏忽所有.ipynb 文件）。显然，执行笔记本的团队须要从新生成 world_fact.ipynb 文档。为此，他们在命令行中应用 Jupytext：

$ jupytext world_facts.md --to ipynb
[jupytext] Reading world_facts.md
[jupytext] Writing world_facts.ipynb

当初，咱们正在正确地对笔记本进行版本控制。差别历史更加清晰。例如，查看咱们的报告中减少的国内生产总值的样子：

Jupyter 笔记本作为脚本？

作为 Markdown 示意的代替办法，咱们能够 world_facts.py 应用 Jupytext 将笔记本与脚本配对。如果您的笔记本中蕴含的代码多于文本，则应尝试一下。这通常是迈向残缺而高效的长笔记本重构的第一步，一旦笔记本被示意为脚本，您就能够提取任何简单的代码，并应用 IDE 中的重构工具将其移至（通过单元测试的）库中。

JupyterLab，JupyterHub，Binder，Nteract，Colab 和 Cloud 笔记本？

您是否应用 JupyterLab 而不是 Jupyter Notebook？不必放心：以上办法在这种状况下也实用。您只须要为 JupyterLab 应用 Jupytext 扩展名，而不是应用 Jupytext 菜单。如果您想晓得，Jupytext 也能够在 JupyterHub 和 Binder 中应用。
如果您应用其余笔记本编辑器，例如 Nteract 桌面，CoCalc，Google Colab 或其余云笔记本编辑器，则可能无奈应用 Jupytext 作为编辑器中的插件。在这种状况下，您只需在命令行中应用 Jupytext。闭上你的笔记本电脑和注入的配对信息到 world_facts.ipynb 与

$ jupytext --set-formats ipynb，md world_facts.ipynb

而后放弃两个示意与

$ jupytext --sync world_facts.ipynb

笔记本参数

Papermill 是用于执行带参数笔记本的参考库。
造纸厂须要晓得哪个单元格蕴含笔记本参数。只需 parameter 应用 Jupyter Notebook 中的单元格工具栏在该单元格中增加标签即可实现此操作：

在 JupyterLab 中，您能够应用 celltags 扩展名。
并且，如果您违心，也能够间接 world_facts.md 在此处编辑并增加标签：

year = 2000

主动执行

当初，咱们领有在生产服务器上执行笔记本所需的所有信息。

生产环境

为了执行笔记本，咱们须要晓得它应该在哪个环境中运行。在此示例中，当咱们应用 Python 笔记本工作时，咱们将其依赖关系列在 requirements.txt 文件中，这是 Python 我的项目的规范。

为简略起见，咱们还将笔记本工具蕴含在同一环境中，即增加 jupytext 和增加 papermill 到同一 requirements.txt 文件中。严格来说，这些工具能够在另一个 Python 环境中装置和执行。

应用以下任一办法创立相应的 Python 环境

$ conda create -n run_notebook --file requirements.txt -y

或者

$ pip install -r requirements.txt

（如果在虚拟环境中）。
请留神，该 requirements.txt 文件只是指定执行环境的一种形式。该重复性执行环境标准的粘结剂队伍为主题的最残缺的参考资料之一。

继续集成

低劣作法是测试对笔记本计算机或其要求的每个新奉献。为此，您能够应用例如 Travis CI（间断集成解决方案）。您仅须要以下两个命令：

• pip install -r requirements.txt 装置依赖项
• jupytext world_facts.md --set-kernel - --execute 在以后的 Python 环境中测试笔记本的执行状况。

您能够在咱们的 .travis.yml 文件中找到一个具体示例。

咱们曾经在主动执行笔记本了，不是吗？Travis 会通知咱们是否在我的项目中引入了回归…停顿如何！然而咱们还没有 100%实现，因为咱们承诺要应用参数执行笔记本。

应用正确的内核

Jupyter 笔记本与内核（即，指向本地 Python 环境的指针）相关联，然而该内核可能在您的生产计算机上不可用。在这种状况下，咱们只需更新笔记本内核，以指向咱们刚刚创立的环境：

$ jupytext world_facts.ipynb --set-kernel-

请留神，--set-kernel - 下面的减号示意以后的 Python 环境。在咱们的示例中，得出：

[jupytext] Reading world_facts.ipynb
[jupytext] Updating notebook metadata with '{"kernelspec": {"name":"python3","language":"python","display_name":"Python 3"}}' [jupytext] Writing world_facts.ipynb (destination file replaced)

如果您要应用另一个内核，只需将内核名称传递给该 –set-kernel 选项（您能够应用来获取所有可用内核的列表，jupyter kernelspec list和 / 或应用来申明一个新内核python -m ipykernel install --name kernel_name --user）。

用参数执行笔记本

当初，咱们能够应用 Papermill 执行笔记本了。

$ papermill world_facts.ipynb world_facts_2017.ipynb -p year 2017
Input Notebook: world_facts.ipynb Output Notebook: world_facts_2017.ipynb 100%|██████████████████████████████████████████████████████| 8/8 [00:04<00:00, 1.41it/s]

功败垂成！笔记本已执行，文件 world_facts_2017.ipynb 蕴含输入。

公布笔记本

当初该交付刚刚执行过的笔记本了。兴许您想在邮箱中找到它？或者，兴许您心愿取得一个能够查看后果的 URL？咱们介绍了几种办法。

GitHub 能够显示 Jupyter 笔记本。这是一个不便的解决方案，因为您能够轻松抉择谁能够拜访存储库。只有您在笔记本中不蕴含任何交互式 JavaScript 图或小部件，此办法就能够很好地工作（GitHub 疏忽 JavaScript 局部）。就咱们的笔记本而言，交互式绘图未呈现在 GitHub 上，因而咱们须要另一种办法。

另一个抉择是应用 Jupyter Notebook Viewer。该 nbviewer 服务能够使任何笔记本电脑是在 GitHub 上公开。因而，咱们的笔记本在此处正确渲染。如果您的笔记本不是公开的，则能够抉择在本地装置 nbviewer。

或者，您能够将执行的笔记本转换为 HTML，并将其公布在 GitHub 页面上，或在您本人的 HTML 服务器上，或通过电子邮件发送。轻松将笔记本转换为 HTML

$ jupyter nbconvert world_facts_2017.ipynb --to html
[NbConvertApp] Converting notebook world_facts_2017.ipynb to html [NbConvertApp] Writing 3361863 bytes to world_facts_2017.html

生成的 HTML 文件包含以下代码单元：

然而，兴许您不想看到 HTML 中的输出单元格？您只须要增加 –no-input：

$ jupyter nbconvert --to html --no-input world_facts_2017.ipynb --output world_facts_2017_report.html

您会失去一份更清晰的报告：

将独立的 HTML 文件作为附件发送到电子邮件中很容易。也能够将报告嵌入到电子邮件注释中（但交互式绘图无奈应用）。

最初，如果您正在寻找一份欠缺的报告并且对 LaTeX 有所理解，则能够尝试 Jupyter 的 nbconvert 命令的 PDF 导出选项。

应用管道

应用命名文件的代替办法是应用管道。jupytext，nbconvert 并且 papermill 所有人都反对它们。以前的命令的单行代替是：

$ cat world_facts.md \ 
| jupytext --from md --to ipynb --set-kernel - \ 
| papermill -p year 2017 \ 
| jupyter nbconvert --stdin --output world_facts_2017_report.html

论断

当初，您应该可能基于 Jupyter 笔记本电脑建设用于在生产中生成报告的残缺管道。咱们曾经看到了如何：

• 应用 Jupytext 版本控制笔记本
• 在多个用户之间共享笔记本及其依赖项
• 继续集成测试笔记本
• 应用 Papermill 执行带有参数的笔记本
• 最初，如何公布笔记本（在 GitHub 或 nbviewer 上），或将其出现为动态 HTML 页面。

本示例中应用的技术齐全基于 Jupyter Project，它是数据迷信的事实上的规范。这里应用的工具都是开源的，并且能够与任何继续集成框架一起很好地工作。
您领有打算和交付通过微调的，无代码的报告所需的所有！

结语

这里应用的工具是用 Python 编写的。然而它们与语言无关。感激 Jupyter 框架，它们实际上实用于存在 Jupyter 内核的 40 多种编程语言中的任何一种。

当初，假如您曾经编写了一个蕴含一些 Bash 命令行的文档，就像这篇博客文章一样。装置 Jupytext 和 bash 内核，博客文章将成为此交互式 Jupyter 笔记本！

更进一步，咱们是否应该确保帖子中的每条指令都切实有效？咱们通过继续的集成来做到这一点……扰流板警报：就像 jupytext –execute README.md！一样简略！

致谢

Marc 感激 Eric Lebigot 和 Florent Zara 对本文的奉献，并感激 CFM 通过其开源打算反对这项工作。

对于作者

本文由 Marc Wouts 撰写。Marc 于 2012 年退出 CFM 的钻研团队，从事过从最佳交易到投资组合构建的一系列钻研我的项目。

Marc 始终对寻找无效的工作流以进行波及数据和代码的合作钻研感兴趣。在 2015 年，他编写了一个外部工具，用于在 Atlassian 的 Confluence Wiki 上公布 Jupyter 和 R Markdown 笔记本，为在笔记本上进行合作提供了第一个解决方案。在 2018 年，他编写了 Jupytext 这个开源程序，该程序可简化 Jupyter 笔记本的版本控制。Marc 也对数据可视化感兴趣，并在 CFM 协调无关此主题的工作组。

Marc 于 2007 年取得巴黎狄德罗大学的概率论博士学位。

免责申明

本文档中蕴含的所有观点均形成其作者的判断，并不一定反映资本基金治理公司或其任何分支机构的观点。本文档中提供的信息仅是个别信息，不形成投资或其余倡议，如有更改，恕不另行通知。以上成绩源自 Google 翻译。微信 yujiabuao.