Kedro 项目模板 README 全解从安装依赖、运行 Pipeline 到测试、Notebook 与打包【免费下载链接】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 开源仓库中的项目模板 READMEfeatures/test_starter/{{ cookiecutter.repo_name }}/README.md 及其生产版 kedro/templates/project/{{ cookiecutter.repo_name }}/README.md展开这份 README 是kedro new生成的新项目自带的「项目使用说明书」。文章会逐一拆解其中关于依赖安装、kedro run、pytest测试、Notebook/IPython 交互以及项目打包的每一项指引并结合仓库中的 cookiecutter 配置、pyproject.toml、requirements.txt、conf/目录和tests/test_run.py等真实文件说明每一项指引在生成项目里对应的落地文件与底层实现。读完本文你将能完整掌握一个 Kedro 项目从生成到运行、测试、调试和打包的全流程并理解模板 README 中每条规则背后的工程考量。模板 README 在 Kedro 项目中的角色一份写给「项目使用者」的说明书当用户执行kedro new创建新项目时Kedro 会通过 cookiecutter 模板生成一个完整的项目骨架而这个骨架里一定包含一份README.md。它面向的不是 Kedro 框架开发者而是每一个使用该模板创建项目的团队用于回答三个最基础的问题这个项目是怎么来的生成时用的 Kedro 版本日常开发要遵守哪些规则.gitignore、数据与凭据管理项目如何安装、运行、测试、用 Notebook 调试、打包发布在仓库中这份模板 README 有两个互为镜像的版本生产模板kedro/templates/project/{{ cookiecutter.repo_name }}/README.md由kedro new直接使用测试用精简版features/test_starter/{{ cookiecutter.repo_name }}/README.md用于端到端特性测试对应 features/starter.feature。两者内容几乎一致均由 cookiecutter 变量如{{ cookiecutter.project_name }}、{{ cookiecutter.kedro_version }}在生成时渲染因此最终落盘到每个项目里的 README 都带有该项目自己的名称与 Kedro 版本号。对应的 cookiecutter 变量定义见 features/test_starter/cookiecutter.json 与 kedro/templates/project/cookiecutter.json。README 开头项目身份信息模板 README 第一行是项目标题# {{ cookiecutter.project_name }}并由{{ cookiecutter.kedro_version }}声明生成项目所用的 Kedro 版本。这两个变量的默认值与派生规则定义在 kedro/templates/project/cookiecutter.json 中{ project_name: New Kedro Project, repo_name: {{ cookiecutter.project_name.strip().replace( , -).replace(_, -).lower() }}, python_package: {{ cookiecutter.project_name.strip().replace( , _).replace(-, _).lower() }}, kedro_version: {{ cookiecutter.kedro_version }}, tools: none, example_pipeline: no }从这些派生规则可以看出repo_name仓库目录名会把空格和下划线统一转成连字符并小写而python_packagePython 包名则把空格和连字符统一转成下划线并小写——这正是 README 中所有命令如kedro run能够在新项目里直接工作的前提。example_pipeline默认为no说明新项目默认不附带示例流水线但 README 中仍保留了示例数据集说明见下文「Data Catalog 与示例数据」。Overview先看官方文档再动手README 的 Overview 部分建议用户查看 Kedro 官方文档以了解如何上手。在仓库内与这份 README 配套、可深入阅读的项目级资料包括项目全局说明README.md 与 RELEASE.md入门概念docs/getting-started/kedro_concepts.md项目结构总览docs/getting-started/architecture_overview.md命令速查docs/getting-started/commands_reference.md。Rules and guidelines模板内置的工程规范模板 README 用「Rules and guidelines」一节给出了四条硬性规则这些规则直接决定生成项目是否可复现、可维护不要删除kedro new生成的.gitignore中的任何一行——它保证了数据、日志、会话记录等运行产物不会被误提交进版本库遵循数据工程分层约定data engineering convention——即data/01_raw到data/08_reporting的分层目录保证结果可复现不要把数据提交到仓库——数据应当通过 Data Catalog 按路径读取而不是进 Git不要把凭据或本地配置提交到仓库所有凭据与本地配置放在conf/local/——这是 Kedro 配置隔离模型的核心。分层数据目录在模板中的落地模板项目的数据目录骨架见 kedro/templates/project/{{ cookiecutter.repo_name }}/data以及测试版 features/test_starter/{{ cookiecutter.repo_name }}/data包含01_raw、02_intermediate、03_primary、04_feature、05_model_input、06_models、07_model_output、08_reporting共八个层级。README 中「确保结果可复现」的建议正是要求各节点读写遵循这套约定例如原始数据只放01_raw、模型文件放06_models、预测输出放07_model_output。conf/base 与 conf/local 的职责分离规则 4 提到的conf/local/来自模板的配置目录结构kedro/templates/project/{{ cookiecutter.repo_name }}/confconf/base/存放跨成员共享的、非敏感的配置如 catalog.yml 和 parameters.ymlconf/local/存放用户私有或受保护的配置如安全密钥。模板在 conf/README.md 中进一步强调Thelocalfolder should be used for configuration that is either user-specific (e.g. IDE configuration) or protected (e.g. security keys). Please do not check in any local configuration to version control. WARNING: Please do not put access credentials in the base configuration folder.也就是说base是团队共享、非敏感的配置层local是个人、敏感的配置层且local 配置不得提交版本库。这一「base 环境 local 运行环境」的加载机制最终由项目 settings.py 中的CONFIG_LOADER_ARGS配置CONFIG_LOADER_ARGS { base_env: base, default_run_env: local, # config_patterns: { # spark : [spark*/], # parameters: [parameters*, parameters*/**, **/parameters*], # } }即默认从base环境加载共享配置、从local环境加载运行配置两者合并后生效——这也是 README 第 4 条规则能够落地的机制基础。相关实现位于 kedro/config/omegaconf_config.py。How to install dependencies依赖安装requirements.txt 是依赖的唯一入口README 明确所有依赖声明在requirements.txt中安装命令为pip install -r requirements.txt测试版模板的 requirements.txt 内容如下ipython8.10 jupyterlab3.0 notebook kedro~{{ cookiecutter.kedro_version }} kedro-datasets[pandas-csvdataset]可以看到新项目默认依赖Kedro 本体版本与生成时所用版本保持~兼容、kedro-datasets的 pandas CSV 支持对应pandas.CSVDataset见下文 catalog 示例、以及 IPython/JupyterLab/Notebook对应 README 后面「How to work with Kedro and notebooks」一节。pyproject.toml 中的依赖与开发工具模板同时提供 pyproject.toml其中[project]段声明了与requirements.txt一致的核心依赖并补充了两组可选依赖[project.optional-dependencies] docs [ ... ] # Sphinx 文档构建工具链 dev [ pytest-cov3,7, pytest-mock1.7.1, 2.0, pytest~7.2, ruff~0.1.8 ]dev组把 README「How to test」一节所需的pytest、覆盖率插件pytest-cov、pytest-mock以及代码风格检查工具ruff一并管理起来。requires-python 3.9说明了该模板支持的最低 Python 版本。另在[project.scripts]中定义了命令入口[project.scripts] {{ cookiecutter.repo_name }} {{ cookiecutter.python_package }}.__main__:main这意味着项目安装后可以直接在终端输入仓库名来启动 Kedro CLI。[tool.kedro]段则记录了package_name、project_name、kedro_init_version、source_dir src等项目元信息供 Kedro 框架在运行时读取。How to run Kedro运行 Pipeline一条命令跑通默认流水线kedro run这条命令会执行pipeline_registry.py中注册的__default__流水线。模板的 pipeline_registry.py 实现如下def register_pipelines() - dict[str, Pipeline]: Register the projects pipelines. pipelines find_pipelines(raise_errorsTrue) pipelines[__default__] sum(pipelines.values()) return pipelines它通过find_pipelines自动发现项目内所有注册的流水线并把它们合并为__default__因此kedro run默认会跑全部已发现的流水线。kedro run的完整参数如--pipeline、--node、--from-inputs、--to-outputs等可查阅 docs/getting-started/commands_reference.md命令行实现位于 kedro/framework/cli/project.py。入口脚本如何把命令接到 Kedro CLI项目还支持两种等价的可执行方式python -m {{ cookiecutter.python_package }}或安装后直接运行仓库名命令。这一机制由模板的main.py 提供def main(*args, **kwargs) - Any: package_name Path(__file__).parent.name configure_project(package_name) interactive hasattr(sys, ps1) kwargs[standalone_mode] not interactive run find_run_command(package_name) return run(*args, **kwargs)它先调用configure_project初始化项目配置再通过find_run_command定位到 Kedro CLI 的 run 命令并执行——这也解释了为什么在交互式IPython环境下也能复用同一套命令分发逻辑。How to test your Kedro project测试与覆盖率从 tests/test_run.py 出发README 提示读者查看tests/test_run.py了解如何编写测试并直接给出运行命令pytest测试版模板的 tests/test_run.py 展示了 Kedro 项目测试的标准写法通过OmegaConfigLoader加载conf/配置、构造KedroContext再断言项目上下文信息pytest.fixture def config_loader(): return OmegaConfigLoader(conf_sourcestr(Path.cwd() / settings.CONF_SOURCE)) pytest.fixture def project_context(config_loader): return KedroContext( package_name{{ cookiecutter.python_package }}, project_pathPath.cwd(), config_loaderconfig_loader, hook_manager_create_hook_manager(), ) class TestProjectContext: def test_project_path(self, project_context): assert project_context.project_path Path.cwd()文件头部的模块文档字符串还给出了测试的组织约定测试应放在镜像项目结构的模块中命名为test_*.py测试函数命名为test_*。从源码结构看这与仓库自身的测试组织方式一致如 tests/framework/test_startup.py、tests/io/test_data_catalog.py 等均按镜像结构组织。覆盖率阈值的配置位置README 指出覆盖率阈值配置在项目pyproject.toml的[tool.coverage.report]段。模板默认值如下见 pyproject.toml[tool.coverage.report] fail_under 0 show_missing true exclude_lines [pragma: no cover, raise NotImplementedError]fail_under 0默认不因覆盖率不达标而让测试失败团队可自行调高阈值例如改为 80show_missing true报告中标出未覆盖行exclude_lines设置需要从覆盖率统计中排除的行如pragma: no cover标注的行和raise NotImplementedError。同时[tool.pytest.ini_options]段配置了 pytest 的默认参数[tool.pytest.ini_options] addopts --cov-report term-missing \ --cov src/{{ cookiecutter.python_package }} -ra即运行pytest时会自动对src/下的项目包做覆盖率统计--cov以终端形式输出缺失行--cov-report term-missing并用-ra汇总所有测试结果。How to work with Kedro and notebooksNotebook 与 IPython 调试自动注入的三个变量context、catalog、sessionREADME 用一个醒目的提示说明了 Notebook 与 IPython 集成的关键Usingkedro jupyterorkedro ipythonto run your notebook provides these variables in scope:context,catalog, andsession.也就是说通过 Kedro 启动的 Notebook/IPython 会话中可以直接使用这三个对象context当前项目的KedroContext可访问项目路径、配置加载器等catalog当前项目的DataCatalog用于按名称加载/保存数据集如catalog.load(example_iris_data)session当前KedroSession用于管理运行与钩子。这一行为由 kedro/ipython/init.py 中的load_ipython_extension实现并配套了%load_node与%reload_kedro等魔法命令见 kedro/ipython/、docs/ipython 相关文档。仓库的 Notebook 集成测试见 tests/ipython/test_ipython.py命令行入口在 kedro/framework/cli/jupyter.py。三种启动方式场景安装命令启动命令Jupyter Notebookpip install jupyterkedro jupyter notebookJupyterLabpip install jupyterlabkedro jupyter labIPython 会话无需额外安装模板已依赖ipython8.10kedro ipython注意由于模板 requirements.txt 默认已包含jupyterlab、notebook、ipython新项目开箱即可使用这三种方式README 中的安装命令用于需要显式确认或隔离环境中缺少这些包时的补充操作。用 nbstripout 清理 Notebook 输出README 建议用nbstripout在提交前自动清除 Notebook 的输出单元nbstripout --install该命令会在.git/config中安装 Git 钩子使每次提交前自动剥离输出内容避免.ipynb的 JSON 输出造成无谓的 diff 与仓库膨胀。注意输出单元在本地仍然保留Your output cells will be retained locally.只影响提交内容。配套文件解读Data Catalog 与参数文件README 虽未逐行讲解但其「Overview」指向的 Kedro 文档以及「Rules」部分依赖的两类配置文件在模板中均有真实样例见 kedro/templates/project/{{ cookiecutter.repo_name }}/conf/base 与测试版 features/test_starter/{{ cookiecutter.repo_name }}/conf/basecatalog.yml中展示了三种数据集定义example_iris_data: type: pandas.CSVDataset filepath: data/01_raw/iris.csv example_model: type: pickle.PickleDataset filepath: data/06_models/example_model.pkl example_predictions: type: pickle.PickleDataset filepath: data/07_model_output/example_predictions.pkl对应的pandas.CSVDataset由kedro-datasets提供即requirements.txt中kedro-datasets[pandas-csvdataset]的作用而filepath使用data/0X_*分层路径正好呼应 README「数据工程分层约定」的规则。文件头部还给出了 Spark、SQL 数据集与转码transcoding等更高级用法的注释示例Data Catalog 的详细文档见 docs/catalog-data/introduction.md。parameters.yml则演示了流水线参数的声明方式example_test_data_ratio: 0.2 example_num_train_iter: 10000 example_learning_rate: 0.01参数通过params:前缀在节点中引用如params:example_test_data_ratio。参数与凭据的完整用法见 docs/configure/how_to_use_parameters_and_credentials.md。Package your Kedro project打包与文档构建README 最后一节引导读者查看打包指南。在仓库内对应的实战文档是 docs/deploy/package_a_project.md涵盖构建项目文档模板自带docs/source/的 Sphinx 工程见 kedro/templates/project/{{ cookiecutter.repo_name }}/docs可用pyproject.toml中的[project.optional-dependencies].docs安装文档工具链后构建打包为 Python 包pip install -e .等本地安装方式部署到生产环境结合 docs/deploy/index.md 可进一步了解单机、分布式与各类平台部署。需要特别说明README 中pip install -r requirements.txt与打包安装如pip install -e .可以并存——前者安装运行依赖后者将项目自身注册为可执行包对应[project.scripts]中的命令入口。小结模板 README 是每个 Kedro 新项目的第一份技术文档它用最少篇幅覆盖了项目全生命周期的关键操作依赖管理requirements.txt运行时依赖pyproject.toml打包元数据与docs/dev可选依赖运行kedro run执行pipeline_registry.py中注册的__default__流水线测试pytest[tool.coverage.report]覆盖率配置测试写法参考tests/test_run.py交互式开发kedro jupyter notebook、kedro jupyter lab、kedro ipython提供context、catalog、session三个内置变量配合nbstripout保持仓库干净规范约束.gitignore 不可删、分层数据目录、数据与凭据不入库、conf/local/存放敏感配置打包结合docs/deploy/package_a_project.md完成文档构建与项目打包。这些指引并非孤立文字而是与模板中的 pyproject.toml、requirements.txt、settings.py、pipeline_registry.py、tests/test_run.py 等文件一一对应。理解这份 README就等于拿到了 Kedro 项目日常开发与交付的完整操作地图。【免费下载链接】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），仅供参考