Python中文社區(qū)(ID:python-china)

你是否曾經(jīng)創(chuàng)建過(guò) Jupyter notebook 并希望可以使用一組不同的參數(shù)生成notebook？這樣做的話你可能至少執(zhí)行了以下操作之一：

•編輯單元格中的變量并重新運(yùn)行notebook，根據(jù)需要保存副本。•保存了notebook的副本，并且可能修改了代碼以直接在 .ipynb 文件中編輯值并重新運(yùn)行notebooks•構(gòu)建了一些自定義代碼以使用從數(shù)據(jù)庫(kù)或配置文件加載的數(shù)據(jù)設(shè)置變量，然后重新運(yùn)行notebook

這個(gè)問(wèn)題有一個(gè)很好的解決方案，可以將交互式筆記本參數(shù)化并與自動(dòng)化作業(yè)很好地共存，這就是所謂的papermill。

動(dòng)機(jī)

許多notebook用戶使用在其notebook頂部附近指定一個(gè)單元格作為全局變量的標(biāo)準(zhǔn)做法。然后修改單元格中的值并運(yùn)行整個(gè)notebook以獲得不同的結(jié)果。為了保持輸出，作者將手動(dòng)下載另一種格式的notebook或?qū)⑵淞泶鏋椴煌膎otebook文件。但是僅使用notebook服務(wù)器和這些手動(dòng)方法很快就會(huì)變得混亂且難以跟蹤，更不用說(shuō)容易出錯(cuò)了。你編輯的是哪個(gè)notebook？ Papermill 有助于解決這個(gè)問(wèn)題。在這篇文章中，我將介紹 papermill 和基本用法，通過(guò)一個(gè)參數(shù)化的例子，最后談?wù)勈褂?cron 完全調(diào)度和自動(dòng)化 notebook 執(zhí)行的方法。

對(duì)于papermill，notebook中的一個(gè)特殊單元格被指定為參數(shù)。當(dāng) papermill 通過(guò)命令行界面 (CLI) 或使用 Python API 執(zhí)行參數(shù)化notebook時(shí)，參數(shù)會(huì)傳入并在后續(xù)單元中執(zhí)行。這允許notebook以不同的參數(shù)快速運(yùn)行多次。然后可以將生成的執(zhí)行后的notebook保存在各種位置，包括本地或云存儲(chǔ)。

安裝

要安裝 papermill，請(qǐng)使用 pip。我建議使用 virtualenv 或 conda 的虛擬環(huán)境。我經(jīng)常推薦使用 pyenv 來(lái)安裝最新的 Python 版本并創(chuàng)建一個(gè) virtualenv虛擬環(huán)境。

pip install papermill 

如果您想使用各種輸入和輸出選項(xiàng)，如 Amazon 的 s3 或 Microsoft 的 azure，您可以安裝所有依賴項(xiàng)。我不會(huì)在這里詳細(xì)介紹，但文檔涵蓋了這些選項(xiàng)，你甚至可以擴(kuò)展 papermill 為notebooks的輸入/輸出 (I/O) 添加其他處理程序。 

pip install papermill[all] 

基本使用

大多數(shù)用戶想要用 papermill 做的第一件事就是參數(shù)化notebook。一旦您運(yùn)行了 Jupyter 并打開了一個(gè)notebook，您需要做的就是將參數(shù)標(biāo)簽添加到包含參數(shù)的單元格中。

保存notebook，現(xiàn)在您可以使用 papermill 執(zhí)行它了。對(duì)于示例notebook，請(qǐng)使用 CLI 運(yùn)行notebook，并提供您自己的名稱。

papermill -p name Matt papermill_example1.ipynb papermill_matt.ipynb 

此命令告訴 papermill 執(zhí)行輸入 notebook papermill_example1.ipynb 并將輸出寫入 papermill_matt.ipynb，同時(shí)將參數(shù)名稱設(shè)置為值 Matt。如果您打開生成的notebook，將在帶有注入?yún)?shù)標(biāo)簽的參數(shù)標(biāo)記之后包含一個(gè)新單元格，如下所示。

您現(xiàn)在應(yīng)該看到如何根據(jù)需要添加盡可能多的參數(shù)，以便從現(xiàn)有notebook制作新notebook。將主notebook（在我們的例子中是papermill_example1.ipynb）想象成一個(gè)模板，您可以使用它通過(guò)快速注入?yún)?shù)來(lái)制作任意數(shù)量的副本。

API 的基本使用

您可能希望使用 Python 代碼獲取或構(gòu)建您注入的參數(shù)，因此還可以使用 Python API 來(lái)執(zhí)行 papermill。我們可以在 Python 腳本中實(shí)現(xiàn)與上述完全相同的結(jié)果（或在notebook中，它在那里也能很好地工作 - 并且會(huì)動(dòng)態(tài)地向您顯示進(jìn)度）。 

