scrapbook

剪貼簿

剪貼簿庫將筆記本的資料值和產生的視覺內容記錄為「剪貼簿」。記錄的碎片可以在將來讀取。

有關如何使用剪貼簿的更多信息，請參閱剪貼簿文件。

使用案例

筆記本使用者可能希望記錄筆記本執行期間產生的資料。這些記錄的數據，即 scraps ，可以在以後使用，或在工作流程中傳遞到另一個筆記本作為輸入。

也就是說，剪貼簿可以讓您：

• 將資料和視覺內容作為碎片保留在筆記本中顯示

• 呼叫任何持久的資料片段

• 總結筆記本收藏

Python版本支援

本函式庫的長期支援目標是 Python 3.6+。目前，它還支援 Python 2.7，直到 Python 2 於 2020 年停止使用。

安裝

使用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, 'arrow')

稍後可以使用剪貼簿庫從輸出筆記本中恢復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.調節膠

此抽象化也使保存的內容可作為引用每個密鑰和來源的資料幀。更多這些方法將在以後的版本中提供。

 # 產生一個資料框，其中["name", "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」關聯的片段。 , "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 # 傳回一個帶有`data` 的`Scrap` `` ``類型為任何類型，通常特定於編碼器名稱

這可以將碎片讀取轉換為表示其內容或位置的 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 。