Kedro 检测快照模型全解析kedro.inspection.models 六大 Dataclass 深度指南【免费下载链接】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/kedrokedro.inspection.models是 Kedro 检测InspectionAPI 的数据模型层定义了 6 个只读 DataclassProjectSnapshot、ProjectMetadataSnapshot、PipelineSnapshot、NodeSnapshot、NodeSourceSnapshot与DatasetSnapshot。它们共同构成一个项目快照snapshot结构让外部工具、IDE 插件与自动化 Agent 无需执行任何 pipeline 节点即可获知项目元数据、pipeline 拓扑、节点源码位置与 catalog 数据集清单。读完本文你将掌握每个模型的字段语义、默认值与构造规则理解快照如何由get_project_snapshot编排构建并能据此为 Kedro 项目编写自己的只读检视工具。一、快照模型在 Kedro 检测 API 中的位置Kedro 的检测 API 以kedro.inspection.get_project_snapshot为唯一公开入口返回一个完整的ProjectSnapshot。该函数初始化项目、加载配置与 pipeline并在不执行任何 pipeline 节点、不写入数据的前提下组装快照。其返回值正是由kedro.inspection.models中的 6 个 Dataclass 组成的嵌套结构ProjectSnapshot ├── metadata: ProjectMetadataSnapshot # pyproject.toml 中的项目元数据 ├── pipelines: list[PipelineSnapshot] # 每个已注册 pipeline 的快照 │ └── nodes: list[NodeSnapshot] # 拓扑执行顺序下的节点快照 │ └── source: NodeSourceSnapshot? # 节点函数在项目内的源码位置 ├── datasets: dict[str, DatasetSnapshot] # catalog 中每个数据集条目 └── parameters: list[str] # 参数键名列表不含值从源码结构看这一层是只读描述层所有模型均为标准dataclass不含任何业务方法仅DatasetSnapshot提供from_config构造辅助因此快照天然可序列化、可比较适合作为 API 响应体、文件导出格式或缓存对象的载体。二、六大模型的字段语义与默认值所有模型定义集中在 kedro/inspection/models.py均使用from __future__ import annotations与类型标注可直接用于静态类型检查。下面按从叶子到根的顺序逐一展开。2.1 ProjectMetadataSnapshot项目元数据快照ProjectMetadataSnapshot是pyproject.toml中项目元数据的只读快照仅含 3 个必填字段字段类型说明project_namestr人类可读的项目名称package_namestr项目的 Python 包名kedro_versionstr来自项目元数据的 Kedro 包版本kedro_version取的是ProjectMetadata.kedro_init_version项目初始化时的 Kedro 版本而非当前进程加载的 Kedro 运行时版本——这一点在 snapshot.py 的_build_project_metadata_snapshot中体现它把metadata.kedro_init_version映射到快照的kedro_version字段。对应测试 tests/inspection/test_metadata_snapshot.py 验证了三个字段全部由ProjectMetadata填充以及构建过程不进行任何文件 I/O。2.2 DatasetSnapshotcatalog 数据集条目快照DatasetSnapshot描述 catalog 中的单个数据集条目字段如下字段类型默认值说明namestr必填数据集在 catalog 中的名称typestr必填数据集类型字符串如pandas.CSVDatasetfilepathstr \| NoneNone配置中存在的文件路径缺失时为None它提供的from_config(name, config)类方法用于从原始 catalog 配置条目构造快照取config[type]缺失时为空字符串、config.get(filepath)。安全关键点当filepath存在时会先经过_redact_url_credentials脱敏再存入快照。凭据脱敏机制脱敏逻辑位于 kedro/io/core.py 的_redact_url_credentials它按结构解析 URL而非依赖固定的敏感参数名列表把s3://user:passbucket/...这类内嵌凭据替换为s3://redactedbucket/...并同时处理 query string 与 fragment普通本地路径如data/01_raw/companies.csv原样返回。测试 tests/inspection/test_dataset_snapshot.py 覆盖了s3://、postgresql://、gs://三种协议的脱敏结果以及普通路径不受影响的行为。这意味着快照可以安全地输出到日志、UI 或第三方系统而不会泄露存储凭据。工厂模式factory pattern条目的处理需要说明的是_build_dataset_snapshots会先为 catalog 中每一个条目包括以{namespace}.{name}形式存在的工厂模式本身生成快照随后由_resolve_factory_patterns见 helper.py基于所有 pipeline 节点实际引用的输入/输出名称反查出匹配的具体数据集并解析出其真实配置。因此ProjectSnapshot.datasets中既可能包含直接条目也可能包含由工厂模式展开的具体数据集。同时该构建器会跳过以_开头的 YAML 锚点条目、非 dict 条目与None条目测试见 tests/inspection/test_dataset_snapshot.py。2.3 NodeSourceSnapshot节点函数源码位置NodeSourceSnapshot记录 pipeline 节点底层函数的源码位置元数据全部为必填字段字段类型说明filepathstr相对于项目根目录的源码文件路径line_startint函数定义第一行的 1 起始行号line_endint函数定义最后一行的 1 起始行号它让快照使用者能够直接跳转到节点的实现代码是 IDE 集成、代码导航与调试工具的基础。注意filepath是项目相对路径如src/pkg/nodes.py而非绝对路径——这是为了快照可移植、可复现。2.4 NodeSnapshot单个 pipeline 节点快照NodeSnapshot描述 pipeline 中的单个节点字段如下字段类型默认值说明namestr必填节点的全限定名称含命名空间前缀func_namestr必填仅关键字传参kw_onlyTrue节点底层函数的可读名称namespacestr \| NoneNone节点命名空间无命名空间时为Nonetagslist[str][]节点的标签列表已排序inputslist[str][]输入数据集名称的有序列表outputslist[str][]输出数据集名称的有序列表sourceNodeSourceSnapshot \| NoneNone节点函数源码位置无法解析或位于项目外时为None两个值得注意的细节func_name被声明为field(kw_onlyTrue)即必须用NodeSnapshot(namen, func_namef)形式传参。测试 tests/inspection/test_node_pipeline_snapshot.py 明确验证了漏传会抛出TypeError。tags在构建时被排序_node_to_snapshot中使用sorted(node.tags)保证同一节点的快照内容稳定、可哈希比较。func_name取自节点的_func_name内部属性与Node.__str__和 registrydescribe的输出保持一致见 snapshot.py 中的注释说明。源码位置的解析规则_resolve_node_source是快照中最精巧的部分它遵循以下规则返回NodeSourceSnapshot或None对functools.partial、内建函数、lambda一律返回None无源码位置先inspect.unwrap(func)解开装饰器包装再定位真实函数inspect.getsourcefile失败OSError/TypeError或返回None时返回None源码文件必须位于项目根目录内否则返回None防止快照泄露项目外的绝对路径成功后记录项目相对路径与inspect.getsourcelines计算出的行号区间。对应的测试覆盖了 partial、lambda、内建函数、可调用类实例、源码不可用、文件解析失败、装饰器解包、项目内外路径等全部场景见 tests/inspection/test_node_pipeline_snapshot.py。2.5 PipelineSnapshot已注册 pipeline 快照PipelineSnapshot描述一个已注册的 pipeline字段类型默认值说明namestr必填pipeline 注册键如__default__、data_sciencenodeslist[NodeSnapshot]必填按拓扑执行顺序排列的节点快照列表inputslist[str][]pipeline 自由输入已排序outputslist[str][]pipeline 最终输出已排序nodes保持Pipeline.nodes的既有顺序该顺序即拓扑执行顺序测试 tests/inspection/test_node_pipeline_snapshot.py 特意以逆序构造 pipeline 来验证快照仍按执行顺序输出inputs/outputs则通过sorted(pipeline.inputs())稳定排序。2.6 ProjectSnapshot整个项目的根快照ProjectSnapshot是整棵快照树的根字段类型说明metadataProjectMetadataSnapshot项目元数据快照名称、包名、Kedro 版本pipelineslist[PipelineSnapshot]每个已注册 pipeline 的快照按 registry 迭代顺序排列datasetsdict[str, DatasetSnapshot]数据集名称到快照的映射包含由工厂模式解析出的条目parameterslist[str]参数键名字符串的有序列表不存储值parameters只存键名不存值是刻意的安全与体积设计快照用于描述结构而非承载敏感数据。参数键来自配置加载器的parameters配置缺失时为空列表由 helper.py 的_get_parameter_keys排序返回。三、快照如何被构建从配置到模型的调用链整个快照的装配发生在 kedro/inspection/snapshot.py 的_build_project_snapshot编排函数中流程如下解析项目路径project_path经expanduser().resolve()规范化若同时传入metadata且两者指向不同目录则发出UserWarning并以metadata.project_path为准见 kedro/inspection/init.py 的入口文档说明。校验环境名env若提供必须匹配正则^[A-Za-z0-9_-]$否则抛出ValueError。引导项目未提供metadata时调用bootstrap_project已提供则跳过避免重复初始化。创建配置加载器_make_config_loader使用settings.CONFIG_LOADER_CLASS与settings.CONFIG_LOADER_ARGS实例化项目配置的加载器默认conf_source为project_path/settings.CONF_SOURCE见 helper.py。读取 catalog加载catalog配置若KeyError或MissingConfigException则按空 dict 处理catalog 缺失不应导致快照失败。逐层构建依次构建metadata快照、各 pipeline 快照通过dict(kedro.framework.project.pipelines)枚举注册表None条目被跳过、数据集快照然后解析工厂模式、提取参数键名。组装返回ProjectSnapshot。编排函数本身不执行任何节点函数、不写任何数据这也是get_project_snapshot被称为只读的原因。四、实战如何用get_project_snapshot获取并使用快照get_project_snapshot是唯一公开入口签名如下见 kedro/inspection/init.pydef get_project_snapshot( project_path: str | Path | None None, env: str | None None, conf_source: str | None None, metadata: ProjectMetadata | None None, ) - ProjectSnapshot: ...参数约定参数说明project_path项目根目录含pyproject.toml的目录提供metadata时可省略env运行环境覆盖如stagingNone时使用项目默认运行环境conf_source配置目录路径None时默认为project_path/settings.CONF_SOURCEmetadata先前bootstrap_project返回的ProjectMetadata提供时跳过bootstrap_project最少调用——只需项目路径from kedro.inspection import get_project_snapshot snapshot get_project_snapshot(project_path/path/to/project) print(snapshot.metadata.project_name) # 项目名 print(snapshot.metadata.kedro_version) # 项目初始化时的 Kedro 版本 for pipe in snapshot.pipelines: print(pipe.name, [n.name for n in pipe.nodes]) print(sorted(snapshot.datasets)) # 所有数据集名 print(snapshot.parameters) # 参数键名列表长时运行服务中的推荐模式——先引导一次、多次取快照官方 docstring 给出的范例from kedro.framework.startup import bootstrap_project from kedro.inspection import get_project_snapshot # --- 服务启动时 --- metadata bootstrap_project(project_path) # --- 每次请求取快照不再调用 bootstrap_project--- snapshot get_project_snapshot(metadatametadata) snapshot_staging get_project_snapshot(envstaging, metadatametadata)这种启动时引导、请求时取快照的模式避免了同一进程内重复初始化项目带来的开销。相关使用方式在 Kedro 的服务端模块kedro/server与 docs/api/inspection/kedro.inspection.md 中均有对应体现该模块的成员表格同样以get_project_snapshot为唯一公开函数。五、行为边界与可验证性快照模型的行为不是黑盒仓库测试给出了明确的可验证契约元数据构建零 I/Otests/inspection/test_metadata_snapshot.py 用 mock 断言构建过程不调用open。凭据脱敏tests/inspection/test_dataset_snapshot.py 覆盖s3://、postgresql://、gs://协议的user:pass内嵌凭据被替换为redacted普通路径不变。节点源码解析tests/inspection/test_node_pipeline_snapshot.py 验证 lambda/partial/内建/外部函数返回None、装饰器解包后定位真实函数、项目内函数返回相对路径与行号区间。工厂模式展开tests/inspection/test_dataset_snapshot.py 验证工厂模式条目如{namespace}.{name}本身也会被纳入快照集合。编排容错tests/inspection/test_project_snapshot.py 验证空集合场景tests/inspection/test_node_pipeline_snapshot.py 验证注册表中值为None的 pipeline 被跳过。此外ProjectSnapshot的多个集合字段使用field(default_factorylist/dict)保证每个实例持有独立的可变容器避免多个快照实例共享默认列表导致意外串扰。六、小结何时使用这些模型kedro.inspection.models适合以下场景IDE / 编辑器插件利用NodeSnapshot.source实现从节点跳转到源码可视化与文档生成遍历pipelines与nodes绘制 DAG无需实例化 runnerCI / 配置审计核对datasets的type与filepath、parameters键集合是否符合约定服务端 API 响应将ProjectSnapshot直接序列化为 JSON 提供给前端或下游 Agent凭据已自动脱敏。只需记住一条原则快照是描述不是执行——它不运行节点、不写数据也不存储参数值这既是它的能力边界也是它安全、轻量、可复现的保证。【免费下载链接】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），仅供参考