scrapbook

剪贴簿

剪贴簿库将笔记本的数据值和生成的视觉内容记录为“剪贴簿”。记录的碎片可以在将来读取。

有关如何使用剪贴簿的更多信息，请参阅剪贴簿文档。

使用案例

笔记本用户可能希望记录笔记本执行期间产生的数据。这些记录的数据，即 scraps ，可以在以后使用，或者在工作流程中传递到另一个笔记本作为输入。

也就是说，剪贴簿可以让您：

• 将数据和视觉内容作为碎片保留在笔记本中显示

• 调用任何持久的数据片段

• 总结笔记本收藏

Python版本支持

该库的长期支持目标是 Python 3.6+。目前，它还支持 Python 2.7，直到 Python 2 于 2020 年停止使用。在此日期之后，Python 2 支持将停止，并且仅维护 3.x 版本。

安装

使用pip安装：

pip install scrapbook

为了安装可选的 IO 依赖项，您可以指定单独的存储包，例如s3或azure ：

pip install scrapbook[s3]

或使用all ：

pip install scrapbook[all]

---

模型和术语

剪贴簿定义了以下项目：

• scraps ：可序列化的数据值和可视化，例如字符串、对象列表、pandas 数据框、图表、图像或数据引用。

• notebook ：一个包装的 nbformat 笔记本对象，具有与剪贴簿交互的额外方法。

• 剪贴簿：笔记本的集合，带有用于询问集合问题的界面。

• 编码器：数据与笔记本存储格式之间的注册转换器。

scrap模型

scrap模型在元组中包含一些关键属性，包括：

• name : 剪贴簿留言的名称

• data ：剪贴簿 API 调用捕获的任何数据

• 编码器：用于对笔记本数据进行编码/解码的编码器的名称

• display ：IPython 用于显示可视内容的任何显示数据

---

应用程序编程接口

Scrapbook 添加了一些基本的 api 命令，可以保存和检索数据，包括：

• glue以保留有或没有显示输出的碎片

• read_notebook读取一本笔记本

• scraps提供了一个可搜索的字典，其中包含按名称排列的所有剪贴簿留言

• reglue将另一个笔记本中的碎片复制到当前笔记本

• read_notebooks从给定路径读取许多笔记本

• scraps_report显示有关收集的剪贴簿留言的报告

• papermill_dataframe和papermill_metrics用于向后兼容两个已弃用的 papermill 功能

以下部分提供了有关这些 api 命令的更多详细信息。

glue废料

在给定笔记本单元中记录scrap （数据或显示值）。

