Kedro IPython 扩展完全指南kedro.ipython模块与%load_ext kedro.ipython实战解析【免费下载链接】kedroKedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.项目地址: https://gitcode.com/GitHub_Trending/ke/kedro导读本文聚焦 Kedro 官方 IPython 扩展模块kedro.ipython它是把 Kedro 项目接入 Jupyter Notebook / JupyterLab / IPython / VS Code Notebook / Databricks 等交互式环境的桥梁。通过%load_ext kedro.ipython加载扩展后你可以在 notebook 中直接使用context、catalog、session、pipelines四个全局变量并通过%reload_kedro、%load_node两个行魔法完成项目重载与节点调试。读完本文你将掌握该模块的全部公开函数、参数语义、底层实现原理与可复用的实操命令。模块概览一个为交互式数据科学打造的 IPython 扩展kedro.ipython是 Kedro 官方提供的 IPython 扩展包其核心代码位于 kedro/ipython/init.py模块 docstring 明确描述了它的使命This script creates an IPython extension to load Kedro-related variables in local scope.创建一个 IPython 扩展在本地作用域内加载 Kedro 相关变量。该模块对外暴露 4 个公开函数构成完整的交互式工作流函数类型说明load_ipython_extensionFunction执行%load_ext kedro.ipython时无论是手动执行还是通过kedro ipython或kedro jupyter lab/notebook自动执行的入口函数magic_load_nodeFunction%load_node行魔法的实现将指定节点的数据集加载、import、函数定义与函数调用生成到 notebook 单元格中magic_reload_kedroFunction%reload_kedro行魔法的实现用于重新加载 Kedro 项目变量reload_kedroFunction支撑%reload_kedro行魔法的底层函数除了这 4 个公开函数模块内部还包含一套用于参数解析_normalise_reload_kedro_params等、节点查找_find_node、AST 依赖提取_build_module_symbol_table、_resolve_symbol_dependencies等的私有辅助函数。模块还依赖 IPython 官方 APIget_ipython、needs_local_scope、register_line_magic、magic_arguments、parse_argstring并集成了rich语法高亮当环境中安装了rich时RICH_INSTALLED常量为True代码打印会使用 monokai 主题高亮。扩展加载入口load_ipython_extensionload_ipython_extension(ipython)是 IPython 扩展机制要求的入口函数当执行%load_ext kedro.ipython时被 IPython 自动调用见 源码 L62-L81。其执行流程分为三步注册行魔法通过ipython.register_magic_function注册%reload_kedro与%load_node两个行魔法并输出日志Registered line magic %reload_kedro与Registered line magic %load_node。项目探测调用find_kedro_project(Path.cwd())在当前工作目录向上递归查找 Kedro 项目。若找不到项目会输出警告Kedro extension was registered but couldnt find a Kedro project. Make sure you run %reload_kedro project_root.——这正是从项目外启动交互环境时需要用%reload_kedro project_root手动指定项目路径的原因。自动重载找到项目后自动调用reload_kedro()将 Kedro 变量推入当前命名空间。模块同时提供了kedro别名%load_ext kedro也会触发同样的扩展加载该行为由 tests/ipython/test_ipython.py 中的test_ipython_kedro_extension_alias测试验证。触发方式手动与自动load_ipython_extension有两种典型的触发场景手动在任意 IPython 兼容环境中执行%load_ext kedro.ipython。自动通过 Kedro CLI 启动交互环境。kedro ipython等价于ipython --ext kedro.ipythonkedro jupyter lab与kedro jupyter notebook会创建名为kedro_package_name的自定义内核并在内核启动参数 argv 中追加--ext kedro.ipython见 kedro/framework/cli/jupyter.py 中_create_kernel的 kernel.json 生成逻辑从而保证内核启动即加载扩展。项目重载魔法%reload_kedro%reload_kedro行魔法用于在交互会话中重新加载 Kedro 项目变量典型场景是修改了 Data Catalog 或配置后需要刷新catalog无需重启内核。其实现位于magic_reload_kedro见 源码 L169-L181底层调用reload_kedro函数。完整参数magic_reload_kedro通过magic_arguments与argument装饰器定义了完整的参数协议见 源码 L148-L168参数类型默认值说明pathstrNone项目根目录路径不传则沿用此前设置的项目根目录支持~展开与路径解析-e/--envstrNone配置环境environment与kedro run --env语义一致--paramsdictNone运行时参数覆盖parameters.yml中的同名参数键值用逗号分隔如key1value1,key2value2--conf-sourcestrNone配置文件源目录conf source的自定义路径由于 IPython 的行魔法参数解析基于 shell 分词而--params的值常常包含空格如foobar bazKedro 在解析前会调用_normalise_reload_kedro_params对带引号的参数做归一化处理去引号、按需重新加引号再交由_split_reload_kedro_params复用 CLI 侧的_split_params切分成字典见 源码 L84-L145。tests/ipython/test_ipython.py 中多达十几组参数化用例验证了--params foobar baz、--params foobar baz、--params foobar baz,key2hello world等边界情况的正确解析。使用示例# 从项目外部启动交互环境首次需指定项目根目录 %load_ext kedro.ipython %reload_kedro project_root # 扩展会记住项目路径后续无需重复指定 %reload_kedro # 指定配置环境 %reload_kedro --envprod # 同时指定环境与运行时参数 %reload_kedro --envbase --params model_options.test_size0.3 # 自定义配置文件目录 %reload_kedro --conf-sourcenew_conf若传入未定义的参数如--invalid_argIPython 会抛出UsageError: unrecognized arguments该行为由测试test_line_magic_with_invalid_arguments验证。底层重载逻辑reload_kedro与注入的四个变量reload_kedro(path, env, runtime_params, local_namespace, conf_source)是%reload_kedro的底层实现见 源码 L184-L234它不应当被直接导入调用而是通过行魔法间接执行。其执行链路如下解析项目路径_resolve_project_path依次尝试——显式传入的path→ 本地命名空间中已有context.project_path→ 从当前目录向上查找 Kedro 项目find_kedro_project并维护路径已更新的日志提示。引导项目bootstrap_project(project_path)加载项目元数据。清理缓存模块_remove_cached_modules删除sys.modules中所有以项目包名开头的模块。源码注释解释了为何不用reload()如果新版模块不再定义旧版模块中的某个名字reload()会残留旧定义而删除后重新导入可保证完全干净。配置项目configure_project(metadata.package_name)建立项目级全局状态pipelines、settings、LOGGING。创建 Session 并加载 Context根据settings.SESSION_CLASS是否是KedroSession子类决定runtime_params传入create()还是load_context()——这是因为KedroSession在create()接收runtime_params而KedroServiceSession在run()接收属于新旧 Session 架构过渡期的兼容处理。注入全局变量通过get_ipython().push(...)将context、catalog、session、pipelines四个变量推入交互命名空间并记录日志 Defined global variable context, session, catalog and pipelines。注册插件行魔法遍历load_entry_points(line_magic)把项目插件通过 entry point 暴露的行魔法逐一注册。四个注入变量的含义变量类型说明catalogkedro.io.DataCatalog项目 Data Catalog 实例等价于context.catalog的快捷方式contextKedroContext提供对 Kedro 库组件的访问入口sessionKedroSession/KedroServiceSession编排管道运行的一次会话pipelinesdict[str, Pipeline]项目 pipeline registry 中注册的管道字典值得注意的实现细节pipelines采用惰性加载lazy loadingreload_kedro注入的只是尚未触发实际加载的注册表引用只有首次访问其内容如pipelines[__default__]时才真正调用注册函数加载数据。该行为由测试test_ipython_lazy_load_pipelinetests/ipython/test_ipython.py验证reload_kedro()之后pipelines._content {}触发_load_data()后才会填充实际内容。同时一次 Session 与一次 run 是一一对应的若想执行多次session.run()需要重新执行%reload_kedro获取新 Session。节点加载魔法%load_node%load_node是 Kedro 提供的实验性行魔法源码 L301-L331用于把项目管道中某个节点的完整可执行代码加载到 notebook 单元格中方便单独探索节点的输入、行为与输出或用于调试。使用前提节点必须有名字通过node(func, inputs, outputs, name...)命名未命名时 Kedro 会根据函数名、输入输出自动生成一个名字且名字在管道内必须唯一。节点的输入必须已持久化节点输入需显式声明在 Data Catalogconf/base/catalog.yml中因为生成的单元格依赖catalog.load(dataset_name)获取输入数据。默认 Kedro 数据保存在内存中未注册的数据集无法通过catalog.load访问。支持的环境Jupyter Notebook7.0需安装ipylab1.0.0、notebook7.0.0、JupyterLab、IPython、VS Code Notebook。生成的单元格结构%load_node my-node-name底层由_load_node见 源码 L381-L413负责生成代码输出一个由 14 个单元格组成的代码序列输入准备单元格可选生成catalog.load(...)语句把节点每个输入参数绑定到对应数据集例如first_arg catalog.load(a)。对于*args形式的可变参数Kedro 会使用数据集名作为变量名。单元格以注释# Prepare necessary inputs for debugging与# All debugging inputs must be defined in your project catalog开头。import 单元格扫描节点函数所在源文件提取所有from ... import .../import ...语句。实现上会逐行解析并处理多行 import形如from logging import (INFO, DEBUG, ...)的括号换行写法。函数定义单元格提取节点函数体。这部分的实现相当精细——见 源码 L507-L566 的_prepare_function_body它优先采用AST 依赖提取把模块源码解析成 AST构建顶层符号表函数、类、常量、类型注解赋值解析出节点函数及其引用的同模块辅助函数、类、常量的传递闭包如node_fn - helper_a - helper_b再按源码行号顺序重组为可独立运行的代码块保留装饰器。若 AST 提取失败源文件缺失、语法错误、依赖解析失败、渲染失败等会回退到inspect.getsourcelines()的基础提取方式并记录降级警告日志。函数调用单元格生成形如my_node_function(dataset_a, dataset_b)的调用语句参数名与数据集名一一对应。运行环境感知生成代码的呈现方式取决于_guess_run_environment见 源码 L287-L298对运行环境的探测检测到VSCODE_PID/VSCODE_CWD环境变量 →vscodeDatabricks 环境 →databricks存在kernel属性Jupyter 内核特征→jupyter否则 →ipython。对于ipython、vscode、jupyter环境多个单元格会合并为一个单元格并通过set_next_input注入对于其他环境如 Databricks、Colab或探测失败时则改为打印代码——安装了rich时使用语法高亮输出。使用示例%load_node split_data_node执行后会自动填充新的单元格包含类似如下的代码# Prepare necessary inputs for debugging # All debugging inputs must be defined in your project catalog X_train catalog.load(X_train) y_train catalog.load(y_train) # ... import statements ... # ... function definition ... split_data(X_train, y_train)若指定的名字在任一已注册管道中找不到会抛出ValueErrorNode with name... not found in any pipelines. Remember to specify the node name, not the node function.——注意这里要求的是节点名而非节点函数名见_find_node的实现与对应测试。典型工作流结合%load_node与%debug调试管道kedro.ipython常与 IPython 内置的%debug行魔法配合完成节点级调试完整流程见 docs/integrations-and-plugins/notebooks_and_ipython/kedro_and_notebooks.md运行kedro run失败后从日志中找到出错的节点名。在 notebook 中执行%load_node name-of-failing-node加载该节点。运行生成的单元格在隔离环境中复现节点行为。若仍报错在出错语句前使用%debug或-b指定断点进入交互式调试器也可用%pdb 1让异常发生时自动进入调试模式。测试与质量保障该模块的单元测试集中在 tests/ipython/test_ipython.py覆盖以下关键行为%load_ext kedro.ipython/%load_ext kedro别名加载与魔法注册TestLoadIPythonExtension项目路径解析的四种场景显式路径、沿用context.project_path、自动向上查找、查找失败TestProjectPathResolutionreload_kedro注入的变量内容及其惰性管道加载TestLoadKedroObjects%load_node生成的四个单元格内容、多行 import 处理、*args输入绑定、AST 依赖提取含辅助函数、装饰器保留与降级回退分支TestLoadNodeMagic、TestFormatNodeInputsText--params带空格引号参数的归一化解析test_line_magic_params_with_quoted_spaces。测试夹具位于 tests/ipython/dummy_function_fixtures.py 与 tests/ipython/dummy_multiline_fixtures.py是理解_prepare_function_bodyAST 提取行为的最佳入口。使用注意事项小结必须在 Kedro 项目内或显式指定项目路径扩展加载后若找不到项目%reload_kedro前的变量注入不会发生日志会给出明确提示。--params值含空格时必须加引号且支持单引号/双引号、多个键值对逗号分隔等写法解析器对或空格分隔符两种写法均兼容。一次 Session 对应一次 run需要多次运行管道时请重新执行%reload_kedro。%load_node是实验性功能仅支持 Jupyter Notebook7.0、JupyterLab、IPython 与 VS Code Notebook在其他交互环境中kedro.ipython仍可加载四个全局变量但节点加载会退化为代码打印此时请手动从项目文件中复制相关代码。修改配置或 Catalog 后%reload_kedro会通过清理sys.modules中的项目模块缓存来保证加载的是最新代码无需重启内核。【免费下载链接】kedroKedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.项目地址: https://gitcode.com/GitHub_Trending/ke/kedro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考