jupyter-require 0.6.1

关于

jupyter-require库旨在用于Jupyter笔记本。

Jupyter-require允许执行和管理自定义JavaScript和CSS文件，甚至可以直接从Jupyter笔记本创建和加载自己的样式和脚本。

Jupyter-require提供了一个独特的定制Jupyter笔记本的机会，使用户能够在考虑同步需求和安全性影响的同时，手工制作自己的JavaScript增强工作流程。

这是用来做什么的？

让我们通过一个示例来演示用法。请注意，用法仅限于您的想象力，这只是一个单一用例的演示。

如果您像我一样对数据可视化感兴趣，您可能已经听说过d3.jsJavaScript生态系统。这是一个功能强大的工具，可以用于创建高级交互式可视化。

然而，它在Jupyter笔记本中使用并不舒适，更不用说与Python集成。

请参阅有关在Jupyter笔记本中自定义D3.js可视化的文章。

这就是 jupyter-require（jupyter-require）以及相关的 jupyter-d3 发挥作用的地方。jupyter-require 允许您轻松地引入自定义脚本（如 d3）和样式，并在笔记本中使用它们。

还可以查看 jupyter-d3，它将 Jupyter 笔记本中的 d3 工作流程提升到另一个层次。

安装

要安装 jupyter-require Python 包

pip install jupyter-require

[可选] 这一步是可选的，但如果您发现扩展没有正确加载（或根本没有加载），请先尝试执行以下命令。

jupyter nbextension install --user --py jupyter_require

您也可以从 Python 解释器中完成所有这些操作。要安装 nbextension 并启用它，我们在 jupyter-nbutils utils 模块中提供了辅助函数。

from jupyter_nbutils import utils

# install jupyter-require extension
utils.install_nbextension('jupyter_require', overwrite=True)  # note there is an underscore, it's Python module name

# load and enable the extension
utils.load_nbextension('jupyter-require', enable=True)

所有这些都可以在命令行中完成，因此如果您习惯于使用常规方式安装 nbextensions，请随时这样做。实际上，强烈建议这样做，这种方法只是为了像我这样的懒人。

注意：您可能需要重新加载页面（只需按 F5），以便 jupyter-require nbextension 能够正确初始化。

示例用法

在 Jupyter 笔记本中

# Applicable for version <=0.3.0
%load_ext jupyter_require

NOTE: Since the version 0.3.1 this extension is autoloaded and this step is no longer required

%requirejs d3 https://d3js.org/d3.v5.min
%requirejs d3-hierarchy https://d3js.org/d3-hierarchy.v1.min

NOTE: Note that the path does **NOT** contain the `.js` file extension. This is `requireJS`_ standard.

from jupyter_require import require
from jupyter_require import load_css

require.config({
  'd3': 'https://d3js.cn/d3.v5.min'
  'd3-hierarchy': 'https://d3js.cn/d3-hierarchy.v1.min'
})

load_css(...)  # stylesheet goes here

执行自定义脚本

现在我们可以真正利用 Python 和 JS 之间的双向通信了

假设我们有以下 d3 脚本

注意：我假设我们在 Jupyter 笔记本环境中工作，因此我们有可用的上下文单元格。

/**
 * @module
 * @description  Print coloured circles into the cell output
 * @file  d3-simple-example.js
 */

 // Inspired by: https://www.d3-graph-gallery.com/intro_d3js.html

// create SVG element in the output area
// the ``element`` is a contextual binding to the output of the current cell
let svg = d3.select(element.get(0))
  .append('svg');

// create group
let g = svg.append('g');

g.append("circle")
  .attr("cx", 2).attr("cy", 2).attr("r", 40).style("fill", "blue");
g.append("circle")
  .attr("cx", 140).attr("cy", 70).attr("r", 40).style("fill", "red");
g.append("circle")
  .attr("cx", 300).attr("cy", 100).attr("r", 40).style("fill", "green");

现在，为了在单元格中执行脚本，我们必须告诉它使用 d3。execute_with_requirements 就是为了这个目的而设计的。

from pathlib import Path
from jupyter_require import execute_with_requirements

script = Path('d3-simple-example.js').read_text()

