开发工具CLI数据工程【免费下载链接】papermill Parameterize, execute, and analyze notebooks项目地址https://gitcode.com/gh_mirrors/pa/papermill点击查看免费下载Papermill 是一个用于参数化parameterize与执行executeJupyter Notebook的命令行与 Python 库工具核心能力是把带有默认参数的笔记本变成可批量注入参数并自动执行的数据管道节点。本文以官方文档 docs/index.rst 为主线结合仓库源码系统讲解安装、参数化机制、执行方式、CLI 全量选项、存储后端与扩展接口帮助读者在报表批量生成、工作流串联等场景中直接落地使用。本文对应的官方文档入口为 docs/index.rst其下设安装、工作流、CLI、扩展、故障排查与变更日志等子页面均可从仓库根目录的docs/目录继续深入阅读。Papermill 的核心定位参数化 执行根据 docs/index.rst 的官方定义Papermill 是一套用于参数化并执行 Jupyter Notebook 的工具它允许开发者parameterize参数化notebooks把笔记本中的固定数值、路径、配置抽成参数execute执行notebooks用指定的参数值驱动内核重新运行整份笔记本并产出执行结果。Papermill 对参数化 执行采取了一种**有主见opinionated**的实现方式——这是其在数据管道中大规模使用 Notebook 的经验沉淀见 README.md 与 docs/index.rst。它不要求使用者重构笔记本为函数或模块只需在单元格上打上约定的标签即可把笔记本当作可复用的执行单元。两个典型应用场景官方文档给出了两个极具代表性的落地场景docs/index.rst周期报表批量生成假设你有一份财务报告笔记本希望在月初/月末、年初/年末用不同的数值各跑一遍。借助参数parameters同一份模板笔记本即可被反复执行无需手工改代码或复制多份笔记本。程序化工作流串联当你需要先运行 A 笔记本再根据 A 的结果决定运行 B 或 C 笔记本时可以通过 Python API 或 CLI程序化地执行工作流彻底告别在笔记本之间手工复制粘贴。这两个场景共同构成了 Papermill 的定位把交互式探索的 Notebook 变成可重复、可参数化、可编排的生产级任务。Python 版本支持官方文档明确说明docs/index.rst、README.md当前版本支持 Python 3.10 及以上。当 Python 官方逐步淘汰某个次版本minor version时Papermill 也会随之放弃对该版本的支持。在使用或规划部署环境时请以此为前提确认 Python 版本符合要求。安装与运行环境命令行安装按 docs/installation.rst 的说明使用 pip 安装即可python3 -m pip install papermill如果要启用 S3、Azure、GCS 等远程存储后端可选 IO 依赖可按 README.md 指定依赖包组安装例如pip install papermill[all]all表示一次性安装全部可选存储依赖也可以像s3、azure这样按需单独安装某一组。若希望用 Black 格式化注入的参数代码可以额外安装black作为 extra requires。仓库中的 requirements/ 目录列出了各组可选依赖的具体内容例如 requirements/s3.txt、requirements/azure.txt、requirements/gcs.txt。笔记本内语言绑定In-Notebook language bindings官方文档说明In-Notebook 语言绑定用于为不同编程语言提供使用 Papermill 的辅助工具docs/installation.rst。其中Python 绑定已内置在 papermill 包中无需额外安装步骤也就是说安装完papermill后即可直接在 Python 会话中import papermill as pm使用。核心工作流参数化 → 执行 → 存储根据 docs/usage-workflow.rst使用 Papermill 的通用工作流包含三步参数化parameterizing笔记本、执行executing它、以及存储storing结果。除单本笔记本外Papermill 也支持操作一批笔记本collection of notebooks例如通过list_notebook_files之类的辅助能力批量处理。仓库根目录下的 binder/cli-simple/ 提供了cli_example.ipynb、pm_example.ipynb、simple_input.ipynb等可直接运行的示例笔记本可作为上手参考。第一步参数化笔记本如何标记参数单元要参数化笔记本需要给某个单元格打上parameters标签tag。官方文档在 docs/usage-parameterize.rst 中给出了三种主流界面的操作方式Jupyter Notebook经典界面通过View → Cell Toolbar → Tags激活标签工具栏在单元格右上角的文本框中输入parameters点击Add tag完成添加。JupyterLab 3.0选中要参数化的单元格点击右侧边栏的属性检查器Property Inspector双齿轮图标在 Add Tag 输入框中输入parameters并回车。JupyterLab 2.0 – 2.2.x选中单元格点击左侧边栏的属性检查器双齿轮图标在 Add Tag 输入框中输入parameters并回车。JupyterLab 2.0建议安装jupyterlab-celltags扩展选中单元格点击单元格检查器扳手图标在 Add Tag 输入框输入parameters并回车。若未安装扩展也可以直接在单元格检查器的 Cell Metadata 字段中手动添加tags:[parameters]。参数如何生效injected-parameters 注入机制官方文档对参数机制的定义如下docs/usage-parameterize.rst打上parameters标签的单元格被视作默认值可在执行时被传入的新值覆盖Papermill 会在parameters单元格之后立即插入一个标记为injected-parameters的新单元格injected-parameters单元格只包含被覆盖传入的参数其后的单元格即使也带parameters标签也会被当作普通单元格处理如果笔记本中没有任何parameters标签的单元格则injected-parameters会被插入到笔记本顶部。另外README.md 补充了一个重要细节如果重复用 Papermill 执行同一本笔记本它会复用上一次运行留下的injected-parameters单元格用本次新传入的参数替换旧内容而不是无休止地堆叠注入单元格。从源码 papermill/parameterize.py 可以看到这一机制的实现痕迹第 59 行定义了parameterize_notebook()负责把参数装配到输入笔记本的合适位置第 102-103 行通过find_first_tagged_cell_index(nb, parameters)与find_first_tagged_cell_index(nb, injected-parameters)定位两个关键单元格第 96 行新建单元格并设置newcell.metadata[tags] [injected-parameters]第 114 行在找不到parameters标签时给出告警 Input notebook does not contain a cell with tag parameters第 119 行把最终参数记录进nb.metadata.papermill[parameters]供后续追溯。参数值由 papermill/translators.py 中的translate_parameters()依据内核/语言翻译成对应语言的赋值代码因此注入单元格可以适配不同编程语言的内核。一个容易踩坑的注意点参数间依赖官方文档特别提醒parameters单元格中的相互依赖参数可能不会按直觉工作docs/usage-parameterize.rst。考虑一本note.ipynb包含两个单元格#parameters a 1 twice a * 2print(a , a, and twice , twice)当执行papermill note.ipynb -p a 9时输出是a 9 and twice 2而不是twice 18。原因在于injected-parameters只注入覆盖后的a 9而twice a * 2这一行位于parameters单元格内、在注入前已被当作默认值执行并保留为2。因此凡是在默认单元格内基于其他参数计算的派生值不会随新参数自动重算。第二步执行笔记本官方文档指出带参数执行笔记本有两条途径Python API与命令行接口docs/usage-execute.rst、README.md。方式一Python API核心函数是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的完整调用链是先通过 papermill/parameterize.py 的add_builtin_parameters()与parameterize_path()处理路径模板与内置参数再经parameterize_notebook()注入参数然后交给 papermill/engines.py 的papermill_engines选择执行引擎最后通过 papermill/iorw.py 的write_ipynb()写出结果。其支持的关键参数包括engine_name执行引擎、kernel_name内核名、prepare_only只注入参数不执行、progress_bar进度条、log_output、stdout_file/stderr_file、start_timeout内核启动超时默认 60 秒、report_mode隐藏输入、cwd工作目录等几乎与 CLI 选项一一对应。方式二命令行 CLICLI 的基本形态docs/usage-cli.rstUsage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]其执行流程为读取源笔记本 → 应用参数 → 用指定内核执行 → 保存到目标笔记本。一个经典的本地到 S3 的示例docs/usage-execute.rst$ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1其中-p等价于--parameters一次设置一个参数看起来像布尔值或数字的参数会被自动解释为对应类型。例如alpha 0.6会以浮点数注入而非字符串。参数传递的四种 CLI 方式官方文档docs/usage-execute.rst总结了四种参数注入方式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不同即使值看起来像数字或布尔值也会保持字符串。3.-f / --parameters_file从 YAML 文件读取$ papermill local/input.ipynb s3://bkt/output.ipynb -f parameters.yaml仓库 papermill/tests/parameters/ 下提供了example.yaml、example.json等现成参数文件样例可参考。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 文本适合在无法直接传递多行文本的环境中使用。使用 YAML 时的进阶能力当通过-y、-b或-f传入参数时参数值可以是数组或字典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行为对应CLI 侧的参数解析与翻译逻辑集中在 papermill/cli.py可通过papermill --help查看实时选项列表。多账户凭据AWS_PROFILE官方文档提示docs/usage-execute.rst、README.md如果你使用多个 AWS 账户并已正确配置 AWS 凭据可以在命令行通过设置AWS_PROFILE环境变量指定要使用的账户$ AWS_PROFILEdev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1类似的账户选择模式同样适用于其他类型的远程存储如 Azure、GCS。用单元格描述跟踪执行进度官方文档提供了一项实用的可观测性技巧docs/usage-execute.rst如果想更细致地跟踪执行进度可以在关注单元格的最开头加入如下格式的注释它会被注入到 TQDM 进度条中#papermill_descriptionTQDM_DESCRIPTION例如给第 0 个单元添加#papermill_descriptionFirstCell、给第 1 个单元添加#papermill_descriptionSecondCell执行时进度条会显示Executing FirstCell: 0%...、Executing SecondCell: 25%...这样的可读信息。注意注释内容不能包含空格否则会被忽略。第三步存储笔记本与支持的 Name Handlers执行完成后结果需要写到目标位置。官方文档docs/usage-store.rst说明 Papermill 可以将笔记本存储到多种位置包括AWS S3、Azure Blob数据块、Azure Data Lake数据湖等且其模块化架构允许后续持续注册新的数据存储。在 README.md 中官方列出了执行时输入/输出路径所支持的 name handler路径协议前缀本地文件系统localHTTP / HTTPS 协议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 的-统一注册进PapermillIO实例并通过register_entry_points()第 117-120 行支持第三方扩展注册。其中-表示 stdout/stderr 或管道输入输出如 docs/usage-cli.rst 所述generate input... | papermill | ...process output会把 stdin 的笔记本读入、执行后写到 stdout。检查笔记本参数Inspect在正式执行前开发者往往需要先确认笔记本里有哪些可注入参数。官方文档docs/usage-inspect.rst提供了 Python API 与 CLI 两种检查方式。Python APIinspect_notebook()import papermill as pm pm.inspect_notebook(path/to/input.ipynb)如果路径本身是参数化模板包含{month}之类的占位符可以传入参数字典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)可以看到检查输出会列出每个参数的推断类型与默认值。这一功能由 papermill/inspection.py 的inspect_notebook()第 97 行与_infer_parameters()实现相关测试覆盖见 papermill/tests/test_inspect.py。CLI 全量选项参考papermill/cli.py 对应的官方 CLI 参考文档 docs/usage-cli.rst 列出了全部选项整理如下选项说明--help-notebook显示给定笔记本的参数信息即 Inspect 功能-p, --parameters TEXT...传给参数单元格的参数自动推断类型-r, --parameters_raw TEXT...以原始字符串读取参数-f, --parameters_file TEXT指向含参数的 YAML 文件路径-y, --parameters_yaml TEXT直接使用的 YAML 参数字符串-b, --parameters_base64 TEXTBase64 编码的 YAML 参数字符串--inject-input-path将输入笔记本路径注入为PAPERMILL_INPUT_PATH参数--inject-output-path将输出笔记本路径注入为PAPERMILL_OUTPUT_PATH参数--inject-paths同时注入PAPERMILL_INPUT_PATH/PAPERMILL_OUTPUT_PATH--engine TEXT执行笔记本时使用的执行引擎名称--request-save-on-cell-execute / --no-request-save-on-cell-execute每个单元执行后请求保存笔记本--autosave-cell-every INTEGER长单元执行期间每隔多少秒自动保存0 表示禁用--prepare-only / --prepare-execute只应用参数输出笔记本、不执行-k, --kernel TEXT运行所用的内核名称--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]设置日志级别--start-timeout, --start_timeout INTEGER等待内核启动的秒数--execution-timeout INTEGER每个单元执行超时秒数默认永久等待--report-mode / --no-report-mode是否隐藏输入报表模式--version显示版本号-h, --help显示帮助信息其中--prepare-only与 Python API 的prepare_onlyTrue参数对应先只完成参数化这一步输出一份带注入参数但未执行的笔记本便于检查注入结果是否符合预期。仓库测试 papermill/tests/notebooks/result_no_exec.ipynb 与 papermill/tests/test_execute.py 可用于验证相关行为。扩展 PapermillEntry Points 机制官方文档 docs/extending-overview.rst 说明Papermill 开箱即用地提供了与若干外部服务的接口但如果你希望它做更多事情最便捷的方式是通过 entry pointsPython 打包规范中的入口点扩展它而无需修改项目本身。运行时执行一本笔记本会经历四个步骤读取笔记本文件将文件内容转换为 notebook Python 对象执行笔记本将笔记本写入文件。通过 entry points你可以自行编写工具接管第 1、3、4 步读写与执行引擎例如自定义一个新的存储协议 handler 或一个自定义执行引擎。这与前文 papermill/iorw.py 的register_entry_points()第 117-120 行以及 papermill/engines.py 中papermill_engines的注册机制相互呼应。更深入的扩展指引见 docs/extending-entry-points.rst 与 docs/extending-developing.rst开发规范可参考 DEVELOPMENT_GUIDE.md 与 CONTRIBUTING.md。文档与参考资源导航作为官方文档的总入口docs/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提供了可直接运行的完整示例。总结Papermill 的价值在于把 Jupyter Notebook 从人工交互探索提升为可参数化、可批量执行、可存储到任意后端的数据管道构件。核心要点可归纳为四条标记在默认参数单元格上打parameters标签执行时 Papermill 注入injected-parameters覆盖默认值papermill/parameterize.py执行pm.execute_notebook(...)Python API或papermill input.ipynb output.ipynb -p k vCLI支持-p/-r/-f/-y/-b五种参数注入方式存储local、http(s)://、s3://、adl://、abs://、gs://、hdfs://等协议统一注册于 papermill/iorw.py模块化可扩展编排结合inspect_notebook/--help-notebook探查参数、--prepare-only预检注入、AWS_PROFILE多账户切换即可把多本笔记本串成自动化工作流。如需在多个账户/多个存储后端之间切换或需要自定义执行引擎与存储协议官方文档的扩展章节docs/extending-overview.rst与故障排查docs/troubleshooting.rst页面提供了继续深入的完整路径。赞分享开发工具CLI数据工程【免费下载链接】papermill Parameterize, execute, and analyze notebooks项目地址https://gitcode.com/gh_mirrors/pa/papermill点击查看免费下载相关推荐papermill 完全指南参数化、执行与分析 Jupyter Notebook 的工程化方案papermill 完全指南参数化、执行与分析 Jupyter Notebook 的工程化方案 本篇指南以开源项目 papermill 的 README.md开发工具CLI数据工程Papermill参数化指南如何动态执行Jupyter NotebookPapermill参数化指南如何动态执行Jupyter Notebook 什么是Papermill参数化 Papermill是一个强大的工具它允许用户参数化开发工具CLI数据工程papermill 命令行入门实战用 CLI 参数化并执行 Jupyter Notebookpapermill 命令行入门实战用 CLI 参数化并执行 Jupyter Notebook 本指南基于仓库中的 binder/cli simple 示例讲开发工具CLI数据工程上一篇scikit-learn 1.8 版本发布全解析Array API 扩展、温度校准、ClassicalMDS 与性能重构下一篇G-Helper替代华硕奥创的轻量控制工具单 EXE 管风扇曲线与显卡模式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考