開發(fā)工具CLI數(shù)據(jù)工程【免費下載鏈接】papermill Parameterize, execute, and analyze notebooks項目地址https://gitcode.com/gh_mirrors/pa/papermill點擊查看免費下載Papermill 是一個用于參數(shù)化parameterize與執(zhí)行executeJupyter Notebook的命令行與 Python 庫工具核心能力是把帶有默認參數(shù)的筆記本變成可批量注入?yún)?shù)并自動執(zhí)行的數(shù)據(jù)管道節(jié)點。本文以官方文檔 docs/index.rst 為主線結(jié)合倉庫源碼系統(tǒng)講解安裝、參數(shù)化機制、執(zhí)行方式、CLI 全量選項、存儲后端與擴展接口幫助讀者在報表批量生成、工作流串聯(lián)等場景中直接落地使用。本文對應(yīng)的官方文檔入口為 docs/index.rst其下設(shè)安裝、工作流、CLI、擴展、故障排查與變更日志等子頁面均可從倉庫根目錄的docs/目錄繼續(xù)深入閱讀。Papermill 的核心定位參數(shù)化 執(zhí)行根據(jù) docs/index.rst 的官方定義Papermill 是一套用于參數(shù)化并執(zhí)行 Jupyter Notebook 的工具它允許開發(fā)者parameterize參數(shù)化notebooks把筆記本中的固定數(shù)值、路徑、配置抽成參數(shù)execute執(zhí)行notebooks用指定的參數(shù)值驅(qū)動內(nèi)核重新運行整份筆記本并產(chǎn)出執(zhí)行結(jié)果。Papermill 對參數(shù)化 執(zhí)行采取了一種**有主見opinionated**的實現(xiàn)方式——這是其在數(shù)據(jù)管道中大規(guī)模使用 Notebook 的經(jīng)驗沉淀見 README.md 與 docs/index.rst。它不要求使用者重構(gòu)筆記本為函數(shù)或模塊只需在單元格上打上約定的標簽即可把筆記本當作可復(fù)用的執(zhí)行單元。兩個典型應(yīng)用場景官方文檔給出了兩個極具代表性的落地場景docs/index.rst周期報表批量生成假設(shè)你有一份財務(wù)報告筆記本希望在月初/月末、年初/年末用不同的數(shù)值各跑一遍。借助參數(shù)parameters同一份模板筆記本即可被反復(fù)執(zhí)行無需手工改代碼或復(fù)制多份筆記本。程序化工作流串聯(lián)當你需要先運行 A 筆記本再根據(jù) A 的結(jié)果決定運行 B 或 C 筆記本時可以通過 Python API 或 CLI程序化地執(zhí)行工作流徹底告別在筆記本之間手工復(fù)制粘貼。這兩個場景共同構(gòu)成了 Papermill 的定位把交互式探索的 Notebook 變成可重復(fù)、可參數(shù)化、可編排的生產(chǎn)級任務(wù)。Python 版本支持官方文檔明確說明docs/index.rst、README.md當前版本支持 Python 3.10 及以上。當 Python 官方逐步淘汰某個次版本minor version時Papermill 也會隨之放棄對該版本的支持。在使用或規(guī)劃部署環(huán)境時請以此為前提確認 Python 版本符合要求。安裝與運行環(huán)境命令行安裝按 docs/installation.rst 的說明使用 pip 安裝即可python3 -m pip install papermill如果要啟用 S3、Azure、GCS 等遠程存儲后端可選 IO 依賴可按 README.md 指定依賴包組安裝例如pip install papermill[all]all表示一次性安裝全部可選存儲依賴也可以像s3、azure這樣按需單獨安裝某一組。若希望用 Black 格式化注入的參數(shù)代碼可以額外安裝black作為 extra requires。倉庫中的 requirements/ 目錄列出了各組可選依賴的具體內(nèi)容例如 requirements/s3.txt、requirements/azure.txt、requirements/gcs.txt。筆記本內(nèi)語言綁定In-Notebook language bindings官方文檔說明In-Notebook 語言綁定用于為不同編程語言提供使用 Papermill 的輔助工具docs/installation.rst。其中Python 綁定已內(nèi)置在 papermill 包中無需額外安裝步驟也就是說安裝完papermill后即可直接在 Python 會話中import papermill as pm使用。核心工作流參數(shù)化 → 執(zhí)行 → 存儲根據(jù) docs/usage-workflow.rst使用 Papermill 的通用工作流包含三步參數(shù)化parameterizing筆記本、執(zhí)行executing它、以及存儲storing結(jié)果。除單本筆記本外Papermill 也支持操作一批筆記本collection of notebooks例如通過list_notebook_files之類的輔助能力批量處理。倉庫根目錄下的 binder/cli-simple/ 提供了cli_example.ipynb、pm_example.ipynb、simple_input.ipynb等可直接運行的示例筆記本可作為上手參考。第一步參數(shù)化筆記本如何標記參數(shù)單元要參數(shù)化筆記本需要給某個單元格打上parameters標簽tag。官方文檔在 docs/usage-parameterize.rst 中給出了三種主流界面的操作方式Jupyter Notebook經(jīng)典界面通過View → Cell Toolbar → Tags激活標簽工具欄在單元格右上角的文本框中輸入parameters點擊Add tag完成添加。JupyterLab 3.0選中要參數(shù)化的單元格點擊右側(cè)邊欄的屬性檢查器Property Inspector雙齒輪圖標在 Add Tag 輸入框中輸入parameters并回車。JupyterLab 2.0 – 2.2.x選中單元格點擊左側(cè)邊欄的屬性檢查器雙齒輪圖標在 Add Tag 輸入框中輸入parameters并回車。JupyterLab 2.0建議安裝jupyterlab-celltags擴展選中單元格點擊單元格檢查器扳手圖標在 Add Tag 輸入框輸入parameters并回車。若未安裝擴展也可以直接在單元格檢查器的 Cell Metadata 字段中手動添加tags:[parameters]。參數(shù)如何生效injected-parameters 注入機制官方文檔對參數(shù)機制的定義如下docs/usage-parameterize.rst打上parameters標簽的單元格被視作默認值可在執(zhí)行時被傳入的新值覆蓋Papermill 會在parameters單元格之后立即插入一個標記為injected-parameters的新單元格injected-parameters單元格只包含被覆蓋傳入的參數(shù)其后的單元格即使也帶parameters標簽也會被當作普通單元格處理如果筆記本中沒有任何parameters標簽的單元格則injected-parameters會被插入到筆記本頂部。另外README.md 補充了一個重要細節(jié)如果重復(fù)用 Papermill 執(zhí)行同一本筆記本它會復(fù)用上一次運行留下的injected-parameters單元格用本次新傳入的參數(shù)替換舊內(nèi)容而不是無休止地堆疊注入單元格。從源碼 papermill/parameterize.py 可以看到這一機制的實現(xiàn)痕跡第 59 行定義了parameterize_notebook()負責把參數(shù)裝配到輸入筆記本的合適位置第 102-103 行通過find_first_tagged_cell_index(nb, parameters)與find_first_tagged_cell_index(nb, injected-parameters)定位兩個關(guān)鍵單元格第 96 行新建單元格并設(shè)置newcell.metadata[tags] [injected-parameters]第 114 行在找不到parameters標簽時給出告警 Input notebook does not contain a cell with tag parameters第 119 行把最終參數(shù)記錄進nb.metadata.papermill[parameters]供后續(xù)追溯。參數(shù)值由 papermill/translators.py 中的translate_parameters()依據(jù)內(nèi)核/語言翻譯成對應(yīng)語言的賦值代碼因此注入單元格可以適配不同編程語言的內(nèi)核。一個容易踩坑的注意點參數(shù)間依賴官方文檔特別提醒parameters單元格中的相互依賴參數(shù)可能不會按直覺工作docs/usage-parameterize.rst?？紤]一本note.ipynb包含兩個單元格#parameters a 1 twice a * 2print(a , a, and twice , twice)當執(zhí)行papermill note.ipynb -p a 9時輸出是a 9 and twice 2而不是twice 18。原因在于injected-parameters只注入覆蓋后的a 9而twice a * 2這一行位于parameters單元格內(nèi)、在注入前已被當作默認值執(zhí)行并保留為2。因此凡是在默認單元格內(nèi)基于其他參數(shù)計算的派生值不會隨新參數(shù)自動重算。第二步執(zhí)行筆記本官方文檔指出帶參數(shù)執(zhí)行筆記本有兩條途徑Python API與命令行接口docs/usage-execute.rst、README.md。方式一Python API核心函數(shù)是execute_notebook()簽名為execute_notebook(input, output, parameters)import papermill as pm pm.execute_notebook( path/to/input.ipynb, path/to/output.ipynb, parameters dict(alpha0.6, ratio0.1) )從源碼 papermill/execute.py 看execute_notebook的完整調(diào)用鏈是先通過 papermill/parameterize.py 的add_builtin_parameters()與parameterize_path()處理路徑模板與內(nèi)置參數(shù)再經(jīng)parameterize_notebook()注入?yún)?shù)然后交給 papermill/engines.py 的papermill_engines選擇執(zhí)行引擎最后通過 papermill/iorw.py 的write_ipynb()寫出結(jié)果。其支持的關(guān)鍵參數(shù)包括engine_name執(zhí)行引擎、kernel_name內(nèi)核名、prepare_only只注入?yún)?shù)不執(zhí)行、progress_bar進度條、log_output、stdout_file/stderr_file、start_timeout內(nèi)核啟動超時默認 60 秒、report_mode隱藏輸入、cwd工作目錄等幾乎與 CLI 選項一一對應(yīng)。方式二命令行 CLICLI 的基本形態(tài)docs/usage-cli.rstUsage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]其執(zhí)行流程為讀取源筆記本 → 應(yīng)用參數(shù) → 用指定內(nèi)核執(zhí)行 → 保存到目標筆記本。一個經(jīng)典的本地到 S3 的示例docs/usage-execute.rst$ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1其中-p等價于--parameters一次設(shè)置一個參數(shù)看起來像布爾值或數(shù)字的參數(shù)會被自動解釋為對應(yīng)類型。例如alpha 0.6會以浮點數(shù)注入而非字符串。參數(shù)傳遞的四種 CLI 方式官方文檔docs/usage-execute.rst總結(jié)了四種參數(shù)注入方式1.-p / --parameters類型自動推斷$ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.12.-r / --parameters_raw強制按原始字符串處理$ papermill local/input.ipynb s3://bkt/output.ipynb -r version 1.0與-p不同即使值看起來像數(shù)字或布爾值也會保持字符串。3.-f / --parameters_file從 YAML 文件讀取$ papermill local/input.ipynb s3://bkt/output.ipynb -f parameters.yaml倉庫 papermill/tests/parameters/ 下提供了example.yaml、example.json等現(xiàn)成參數(shù)文件樣例可參考。4.-y / --parameters_yaml與-b / --parameters_base64直接傳入 YAML 字符串$ papermill local/input.ipynb s3://bkt/output.ipynb -y alpha: 0.6 l1_ratio: 0.1$ papermill local/input.ipynb s3://bkt/output.ipynb -b YWxwaGE6IDAuNgpsMV9yYXRpbzogMC4xCg-y直接給出 YAML 文本-b給出Base64 編碼后的 YAML 文本適合在無法直接傳遞多行文本的環(huán)境中使用。使用 YAML 時的進階能力當通過-y、-b或-f傳入?yún)?shù)時參數(shù)值可以是數(shù)組或字典docs/usage-execute.rst$ papermill local/input.ipynb s3://bkt/output.ipynb -y x: - 0.0 - 1.0 - 2.0 - 3.0 linear_function: slope: 3.0 intercept: 1.0這里x是列表、linear_function是字典均會被正確注入。從源碼看papermill/parameterize.py 第 81-83 行支持當parameters是字符串時按 YAML 文件解析與-f行為對應(yīng)CLI 側(cè)的參數(shù)解析與翻譯邏輯集中在 papermill/cli.py可通過papermill --help查看實時選項列表。多賬戶憑據(jù)AWS_PROFILE官方文檔提示docs/usage-execute.rst、README.md如果你使用多個 AWS 賬戶并已正確配置 AWS 憑據(jù)可以在命令行通過設(shè)置AWS_PROFILE環(huán)境變量指定要使用的賬戶$ AWS_PROFILEdev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1類似的賬戶選擇模式同樣適用于其他類型的遠程存儲如 Azure、GCS。用單元格描述跟蹤執(zhí)行進度官方文檔提供了一項實用的可觀測性技巧docs/usage-execute.rst如果想更細致地跟蹤執(zhí)行進度可以在關(guān)注單元格的最開頭加入如下格式的注釋它會被注入到 TQDM 進度條中#papermill_descriptionTQDM_DESCRIPTION例如給第 0 個單元添加#papermill_descriptionFirstCell、給第 1 個單元添加#papermill_descriptionSecondCell執(zhí)行時進度條會顯示Executing FirstCell: 0%...、Executing SecondCell: 25%...這樣的可讀信息。注意注釋內(nèi)容不能包含空格否則會被忽略。第三步存儲筆記本與支持的 Name Handlers執(zhí)行完成后結(jié)果需要寫到目標位置。官方文檔docs/usage-store.rst說明 Papermill 可以將筆記本存儲到多種位置包括AWS S3、Azure Blob數(shù)據(jù)塊、Azure Data Lake數(shù)據(jù)湖等且其模塊化架構(gòu)允許后續(xù)持續(xù)注冊新的數(shù)據(jù)存儲。在 README.md 中官方列出了執(zhí)行時輸入/輸出路徑所支持的 name handler路徑協(xié)議前綴本地文件系統(tǒng)localHTTP / HTTPS 協(xié)議http://、https://AWS S3s3://Azure DataLake Store / Azure Blob Storeadl://、abs://Google Cloud Storagegs://源碼 papermill/iorw.py 印證了這一注冊機制第 459-471 行在模塊加載時把local、s3://、adl://、abs://、http://、https://、gs://、hdfs://以及 stdin/stdout 的-統(tǒng)一注冊進PapermillIO實例并通過register_entry_points()第 117-120 行支持第三方擴展注冊。其中-表示 stdout/stderr 或管道輸入輸出如 docs/usage-cli.rst 所述generate input... | papermill | ...process output會把 stdin 的筆記本讀入、執(zhí)行后寫到 stdout。檢查筆記本參數(shù)Inspect在正式執(zhí)行前開發(fā)者往往需要先確認筆記本里有哪些可注入?yún)?shù)。官方文檔docs/usage-inspect.rst提供了 Python API 與 CLI 兩種檢查方式。Python APIinspect_notebook()import papermill as pm pm.inspect_notebook(path/to/input.ipynb)如果路徑本身是參數(shù)化模板包含{month}之類的占位符可以傳入?yún)?shù)字典pm.inspect_notebook(path/to/input_{month}.ipynb, parameters{month: Feb})CLIpapermill --help-notebookpapermill --help-notebook ./papermill/tests/notebooks/complex_parameters.ipynb輸出示例可對照倉庫測試筆記本 papermill/tests/notebooks/complex_parameters.ipynbUsage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH] Parameters inferred for notebook ./papermill/tests/notebooks/complex_parameters.ipynb: msg: Unknown type (default None) a: float (default 2.25) Variable a b: List[str] (default [Hello,World]) Nice list c: NoneType (default None)可以看到檢查輸出會列出每個參數(shù)的推斷類型與默認值。這一功能由 papermill/inspection.py 的inspect_notebook()第 97 行與_infer_parameters()實現(xiàn)相關(guān)測試覆蓋見 papermill/tests/test_inspect.py。CLI 全量選項參考papermill/cli.py 對應(yīng)的官方 CLI 參考文檔 docs/usage-cli.rst 列出了全部選項整理如下選項說明--help-notebook顯示給定筆記本的參數(shù)信息即 Inspect 功能-p, --parameters TEXT...傳給參數(shù)單元格的參數(shù)自動推斷類型-r, --parameters_raw TEXT...以原始字符串讀取參數(shù)-f, --parameters_file TEXT指向含參數(shù)的 YAML 文件路徑-y, --parameters_yaml TEXT直接使用的 YAML 參數(shù)字符串-b, --parameters_base64 TEXTBase64 編碼的 YAML 參數(shù)字符串--inject-input-path將輸入筆記本路徑注入為PAPERMILL_INPUT_PATH參數(shù)--inject-output-path將輸出筆記本路徑注入為PAPERMILL_OUTPUT_PATH參數(shù)--inject-paths同時注入PAPERMILL_INPUT_PATH/PAPERMILL_OUTPUT_PATH--engine TEXT執(zhí)行筆記本時使用的執(zhí)行引擎名稱--request-save-on-cell-execute / --no-request-save-on-cell-execute每個單元執(zhí)行后請求保存筆記本--autosave-cell-every INTEGER長單元執(zhí)行期間每隔多少秒自動保存0 表示禁用--prepare-only / --prepare-execute只應(yīng)用參數(shù)輸出筆記本、不執(zhí)行-k, --kernel TEXT運行所用的內(nèi)核名稱--cwd TEXT運行筆記本的工作目錄--progress-bar / --no-progress-bar是否顯示進度條--log-output / --no-log-output是否把筆記本輸出寫入配置好的 logger--stdout-file FILENAME將筆記本 stdout 輸出寫入的文件--stderr-file FILENAME將筆記本 stderr 輸出寫入的文件--log-level [NOTSET\|DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL]設(shè)置日志級別--start-timeout, --start_timeout INTEGER等待內(nèi)核啟動的秒數(shù)--execution-timeout INTEGER每個單元執(zhí)行超時秒數(shù)默認永久等待--report-mode / --no-report-mode是否隱藏輸入報表模式--version顯示版本號-h, --help顯示幫助信息其中--prepare-only與 Python API 的prepare_onlyTrue參數(shù)對應(yīng)先只完成參數(shù)化這一步輸出一份帶注入?yún)?shù)但未執(zhí)行的筆記本便于檢查注入結(jié)果是否符合預(yù)期。倉庫測試 papermill/tests/notebooks/result_no_exec.ipynb 與 papermill/tests/test_execute.py 可用于驗證相關(guān)行為。擴展 PapermillEntry Points 機制官方文檔 docs/extending-overview.rst 說明Papermill 開箱即用地提供了與若干外部服務(wù)的接口但如果你希望它做更多事情最便捷的方式是通過 entry pointsPython 打包規(guī)范中的入口點擴展它而無需修改項目本身。運行時執(zhí)行一本筆記本會經(jīng)歷四個步驟讀取筆記本文件將文件內(nèi)容轉(zhuǎn)換為 notebook Python 對象執(zhí)行筆記本將筆記本寫入文件。通過 entry points你可以自行編寫工具接管第 1、3、4 步讀寫與執(zhí)行引擎例如自定義一個新的存儲協(xié)議 handler 或一個自定義執(zhí)行引擎。這與前文 papermill/iorw.py 的register_entry_points()第 117-120 行以及 papermill/engines.py 中papermill_engines的注冊機制相互呼應(yīng)。更深入的擴展指引見 docs/extending-entry-points.rst 與 docs/extending-developing.rst開發(fā)規(guī)范可參考 DEVELOPMENT_GUIDE.md 與 CONTRIBUTING.md。文檔與參考資源導航作為官方文檔的總?cè)肟赿ocs/index.rst 還組織了完整的閱讀路線使用指南docs/installation.rst安裝、docs/usage-workflow.rst工作流總覽、docs/usage-cli.rstCLI 全量選項、docs/extending-overview.rst擴展、docs/troubleshooting.rst故障排查、docs/changelog.md變更日志API 參考docs/reference/index.rst其下細分了 papermill-workflow、papermill-cli、papermill-io、papermill-storage、papermill-translators、papermill-utilities 等模塊參考交互示例binder/cli-simple/ 下的cli_example.ipynb、pm_example.ipynb、simple_input.ipynb、simple_output.ipynb提供了可直接運行的完整示例?？偨Y(jié)Papermill 的價值在于把 Jupyter Notebook 從人工交互探索提升為可參數(shù)化、可批量執(zhí)行、可存儲到任意后端的數(shù)據(jù)管道構(gòu)件。核心要點可歸納為四條標記在默認參數(shù)單元格上打parameters標簽執(zhí)行時 Papermill 注入injected-parameters覆蓋默認值papermill/parameterize.py執(zhí)行pm.execute_notebook(...)Python API或papermill input.ipynb output.ipynb -p k vCLI支持-p/-r/-f/-y/-b五種參數(shù)注入方式存儲local、http(s)://、s3://、adl://、abs://、gs://、hdfs://等協(xié)議統(tǒng)一注冊于 papermill/iorw.py模塊化可擴展編排結(jié)合inspect_notebook/--help-notebook探查參數(shù)、--prepare-only預(yù)檢注入、AWS_PROFILE多賬戶切換即可把多本筆記本串成自動化工作流。如需在多個賬戶/多個存儲后端之間切換或需要自定義執(zhí)行引擎與存儲協(xié)議官方文檔的擴展章節(jié)docs/extending-overview.rst與故障排查docs/troubleshooting.rst頁面提供了繼續(xù)深入的完整路徑。贊分享開發(fā)工具CLI數(shù)據(jù)工程【免費下載鏈接】papermill Parameterize, execute, and analyze notebooks項目地址https://gitcode.com/gh_mirrors/pa/papermill點擊查看免費下載相關(guān)推薦papermill 完全指南參數(shù)化、執(zhí)行與分析 Jupyter Notebook 的工程化方案papermill 完全指南參數(shù)化、執(zhí)行與分析 Jupyter Notebook 的工程化方案 本篇指南以開源項目 papermill 的 README.md開發(fā)工具CLI數(shù)據(jù)工程Papermill參數(shù)化指南如何動態(tài)執(zhí)行Jupyter NotebookPapermill參數(shù)化指南如何動態(tài)執(zhí)行Jupyter Notebook 什么是Papermill參數(shù)化 Papermill是一個強大的工具它允許用戶參數(shù)化開發(fā)工具CLI數(shù)據(jù)工程papermill 命令行入門實戰(zhàn)用 CLI 參數(shù)化并執(zhí)行 Jupyter Notebookpapermill 命令行入門實戰(zhàn)用 CLI 參數(shù)化并執(zhí)行 Jupyter Notebook 本指南基于倉庫中的 binder/cli simple 示例講開發(fā)工具CLI數(shù)據(jù)工程上一篇scikit-learn 1.8 版本發(fā)布全解析Array API 擴展、溫度校準、ClassicalMDS 與性能重構(gòu)下一篇G-Helper替代華碩奧創(chuàng)的輕量控制工具單 EXE 管風扇曲線與顯卡模式創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考