scrapbook

scrapbook是一个库，用于记录笔记本的数据值（碎片）和生成的视觉内容（快照）。这些记录的碎片和快照可以在未来读取。

scrapbook引入了两个新的信息名称

• 碎片：可序列化的数据值，如字符串、对象的列表、pandas数据框或数据表引用。
• 快照：名为信息显示，如生成的图像、图表或UI消息，封装信息但不存储底层数据。

用例

笔记本用户可能希望记录在笔记本执行期间产生的数据。然后可以读取这些记录的数据在稍后的时间使用，或将其传递给另一个笔记本作为输入。

scrapbook让您

• 持久化笔记本中的数据（碎片）
• 在笔记本中草绘命名显示（快照）
• 召回任何持久化的数据碎片或显示的快照
• 总结笔记本集合

API调用

Scrapbook添加了一些基本的API命令，可以启用数据保存和检索。

glue持久化碎片

在指定的笔记本单元中记录一个碎片（数据值）。

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

sb.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, 'arrow')

剪贴簿库可以稍后用于从输出笔记本中恢复剪贴（记录的值）。

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

剪贴簿将根据已注册数据转换器的值类型暗示存储格式。或者，可以通过将storage参数设置为特定转换器的注册名称（例如"json"）来覆盖暗示的存储格式。

这些数据通过生成具有特殊媒体类型的显示输出以标识内容存储格式和数据来持久化。这些输出在笔记本渲染中不可见，但仍然存在于文档中。剪贴簿随后可以通过读取这些单元输出在未来重新激活与笔记本关联的数据。

sketch用于保存显示输出

以可检索的方式显示命名快照（可见的显示输出）。

与glue不同，sketch旨在为笔记本界面生成可渲染的可见显示输出。

# record an image highlight
sb.sketch("sharable_png", IPython.display.Image(filename=get_fixture_path("sharable.png")))
# record a UI message highlight
sb.sketch("hello", "Hello World")

与剪贴相似，这些可以在稍后检索。与剪贴不同，高亮显示不携带任何实际的基础数据，仅保留某些对象的显示结果。

nb = sb.read_notebook('notebook.ipynb')
# Returns the dict of name -> snap pairs saved in `nb`
nb.snaps

更有用的一点是，您可以将早期笔记本执行中的快照复制到当前笔记本中重新显示对象。

nb = sb.read_notebook('notebook.ipynb')
nb.copy_highlight("sharable_png")

read_notebook读取一个笔记本

从指定在path的路径处加载的笔记本对象中读取笔记本对象。您已经在上述API调用示例中看到过这个函数的使用方法，但基本上这提供了一个薄薄的包装，用于在nbformat笔记本对象上提取剪贴簿剪贴和快照的能力。

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

这种抽象使得保存的内容可以作为参考每个键和源的数据框可用。在以后的版本中将提供更多此类方法。

# Produces a data frame with ["name", "value", "type", "filename"] as columns
nb.scrap_dataframe

笔记本对象还包含一些用于与papermill的笔记本对象模型向后兼容的旧功能函数。因此，它可用于读取papermill执行统计信息以及剪贴簿抽象。

nb.cell_timing # List of cell execution timings in cell order
nb.execution_counts # List of cell execution counts in cell order
nb.papermill_metrics # Dataframe of cell execution counts and times
nb.parameter_dataframe # Dataframe of notebook parameters
nb.papermill_dataframe # Dataframe of notebook parameters and cell scraps

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

read_notebooks读取多个笔记本

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

# create a scrapbook named `book`
book = sb.read_notebooks('path/to/notebook/collection/')
# get the underlying notebooks as a list
book.sorted_notebooks

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

book.scraps # Map of {notebook -> {name -> scrap}}
book.flat_scraps # Map of {name -> scrap}

或收集快照

book.snaps # Map of {notebook -> {name -> snap}}
book.flat_highlights # Map of {name -> snap}

剪贴簿集合可以用于将集合中的所有快照以Markdown结构化输出的方式display。

book.display()

此显示可以按快照名称和键进行筛选，以及启用或禁用显示的总体标题。

最后，剪贴簿有两个向后兼容的旧papermill功能特性

book.papermill_dataframe
book.papermill_metrics

这些函数也依赖于papermill注册的iorw来列出和读取各种来源的文件。

存储格式

存储格式可通过键名访问注册在translators.registry对象上的转换器对象。要注册新的数据转换器/加载器，只需调用

# add translator to the registry
registry.register("custom_store_name", MyCustomTranslator())

存储类必须实现两个方法，translate和load

class MyCustomTranslator(object):
    def translate(self, scrap):
        pass  # TODO: Implement

    def load(self, scrap):
        pass  # TODO: Implement

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

unicode

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

sb.glue("hello", "world", "unicode")

json

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

arrow

待实施！

papermill已弃用的record功能

剪贴簿提供了一种强大且灵活的记录模式。这个库旨在取代papermill现有的record功能。

papermill记录文档概述

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在之后通过读取输出笔记本到一个dataframe来恢复记录的值。

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

限制和挑战

• record函数并没有遵循papermill对笔记本代码库线性执行的模式。 (这周将record描述为papermill的一个额外功能显得有些尴尬。它真的感觉像是在描述一个发展较慢的第二个库。)
• 记录/读取需要将所有数据转换为JSON，这对于dataframes来说是一个繁琐且痛苦的过程。
• 将记录的值读入dataframe会导致不直观的dataframe形状。
• 相比其他可以注册自定义操作符的papermill组件，其模块化和灵活性较低。