import papermill as pm  
name = "Matt"  
res = pm.execute_notebook(  
    'papermill_example1.ipynb',  
    'papermill_{name}.ipynb',  
    parameters = dict(namename=name)  
)  
{"version_major":2,"version_minor":0,"model_id":"cf8280b216094bf6a75a9536b6505051"} 

更多參數(shù)傳遞

到目前為止，我們只傳遞了一個(gè)參數(shù)，并使用了 -p 選項(xiàng)來(lái)實(shí)現(xiàn)這一點(diǎn)。您可以通過(guò)幾種方式傳遞參數(shù)。

命令行

您可以使用示例notebook運(yùn)行所有這些內(nèi)容，然后自己查看結(jié)果。首先，您可以從 CLI 指定多個(gè)參數(shù)。即使notebook中尚不存在參數(shù)，也可以傳入和創(chuàng)建參數(shù)。在這種情況下，papermill 將創(chuàng)建一個(gè)注入?yún)?shù)單元并在notebook頂部執(zhí)行它。

這是一個(gè)例子。 

papermill -p name Matt -p level 5 -p factor 0.33 -p alive True papermill_example1.ipynb papermill_matt.ipynb 

或者用長(zhǎng)選項(xiàng)代替...... 

papermill --parameters name Matt --parameters level 5 --parameters factor 0.33 --parameters alive True papermill_example1.ipynb papermill_matt.ipynb 

請(qǐng)注意， -p 或 --parameters 選項(xiàng)將嘗試解析整數(shù)和浮點(diǎn)數(shù)，因此如果您希望將它們解釋為字符串，請(qǐng)使用 -r 或 --raw 選項(xiàng)以字符串形式獲取所有值。 

papermill -r name Matt -r level 5 -r factor 0.33 -r alive True papermill_example1.ipynb papermill_matt.ipynb 

您還可以使用 yaml 來(lái)指定參數(shù)。這可以通過(guò)文件（-f 或 --parameters_file）、字符串（-y 或 --parameters_yaml）或 base64 編碼字符串（-b 或 --parameters_base64）傳入。這允許您傳入更復(fù)雜的數(shù)據(jù)，包括列表和字典。 

papermill papermill_example1.ipynb papermill_matt.ipynb -y "  
name: Matt  
level: 5  
factor: 0.33  
alive: True  
sizes:  
    - 1.0  
    - 2.5  
    - 3.7  
params:  
    x: 3  
    y: 4" 

您可以很容易地對(duì)字符串進(jìn)行 base64 編碼。（在 Mac 或 Linux 或 Windows WSL 上notebook文件所在目錄中的 shell 中運(yùn)行此命令）。 

echo  "  
name: Matt  
level: 5  
factor: 0.33  
alive: True  
sizes:  
    - 1.0  
    - 2.5  
    - 3.7  
params:  
    x: 3  
    y: 4" > params.yaml 

現(xiàn)在您可以運(yùn)行文件版本。

papermill papermill_example1.ipynb papermill_matt.ipynb -f params.yaml 

或者base64版本 

PARAMS=$(cat params.yaml| base64) # makes the base64 version of the yaml file  
papermill papermill_example1.ipynb papermill_matt.ipynb -b $PARAMS 

無(wú)論哪種方式，你都應(yīng)該了解可以從命令行和 API 將復(fù)雜數(shù)據(jù)傳遞到notebook中。這些示例都使用本地文件系統(tǒng)進(jìn)行notebook的輸入和輸出，但也可以從 Amazon s3、Azure、Google Cloud Storage 或 Web 服務(wù)器讀取和寫入notebook。

檢查notebook

可以從 CLI 檢查notebook的可用參數(shù)。 

$ papermill --help-notebook papermill_example1.ipynb  
Usage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]  
Parameters inferred for notebook 'papermill_example1.ipynb':  
  name: Unknown type (default "Joe") 

或者使用 Python API。

pm.inspect_notebook('papermill_example1.ipynb')  

{'name': {'name': 'name',  
  'inferred_type_name': 'None',  
  'default': '"Joe"',  
  'help': ''}} 

執(zhí)行完整的工作流程

papermill的典型工作流程是擁有一個(gè)參數(shù)化notebook，使用多個(gè)值運(yùn)行它，然后將生成的notebook轉(zhuǎn)換為另一種格式以供審查或報(bào)告。讓我們通過(guò)一個(gè)示例來(lái)了解如何設(shè)置。

首先，我們有一個(gè)使用 Yahoo! 金融 API 來(lái)獲取股票價(jià)格并繪制股票歷史最高價(jià)的數(shù)據(jù)（或者至少是過(guò)去兩年的最高價(jià)，因?yàn)槲掖藭r(shí)只獲取那么多數(shù)據(jù)）。

