Papermill 存储后端实战：在 AWS S3、Azure Blob/Data Lake 与更多远程存储之间读写 Notebook

开发工具CLI数据工程【免费下载链接】papermill Parameterize, execute, and analyze notebooks项目地址https://gitcode.com/gh_mirrors/pa/papermill点击查看免费下载本篇技术指南围绕 Papermill 的存储Store能力展开Papermill 不仅能读写本地 Notebook还能把 Notebook 直接存取到 AWS S3、Azure Blob Storage、Azure Data Lake 等远程对象存储中并通过模块化 I/O 架构按需扩展新后端。读完本文你将掌握各类存储路径的 URI 规范、对应依赖与认证方式、CLI/Python API 的读写用法以及如何注册自定义存储 Handler。存储层在 Papermill 工作流中的位置Papermill 的典型工作流是**参数化parameterize→ 执行execute→ 存储store**三件套见 docs/usage-workflow.rst。存储环节决定了输入 Notebook 从哪里读、执行结果往哪里写输入路径可以来自本地磁盘也可以来自s3://、abs://、adl://、gs://、hdfs://等远程位置输出路径同样支持这些位置例如本地输入、S3 输出或S3 输入、S3 输出均可官方文档 docs/usage-store.rst 明确指出Papermill 可以将 Notebook 存储到多种位置包括 AWS S3、Azure data blobs 与 Azure data lakes且模块化架构允许在后续持续新增数据存储后端。这一设计让批量执行结果直接归档到云上成为可能也是 Papermill 被广泛用于数据管线与调度系统的关键原因。核心机制PapermillIO 与 Handler 注册表所有存储后端都统一挂在papermill_ioPapermillIO实例下。该实例在 papermill/iorw.py 中被初始化并注册了一批内置 Handler见 papermill/iorw.py#L459-L472papermill_io PapermillIO() papermill_io.register(local, LocalHandler()) papermill_io.register(s3://, S3Handler) papermill_io.register(adl://, ADLHandler()) papermill_io.register(abs://, ABSHandler()) papermill_io.register(http://, HttpHandler) papermill_io.register(https://, HttpHandler) papermill_io.register(gs://, GCSHandler()) papermill_io.register(hdfs://, HDFSHandler()) papermill_io.register(http://github.com/, GithubHandler()) papermill_io.register(https://github.com/, GithubHandler()) papermill_io.register(-, StreamHandler()) papermill_io.register_entry_points()其中几个要点按 scheme 前缀匹配get_handler(path)会遍历注册表找到第一个path.startswith(scheme)成立的 Handler见 papermill/iorw.py#L122-L164找不到匹配时回退到localHandler否则抛出PapermillException。注册表采用 LIFO 顺序register将新 Handler 插到列表头部见 papermill/iorw.py#L113-L115后注册的同前缀 Handler 优先命中。统一接口每个 Handler 至少实现read(path)、write(buf, path)、listdir(path)、pretty_path(path)四个方法部分只读后端如 GitHub 会针对write/listdir抛出PapermillException。entry points 扩展register_entry_points()会加载所有注册在papermill.ioentry point 组下的第三方 Handler见 papermill/iorw.py#L117-L120这正是模块化架构允许新增数据存储的落地方式。特殊输入类型路径为None时返回NoIOHandler不写任何输出路径为nbformat.NotebookNode对象时使用NotebookNodeHandler见 papermill/iorw.py#L141-L145。依赖缺失时相关 Handler 会被替换为missing_dependency_generator生成的占位实现见 papermill/iorw.py#L24-L57调用时会给出明确提示而非静默失败。本地存储LocalHandler 与默认回退localHandler见 papermill/iorw.py#L186-L224是未匹配任何 scheme 时的默认后端其行为要点read以 UTF-8 打开文件若打开失败会尝试把路径本身当作 JSON 字符串即 Notebook 内容直接内联传入的场景write要求输出目录已存在否则抛出FileNotFoundError: output folder ... doesnt exist.这一点在跨目录输出时需注意通过cwd()支持在读写期间临时切换工作目录配合local_file_io_cwd上下文管理器使用见 papermill/iorw.py#L531-L546。AWS S3s3://后端S3 是文档明确列出的三大目标存储之一对应S3Handlerpapermill/iorw.py#L227-L242底层实现为 papermill/s3.py 中的S3类。路径格式与依赖s3://bucket/key依赖boto3见 requirements/s3.txt。安装后即自动可用pip install papermill[s3]底层实现要点papermill/s3.pyS3.__init__使用boto3.session.Session惰性创建 client/resource 并缓存为类级单例线程安全若设置了环境变量BOTO3_ENDPOINT_URL会作为endpoint_url传入session.resource(s3)见 papermill/s3.py#L141-L155便于对接 S3 兼容服务如 MinIOread逐行迭代文件内容按\n切分cat支持流式读取、断点续读与.gz自动解压见 papermill/s3.py#L259-L355cp_string将字符串内容以put方式写入目标 key上传策略默认bucket-owner-full-control见 papermill/s3.py#L242-L249list/listdir通过list_objects_v2分页器实现listdir额外以/作为 delimiter 模拟ls语义见 papermill/s3.py#L374-L421Bucket、Key、Prefix三个类对 S3 对象模型做了一层轻封装Key.__str__会还原成s3://bucket/key形式见 papermill/s3.py#L16-L116。CLI 中使用 S3 作为输出沿用 docs/usage-execute.rst 中的经典示例将本地 Notebook 执行并输出到 S3$ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1-p/--parameters传参数对值会被自动解析为布尔、整数、浮点或字符串解析逻辑见 papermill/cli.py#L260-L289若希望值保持原始字符串改用-r/--parameters_raw需要 S3 输入 S3 输出时两个路径都写成s3://...即可例如papermill s3://in/input.ipynb s3://out/output.ipynb -f parameters.yaml。多账号认证访问 S3 时遵循 boto3 的标准凭证链。若使用多个 AWS 账号可在命令行通过AWS_PROFILE环境变量指定账号$ AWS_PROFILEdev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1其他远程存储账号Azure 等也可采用类似的环境变量方式切换凭证。Azure 对象存储abs://与adl://后端文档提到的 Azure data blobs 与 Azure data lakes 分别由ABSHandler与ADLHandler承载papermill/iorw.py#L245-L288底层实现见 papermill/abs.py 与 papermill/adl.py。Azure Blob Storageabs://路径格式见 papermill/abs.py#L30-L46 中的 URL 拆分逻辑abs://account.blob.core.windows.net/container/blob?sas_token要点凭证支持两种方式URL 中携带 SAS token或使用azure.identity.EnvironmentCredential()读取环境凭证见 papermill/abs.py#L22-L28依赖azure-storage-blob 12.1.0与azure-identity 1.3.1见 requirements/azure.txtpip install papermill[azure]read将 blob 下载到内存流后按行解码为 UTF-8write调用upload_blob(databuf, overwriteTrue)覆盖写入listdir通过list_blobs(prefix)列出容器内对象见 papermill/abs.py#L48-L70。CLI 示例$ papermill local/input.ipynb abs://myaccount.blob.core.windows.net/mycontainer/output.ipynb?sas_token -p alpha 0.6Azure Data Lakeadl://路径格式见 papermill/adl.py#L23-L29adl://store_name.azuredatalakestore.net/path要点认证通过azure.datalake.store.lib.auth()完成token 在ADL实例内缓存见 papermill/adl.py#L31-L34依赖azure-datalake-store 0.0.30, 2.0.0见 requirements/azure.txtread/write/listdir均基于core.AzureDLFileSystem适配器listdir返回的路径会还原为adl://完整形式见 papermill/adl.py#L39-L61。CLI 示例$ papermill local/input.ipynb adl://mystore.azuredatalakestore.net/output.ipynb -p alpha 0.6更多内置后端GCS、HDFS、GitHub、HTTP 与标准流除文档重点列出的三类外papermill_io还内置了以下后端均有对应 Handler 与测试SchemeHandler底层依赖说明gs://GCSHandlergcsfs 0.2.0requirements/gcs.txtGoogle Cloud Storage写入对限流异常做指数退避重试默认最多 3 次、初始延迟 1 秒、最大 4 秒见 papermill/iorw.py#L291-L337hdfs://HDFSHandlerpyarrow 2.0requirements/hdfs.txt通过HadoopFileSystem(hostdefault)读写listdir 使用FileSelector见 papermill/iorw.py#L340-L361http(s)://github.com/...GithubHandlerPyGithub 1.55requirements/github.txt只读从org/repo/blob/ref/path结构解析并读取仓库文件内容支持GITHUB_ACCESS_TOKEN环境变量见 papermill/iorw.py#L364-L394http:///https://HttpHandlerrequests 2.21.0通用 HTTP 读写GET 读取、PUT 写回 JSON见 papermill/iorw.py#L167-L183-StreamHandler内置从 stdin 读、向 stdout 写见 papermill/iorw.py#L397-L415支持管道式调用... | papermill - - | ...GCS 与 S3 均有对应的测试夹具 Notebookpapermill/tests/notebooks/gcs/gcs_in/gcs-simple_notebook.ipynb、papermill/tests/notebooks/s3/s3_in/s3-simple_notebook.ipynb可在编写用例时参考。Python API 中的远程存储execute_notebook对路径的处理完全透明——输入输出路径都走papermill_io因此 Python API 与 CLI 一样支持任意已注册的存储后端import papermill as pm pm.execute_notebook( s3://my-bucket/input.ipynb, # 从 S3 读取 s3://my-bucket/output.ipynb, # 写回 S3 parametersdict(alpha0.6, ratio0.1), )同理读入端也可以是abs://、adl://、gs://等输出路径传None时不落盘对应NoIOHandler见 papermill/iorw.py#L434-L447。此外papermill_io还暴露了若干便捷函数供上层调用read_yaml_file读取 YAML 参数文件、write_ipynb序列化 Notebook 写盘、load_notebook_node读取并补齐 papermill 元数据、list_notebook_files列出目录下所有.ipynb全部定义在 papermill/iorw.py。自定义存储后端模块化扩展新增存储类型的标准做法是复用papermill.ioentry point 机制实现一个 Handler 类提供read/write/listdir/pretty_path四个方法读写能力可按后端取舍不支持的方法抛PapermillException在项目打包配置中声明 entry point组名为papermill.io名字为该后端的 URI scheme如mycloud://安装该包后papermill_io.register_entry_points()会自动加载它见 papermill/iorw.py#L117-L120随后即可直接使用mycloud://...路径。该机制的注册与匹配行为有测试覆盖test_entrypoint_register验证了 entry point 的加载test_register_ordering验证了 LIFO 匹配顺序见 papermill/tests/test_iorw.py。S3 后端的Bucket/Key/Prefix与S3.list等接口也有专门的单测papermill/tests/test_s3.py并配套test_adl.py、test_abs.py、test_gcs.py等针对各云后端的测试文件可作为实现自定义 Handler 的行为参考。依赖速查各存储后端对应的可选依赖见 requirements/ 目录S3boto3requirements/s3.txtAzure Blob Data Lakeazure-datalake-store 0.0.30,2.0.0、azure-storage-blob 12.1.0、azure-identity 1.3.1、requests 2.21.0requirements/azure.txtGCSgcsfs 0.2.0requirements/gcs.txtHDFSpyarrow 2.0requirements/hdfs.txtGitHubPyGithub 1.55requirements/github.txt未安装对应依赖时相关 Handler 会被替换为缺失依赖占位实现调用时给出提示不影响其他后端使用。小结Papermill 的存储层是按 URI scheme 分发、Handler 统一接口、entry point 可扩展的模块化设计文档明确支持的 AWS S3、Azure Blob、Azure Data Lake 开箱即用GCS、HDFS、GitHub、HTTP 与标准流作为内置补充本地路径始终是默认回退。理解 papermill/iorw.py 中的注册表与各后端路径规范后即可在 CLI 与 Python API 中自由组合输入输出位置也可以按同一套接口快速接入新的存储系统。更多底层 API 细节可查阅 docs/reference/papermill-storage.rst 与 papermill-storage 相关模块。赞分享开发工具CLI数据工程【免费下载链接】papermill Parameterize, execute, and analyze notebooks项目地址https://gitcode.com/gh_mirrors/pa/papermill点击查看免费下载相关推荐Papermill 存储模块深度指南从 Azure Blob、Data Lake 到 AWS S3 的 notebook 读写架构Papermill 存储模块深度指南从 Azure Blob、Data Lake 到 AWS S3 的 notebook 读写架构 Papermill 的存储开发工具CLI数据工程Cppcheck跨平台编译指南Windows、Linux与macOS环境配置Cppcheck跨平台编译指南Windows、Linux与macOS环境配置 引言 你是否曾因跨平台编译C/C静态分析工具Cppcheck而头疼本文将系开发工具CLI数据工程Polars 云存储读写完全指南统一使用 AWS S3、Azure Blob 与 Google Cloud StoragePolars 云存储读写完全指南统一使用 AWS S3、Azure Blob 与 Google Cloud Storage Polars 提供了一套面向 AW数据分析大数据上一篇JupyterHub认证系统全解析PAM、OAuth与LDAP方案对比下一篇从0到1用mlx-optiq量化自己的Gemma模型mlx-community/gemma-4-31B-it-OptiQ-4bit制作全流程 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考