execute_with_requirements(script, required=['d3'])

您应该会看到这三个漂亮的圆圈 :point_up: 。

⚠️ 可能当前的 markdown 渲染器无法渲染上面的原始 </svg> 元素，所以请自己试试看！ :smirk

当然还有更多，但我将留给您去探索。

同步性

JavaScript 执行默认情况下是异步的。在 Jupyter 笔记本中更是如此。执行自定义 JavaScript 脚本将异步发生，其余笔记本不会等待执行完成。

这通常不是我们期望的行为，因为我们可能需要在下一个单元格中使用执行的结果。

Jupyter-require 通过将每个执行的脚本转换为 Promise 并在等待它时暂停 Python 内核的执行来解决此问题。

执行 & 安全性 – 安全脚本 和 清理

在 Jupyter 笔记本中，JavaScript 通常是如何存储（以及如何处理）的，有时可能有些不幸。jupyter-require 引入了 安全脚本 和 清理 的概念。我们先看看后者。

清理

当用户通过原生的Jupyter API执行脚本时，通常像这样display(Javascript("""..."""))，幕后的操作实际上非常复杂。然而，现在的一个重要的事情是，整个脚本被嵌入到单元格输出和生成的*.ipynb文件中。然后，每次复制或重新创建单元格（即，在笔记本重新加载时），脚本都会被执行。由于这个执行不是沙箱化的。实际上，它是在窗口上下文中使用eval函数执行的。

参考：官方MDN网络文档中的“永远不要使用eval！”部分。

这可能会造成潜在的安全威胁！此外，如果您不想共享生成输出的脚本，但希望输出存在，这也不会发生。

我们一步步地解决这个问题，我们的方法也不是最优的，但它确实带来了一些改进，并且我们相信随着时间的推移，它会变得更好。在执行脚本时使用jupyter-require execute_with_requirements函数，嵌入的不是脚本，而是单元格携带的函数对象本身。这使得当复制/粘贴单元格或剪切单元格时，可以重新执行脚本。

此外，我们不像Jupyter默认那样在窗口上下文中使用eval函数评估脚本，而是在当前的开发状态下，将其包裹在其自己的函数作用域中，并手动设置其this和element上下文。

好吧，还没有提到清理，对吧？在这个上下文中，清理意味着丢弃生成输出的JavaScript代码，清理元数据，并将单元格输出区域中显示的输出保存到静态状态。回到d3的例子，清理单元格将使我们所生成的图表持久化并可JSON序列化。输出将在nbviewer或GitHub ipynb预览中可见。

⚠️ SVG提出了另一个安全问题，因此GitHub可能不会显示它们以防止这种情况，例如，参见这个讨论。我们将在未来尝试解决这个问题。

我们正在考虑如何将执行和输出进一步沙箱化，但请记住，这个项目非常年轻，所以让我们一步一步来。

要最终确定您的输出，请使用右侧的“保存和清理”操作按钮，该按钮应位于常规“保存和检查点”按钮的右侧。在您正确关闭笔记本时，也会自动执行清理。我们目前无法处理SIGTERMs，所以请注意，在这种情况下，脚本将被丢弃，输出将丢失。

安全脚本

⚠️ 安全脚本的概念是最近添加的，并且正在受到密切关注。

通过“安全”一词，我们不是指减少安全威胁的执行，不是这样的。是您保证脚本是安全的，并且可以被视为这样的。我们处理“安全脚本”的机制与上述描述的非常相似，但有一个重要的变化：安全脚本在某种程度上类似于默认的Jupyter笔记本行为，因为它们也会在笔记本重新加载时执行，并且也存储在生成的`*.ipynb`笔记本文件中。

因此，您可以在脚本存储在输出中的同时享受沙盒（类似）同步执行的好处。唯一的限制是，它们不允许指定要求，就像execute_with_requirements函数通过其required参数所做的那样。这是因为这些脚本可以在扩展实际加载之前执行，我们无法保证（至少我们现在不知道）jupyter-require的功能将在那时存在。

要将您的脚本视为安全脚本，请使用safe_execute函数执行它。

脚注

作者：Marek Cermak <macermak@redhat.com>