如果要運(yùn)行此示例，則需要確保已安裝 yfinance API 和 matplotlib。如果需要，您可以使用 pip 安裝兩者。

我們可以使用papermill  CLI 來(lái)檢查參數(shù)。 

$ papermill --help-notebook papermill_example2.ipynb  
Usage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]  
Parameters inferred for notebook 'papermill_example2.ipynb':  
  symbol: Unknown type (default 'AAPL') 

我們將用幾個(gè)符號(hào)運(yùn)行這個(gè)notebook 。我選擇為此使用 shell 腳本，以便我可以通過(guò)計(jì)劃的 cron 程序運(yùn)行它。如果需要，這可以使用簡(jiǎn)單的 Python 腳本輕松完成。但是，如果您使用的是虛擬環(huán)境，您最終可能需要一個(gè)腳本來(lái)確保正確加載 virtualenv。在這種情況下，在整個(gè)過(guò)程中使用 shell 腳本可能會(huì)更容易。

我還將使用 jupyter nbconvert（或者您可以將其作為 jupyter-nbconvert 運(yùn)行）命令將notebook轉(zhuǎn)換為 html 文件，以便通過(guò) Web 瀏覽器查看。就像 papermill一樣，nbconvert 可通過(guò)命令行或使用 Python API 獲得。

自動(dòng)化腳本 

#!/bin/bash  
set -eux  
# activate our virtualenv (this was created using pyenv-virtualenv, yours will be elsewhere)  
source /Users/mcw/.pyenv/versions/3.8.6/envs/pandas/bin/activate  
# get to the script directory if running via cron  
cd $(dirname "${BASH_SOURCE[0]}")  
for S in AAPL MSFT GOOG FB  
do  
        papermill -p symbol $S papermill_example2.ipynb papermill_${S}.ipynb  
        jupyter-nbconvert --no-input --to html papermill_${S}.ipynb  
done 

您可以從 shell 運(yùn)行此命令（在調(diào)整激活虛擬環(huán)境的行之后）。您還可以很容易地安排它在 cron 中定期運(yùn)行。例如，您可以像下面這樣（使用您自己的路徑）在每個(gè)工作日的下午 4 點(diǎn)運(yùn)行此報(bào)告。 

00 16 * * mon-fri /Users/mcw/projects/python_blogposts/tools/run_papermill.sh 

擴(kuò)展示例

只需多一點(diǎn)創(chuàng)意（和 nbconvert 上的軟件配置），您就可以將notebooks 輸出為 PDF 或其他格式，通過(guò)電子郵件發(fā)送，或?qū)⑺鼈兩蟼鞯椒?wù)器，以便每天更新報(bào)告。

請(qǐng)注意，每個(gè)符號(hào)的notebooks 都保存到本地磁盤。如果需要調(diào)試或進(jìn)一步工作，它們可以在 Jupyter 服務(wù)器中打開并輕松重新執(zhí)行。請(qǐng)注意，如果您正在運(yùn)行一個(gè)自動(dòng)化作業(yè)，那么每次運(yùn)行時(shí)都會(huì)更換notebook。理想情況下，在主模板notebook上工作，然后通過(guò)自動(dòng)化為每個(gè)符號(hào)生成新版本。

另一個(gè)技巧是papermill可以讀寫標(biāo)準(zhǔn)輸入和輸出。這意味著如果您有其他工具將notebook文件作為輸入，則不必將文件寫入磁盤。例如，在上面的 shell 腳本中，我們可以防止為每個(gè)符號(hào)寫出每個(gè)單獨(dú)的notebook文件，而是在循環(huán)中執(zhí)行以下操作。 

papermill -p symbol $S papermill_example2.ipynb | jupyter-nbconvert --stdin --no-input --to html --output report_${S}.html 

請(qǐng)注意，如果您這樣做，則需要打開主notebook (papermill_example2.ipynb) 并編輯參數(shù)以調(diào)試問(wèn)題。但是，如果您需要節(jié)省磁盤空間并且不需要單獨(dú)調(diào)試每個(gè)notebook的能力，那么這可能更可取。

總結(jié)

Papermill 是一個(gè)用于參數(shù)化和執(zhí)行 Jupyter notebook的庫(kù)。您可以使用它來(lái)自動(dòng)執(zhí)行您的notebook，其中包含您可以想到的任何參數(shù)集。接著使用 nbconvert 轉(zhuǎn)換notebook，以提供可讀且有用的notebook版本。

notebook自動(dòng)化還有很多事情要做，但是從 Papermill 開始作為執(zhí)行和參數(shù)化notebook的工具是一個(gè)很好的構(gòu)建平臺(tái)。