可以在稍后检查输出笔记本时检索scrap （记录值）。

 """记录数据值的glue示例"""将剪贴簿导入为 sbsb.glue("hello", "world")sb.glue("number", 123)sb.glue("some_list", [1, 3, 5])sb.glue("some_dict", {"a": 1, "b": 2})sb.glue("non_json", df, '箭'）

稍后可以使用剪贴簿库从输出笔记本中恢复scraps ：

 # 读取笔记本并获取之前记录的 scrapsnb = sb.read_notebook('notebook.ipynb')nb.scraps

剪贴簿将通过任何注册的数据编码器的值类型来暗示存储格式。或者，可以通过将encoder参数设置为特定编码器的注册名称（例如"json" ）来覆盖隐含的编码格式。

通过生成具有标识内容编码格式和数据的特殊媒体类型的显示输出来保留该数据。这些输出在笔记本渲染中并不总是可见，但仍然存在于文档中。然后，剪贴簿可以通过读取这些单元输出来重新水化与笔记本相关的数据。

带显示输出

要显示具有可见显示输出的命名片段，您需要指示片段可直接渲染。

这可以通过切换display参数来完成。

 # 记录 UI 消息以及输入字符串 b.glue("hello", "Hello World", display=True)

该调用将保存 Scrap 对象的数据和显示属性，使其可见并对原始数据进行编码。这依赖于IPython.core.formatters.format_display_data函数将数据对象转换为显示和元数据字典，以供笔记本内核解析。

可以使用的另一种模式是指定仅应保存显示数据，而不是原始对象。这是通过设置要display的编码器来实现的。

 # 记录没有原始输入对象的图像b.glue("sharable_png", IPython.display.Image(filename="sharable.png"),encoder='display')

最后，可以通过传递列表、元组或字典对象作为显示参数来控制生成的媒体类型。

 sb.glue("media_as_text_only", media_obj,编码器='display',display=('text/plain',) #这将[text/plain]传递给format_display_data的包含参数)sb.glue("media_without_text", media_obj,编码器='display', display={'exclude': 'text/plain'} # 转发到 format_display_data 的 kwargs)

与数据碎片一样，可以稍后通过访问碎片的display属性来检索这些数据碎片。尽管通常人们只会使用笔记本的reglue方法（如下所述）。

read_notebook读取一本笔记本

读取从path指定的位置加载的 Notebook 对象。您已经在上面的 api 调用示例中了解了如何使用此函数，但本质上，这在nbformat的 NotebookNode 上提供了一个薄包装器，并且能够提取剪贴簿碎片。

 nb = sb.read_notebook('notebook.ipynb')

此 Notebook 对象遵循 nbformat 的 json 架构，允许访问其所需字段。

 nb.cells # 笔记本中的单元格nb.metadatanb.nbformatnb.nbformat_minor

还提供了一些其他方法，其中大部分方法在下面进行了更详细的概述：

 nb.废料nb.调节胶

该抽象还使保存的内容可作为引用每个密钥和源的数据帧。更多这些方法将在以后的版本中提供。

 # 生成一个数据框，其中 ["n​​ame", "data", "encoder", "display", "filename"] 作为 columnsnb.scrap_dataframe # 警告：如果数据或显示很大，这可能是一个大对象

Notebook 对象还具有一些遗留功能，用于向后兼容 papermill 的 Notebook 对象模型。因此，它可用于读取造纸厂执行统计数据以及剪贴簿摘要：

 nb.cell_timing # 按单元顺序排列的单元执行计时列表 nb.execution_counts # 按单元顺序排列的单元执行计数列表 nb.papermill_metrics # 单元执行计数和时间的数据帧 nb.papermill_record_dataframe # 笔记本记录的数据帧（仅包含数据的碎片）nb.parameter_dataframe #笔记本参数的数据框nb.papermill_dataframe # 笔记本参数和单元格碎片的数据框

笔记本阅读器依靠 papermill 注册的 iorw 来访问各种来源，例如但不限于 S3、Azure 和 Google Cloud。

scraps提供名称 -> scrap 查找

scraps方法允许访问特定笔记本中的所有剪贴簿片段。

 nb = sb.read_notebook('notebook.ipynb')nb.scraps # 按名称打印所有剪贴簿留言的字典

该对象还有一些附加方法以方便转换和执行。

 nb.scraps.data_scraps # 过滤为仅与“data”关联的片段 nb.scraps.data_dict # 将“data_scraps”映射到“name” -> “data” dictnb.scraps.display_scraps # 过滤为仅与“display”关联的片段 nb.scraps.display_scraps # 过滤为仅与“display”关联的片段。 scraps.display_dict # 将 `display_scraps` 映射到 `name` -> `display` dictnb.scraps.dataframe # 生成一个以 ["name", "data", "encoder", "display"] 作为列的数据帧

这些方法允许简单的用例不需要挖掘模型抽象。

reglue将片段复制到当前笔记本中

使用reglue可以将粘在一本笔记本上的任何废料粘到当前笔记本上。

 nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # 这会复制数据并显示

任何数据或显示信息都将被逐字复制到当前正在执行的笔记本中，就像用户在原始源上再次调用glue一样。

还可以在此过程中重命名废料。

 nb.reglue("table_scrap", "old_table_scrap")

最后，如果有人希望尝试重新粘合而不检查是否存在，则可以将raise_on_missing设置为仅在失败时显示一条消息。

 nb.reglue("maybe_missing", raise_on_missing=False)# => "在此笔记本中未找到名为 'maybe_missing' 的剪贴簿留言”

read_notebooks读取许多笔记本

将给定path中的所有笔记本读入剪贴簿对象。

 # 创建一个名为 `book` 的剪贴簿 book = sb.read_notebooks('path/to/notebook/collection/')# 将底层笔记本作为 listbook.notebooks # 或 `book.values`

该路径重用 papermill 注册的iorw来列出和读取来自各种来源的文件，以便非本地 url 可以加载数据。

 # 创建一个名为 `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/') 的剪贴簿

剪贴簿（本例中为book ）可用于回忆笔记本集合中的所有剪贴簿：

 book.notebook_scraps # 形状 `notebook` -> (`name` -> `scrap`) 的字典 book.scraps # 形状 `name` -> `scrap` 的合并字典

scraps_report显示有关收集的剪贴簿留言的报告

Scrapbook 集合可用于针对集合中的所有剪贴簿生成scraps_report作为 markdown 结构化输出。

 book.scraps_report()

此显示可以过滤剪贴簿和笔记本名称，以及启用或禁用显示的整体标题。

 book.scraps_report( scrap_names=["scrap1", "scrap2"], notebook_names=["result1"], # 匹配 `/notebook/collections/result1.ipynb` 路径笔记本
  标题=假）

默认情况下，报告将仅填充视觉元素。还要报告数据元素集 include_data。

 book.scraps_report(include_data=True)

造纸厂支持

最后，剪贴簿为已弃用的papermill功能提供了两个向后兼容的功能：

 book.papermill_dataframebook.papermill_metrics

编码器

编码器可以通过键名访问到针对encoders.registry对象注册的Encoder对象。要注册新的数据编码器，只需调用：

 from编码器导入注册表作为encoder_registry#将编码器添加到注册表encoder_registry.register("custom_encoder_name", MyCustomEncoder())

编码类必须实现两个方法， encode和decode ：

 class MyCustomEncoder(object):defencode(self, scrap):# scrap.data 是任意类型，通常特定于编码器 namepass # 返回 `Scrap` ，`data` 类型为 [None, list, dict, *six 之一.integer_types, *six.string_types]defdecode(self, scrap):# scrap.data 是 [None, list, dict, *six.integer_types, *six.string_types]pass # 返回一个 `Scrap`，`data` 类型为任意类型，通常特定于编码器名称

这可以将碎片读取转换为表示其内容或位置的 json 对象，并将这些字符串加载回原始数据对象。

text

一种基本的字符串存储格式，将数据保存为 python 字符串。

 sb.glue(“你好”，“世界”，“文本”)

json

 sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")

pandas

 sb.glue("pandas_df",pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]}), "pandas")

papermill 已弃用的record功能

剪贴簿提供了强大且灵活的记录模式。该库取代了 papermill 现有的record功能。

ReadTheDocs 上存在造纸厂record的文档。简而言之，已弃用的record功能：

pm.record(name, value) ：允许使用笔记本保存值 [API 文档]

 pm.record("hello", "world")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" ：1，“b”：2}）

pm.read_notebook(notebook) ：稍后可以使用 pandas 通过将输出笔记本读入数据帧来恢复记录的值。例如：

 nb = pm.read_notebook('notebook.ipynb')nb.dataframe

Papermill record弃用的理由

由于以下限制和挑战，Papermill 的record功能已被弃用：

• record功能并没有遵循造纸厂笔记本的线性执行模式。将record描述为造纸厂的附加功能很尴尬，而且感觉就像描述第二个不太发达的图书馆。

• 记录/读取所有内容所需的数据转换为 JSON。对于数据帧来说，这是一个乏味且痛苦的过程。

• 将记录的值读入数据帧会导致数据帧形状不直观。

• 与可以注册自定义操作员的其他造纸厂组件相比，模块化和灵活性较低。

为了克服 Papermill 的这些限制，我们决定创建Scrapbook 。