企业官网建设流程全解析

Kedro Starters 使用与自定义指南：用 Cookiecutter 模板快速搭建生产级 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

本文围绕 Kedro 的 Starter 机制展开，讲解如何通过kedro new --starter使用官方或自定义模板创建项目、如何利用别名与--checkout进行版本管理，以及如何基于prompts.yml、cookiecutter.json和插件入口点构建团队内部可复用的 Starter。读完本文，你将掌握从「选模板建项目」到「写模板并发布为别名」的完整链路，并能结合仓库源码理解 Kedro 与 Cookiecutter 的协作方式。

什么是 Kedro Starter

Kedro Starter 是一段以 Cookiecutter 模板形式存在的代码，用于生成一个完整的 Kedro 项目骨架。使用 Starter 创建项目，就像在使用幻灯片或文档软件时套用一个预设布局：Starter 决定新项目包含哪些文件、目录、示例代码和工程化配置，而 Cookiecutter 负责把这些占位符替换成你输入的实际值。

从源码结构看，Kedro 将「模板」与「别名」统一定义为KedroStarterSpec对象（kedro/framework/cli/starters.py），包含四个字段：

• alias：Starter 的别名，出现在kedro starter list中，也是kedro new --starter的可选入参；
• template_path：模板路径，可以是本地目录，也可以是 Cookiecutter 支持的远程 VCS 仓库地址；
• directory：可选字段，当同一仓库内含多个模板时，用它指定模板所在子目录；
• origin：保留字段，由 Kedro 内部用来标记 Starter 的来源（官方为kedro，插件来源则取插件模块名），用户无需提供。

Kedro 自身的默认项目模板位于 kedro/templates/project，当不指定任何 Starter 时，kedro new会使用该内置模板（源码中通过TEMPLATE_PATH = KEDRO_PATH / "templates" / "project"定位）。

如何使用 Starter 创建项目

使用 Starter 创建项目，只需给kedro new加上--starter参数：

uvx kedro new --starter=<path-to-starter>

其中<path-to-starter>可以是以下三种形式之一：

1. 本地目录路径；
2. 由 Cookiecutter 支持的远程 VCS 仓库 URL；
3. kedro starter list中列出的别名之一。

说明：使用uvx可以在不把 Kedro 安装进系统或虚拟环境的情况下运行它——每次调用它都会在一个干净的临时环境中下载并执行 Kedro。如果你更习惯标准安装方式（例如 pip + 虚拟环境），请参考 安装指南。

当 Starter 存放在远程 VCS 仓库中，且该仓库同时包含多个模板时，需要通过--directory指定模板所在子目录：

uvx kedro new --starter git+https://github.com/kedro-org/kedro-starters.git --directory spaceflights-pandas

与 Starter 相关的kedro new参数

围绕 Starter 的使用，kedro new提供了以下几个核心参数（均定义在 kedro/framework/cli/starters.py 的new命令上）：

从源码的_validate_flag_inputs可以看到两条关键约束：

• --directory不能脱离--starter单独使用（Cannot use the --directory flag without a --starter value）；
• --starter不能与--example、--tools混用（Cannot use the --starter flag with the --example and/or --tools flag）。

另外，--directory只能用于本地路径或远程仓库形式的 Starter，不能与别名搭配——源码中如果检测到starter_alias命中别名表且同时传入了directory，会直接抛出Cannot use the --directory flag with a --starter alias错误。因为别名本身已经通过KedroStarterSpec.directory携带了目录信息，无需再指定。

Starter 别名与kedro starter list

Kedro 团队为常用官方 Starter 提供了别名，使用别名时不必写出完整仓库路径。例如，使用spaceflights-pandasStarter 创建项目：

uvx kedro new --starter=spaceflights-pandas

查看当前支持的全部别名：

kedro starter list

该命令的实现位于 starter.py 的starter list子命令：它聚合所有来源的 Starter 规格，按origin分组并以 YAML 形式输出每个别名的template_path与directory。官方 Starter 总是排在输出最前面。

别名解析的底层逻辑在_get_starters_dict()中：它先从核心仓库内置的_OFFICIAL_STARTER_SPECS_DICT收集官方别名，再遍历kedro.starters入口点加载插件声明的 Starter；如果插件声明的别名与官方别名冲突，插件别名会被忽略并打印警告。也就是说，插件完全可以扩展这个别名表。

官方 Kedro Starters

Kedro 团队目前维护以下官方 Starter（对应 kedro/framework/cli/starters.py 中的_OFFICIAL_STARTER_SPECS，全部存放在官方 kedro-starters 仓库的对应目录下，template_path统一指向该仓库，directory指向各自的子目录）：

已归档的 Starters

以下 Starter 已归档，在 Kedro 0.19.0 及之后版本中不可用：

• standalone-datacatalog
• pandas-iris
• pyspark-iris
• pyspark

最后一个支持这些 Starter 的 Kedro 版本是0.18.14。如果你确实需要它们：

1. 检查当前安装的 Kedro 版本：在终端输入kedro -V；
2. 安装指定版本（例如 0.18.14）：pip install kedro==0.18.14；
3. 在 0.18.14 下创建项目时，同时用--checkout锁定 Starter 版本，例如使用pandas-iris：kedro new --starter=pandas-iris --checkout=0.18.14。

Starter 版本管理：--checkout

默认情况下，Kedro 使用 Starter 仓库中当前可用的最新版本。若想固定使用某个版本，可通过--checkout参数指定：

uvx kedro new --starter=spaceflights-pandas --checkout=0.1.0

--checkout的值可以是 Starter 仓库中的任意分支（branch）、标签（tag）或提交（commit）。底层实现中，该值会被原样传递给 Cookiecutter 的--checkout参数。

值得注意的默认行为：在 starters.py 的_select_checkout_branch_for_cookiecutter中，当使用官方别名且未显式传入--checkout时，Kedro 会把当前安装的 Kedro 版本号作为默认 checkout 值。这意味着官方 kedro-starters 仓库按 Kedro 版本打 tag 时，会自动为你检出与当前 Kedro 版本匹配的模板；如果你希望忽略这种默认行为，可以用--checkout显式覆盖（例如--checkout=main）。_get_available_tags函数还会通过git ls-remote列出仓库可用 tag，在模板未找到时给出提示。

使用配置文件配合 Starter

默认情况下，用 Starter 创建项目时，kedro new会交互式地询问project_name，并据此自动生成repo_name和python_package——这与 创建新的 Kedro 项目 的默认流程一致。三个变量的含义如下：

当 Starter 需要的配置项比默认模式更多时，可以用--config参数配合一个 YAML 配置文件来非交互式地完成创建：

uvx kedro new --config=my_kedro_project.yml --starter=spaceflights-pandas

配置文件中至少需要包含prompts.yml要求的所有键（对大多数官方 Starter 而言即project_name、repo_name、python_package）。一个可参考的配置示例：

project_name: "Get Started" repo_name: "get-started" python_package: "get_started"

从源码看，--config的校验逻辑（_fetch_validate_parse_config_from_file与_validate_config_file_against_prompts）包含以下几点：

• 配置文件必须包含prompts.yml中声明的全部必填键，否则报错列出缺失项；
• tools与example_pipeline是可选键，缺省时分别使用默认值none与no；
• 使用--starter时，配置文件中不允许出现tools或example_pipeline键，否则直接抛出错误（The --starter flag can not be used with example_pipeline and/or tools keys in the config file）；
• 可选支持output_dir键指定输出目录，且该目录必须真实存在；
• project_name会经过正则校验（^[\w -]{2,}$，只允许字母数字、空格、下划线与连字符，且至少 2 个字符）。

此外，_validate_package_name_is_importable会校验最终生成的 Python 包名不能是 Python 关键字（如import）或标准库模块名（如email、json），否则项目生成后无法被正确 import，kedro run会因ModuleNotFoundError失败。

创建自定义 Starter

你可以构建自己的 Starter 供项目组或团队内部复用，完整操作见 如何创建 Kedro Starter。创建好的自定义 Starter 同样通过--starter使用，若是放在一个包含多个模板的仓库中，还需要配合--directory指定子目录：

uvx kedro new --starter=<path-to-starter> --directory <directory>

一个 Kedro Starter 的本质是一个 Cookiecutter 模板，其目录布局大致如下（{{ cookiecutter.xxx }}是待 Cookiecutter 替换的占位符）：

{{ cookiecutter.repo_name }} # 模板的父目录 ├── conf # 项目配置文件 ├── data # 本地项目数据（不提交到版本控制） ├── docs # 项目文档 ├── notebooks # 项目相关 Jupyter notebook（实验代码可先放这里） ├── pyproject.toml ├── README.md ├── requirements.txt ├── src # 项目源代码 │ └── {{ cookiecutter.python_package }} │ ├── __init__.py │ ├── pipelines │ ├── pipeline_registry.py │ ├── __main__.py │ └── settings.py └── tests

定制交互式提示：prompts.yml

kedro new的交互式问题由模板根目录下的prompts.yml驱动（Kedro 内置模板的示例见 kedro/templates/project/prompts.yml，包含project_name、tools、example_pipeline三个提示）。自定义提示的基本结构如下：

custom_prompt: title: "Prompt title" text: | Prompt description that explains to the user what information they should provide.

规则与能力：

• 每个提示至少必须定义title字段，否则kedro new会报错（源码中_Prompt类要求title键存在）；
• text用于展示问题描述；regex_validator用于输入校验，error_message用于给出校验失败提示；
• 用户输入会作为 CookieCutter 的 extra context 传入，因此prompts.yml中的每个键都必须在cookiecutter.json中有对应键，Cookiecutter 才能消费这些值；
• 默认值可写在cookiecutter.json中（参考 kedro/templates/project/cookiecutter.json，内含project_name、repo_name、python_package、kedro_version、tools、example_pipeline等键），当用户不输入时生效；
• 更复杂的校验逻辑可以借助 Cookiecutter 的 pre/post-generate hooks 实现。

通过插件入口点扩展 Starter 别名

除了本地路径与远程仓库，你还可以把自定义 Starter 注册为别名，从而直接kedro new --starter=your_starter。做法是在插件中导出一个KedroStarterSpec列表，例如（仓库中的示例见 features/test_plugin/plugin.py）：

# plugin.py starters = [ KedroStarterSpec( alias="test_plugin_starter", template_path="your_local_directory/starter_folder", ) ]

如果模板存放在 Git 仓库中，则加上directory指定子目录：

starters = [ KedroStarterSpec( alias="test_plugin_starter", template_path="<your-git-repo-url>", directory="spaceflights-pandas", ) ]

directory是可选参数，用于「一个仓库包含多个模板」的场景（官方 kedro-starters 仓库即如此）；当仓库顶层就是一个模板时，无需指定。随后在插件的pyproject.toml中注册入口点（可参考 features/test_plugin/pyproject.toml）：

[project.entry-points."kedro.starters"] starter = "plugin:starters"

完成注册后即可直接使用：kedro new --starter=test_plugin_starter。自定义别名与官方别名行为一致，也会出现在kedro starter list中。

底层原理：kedro new与 Starter 的协作流程

结合 kedro/framework/cli/starters.py，kedro new处理 Starter 的完整调用链如下：

1. 校验参数：_validate_flag_inputs检查--directory、--starter、--tools、--example的组合合法性；
2. 解析模板来源：_get_starters_dict返回别名表；若--starter命中别名则取出对应template_path/directory并计算默认 checkout；若未命中别名则直接把--starter的值当作模板路径；若完全没有--starter则回退到内置模板TEMPLATE_PATH；
3. 定位模板目录：_get_cookiecutter_dir通过 Cookiecutter 的determine_repo_dir解析模板——远程仓库会被克隆到临时目录，本地路径则直接使用；找不到模板时会抛出KedroCliError，并附上可用 tag 列表与官方别名清单；
4. 生成交互上下文：_get_prompts_required_and_clear_from_CLI_provided读取模板根目录的prompts.yml，把已经由 CLI 提供（--name、--tools、--example）的键从待提问集合中剔除，避免重复提问；
5. 收集配置：有--config则读取并校验配置文件，否则按prompts.yml逐个交互提问（_fetch_validate_parse_config_from_user_prompts通过_Prompt渲染提示并做正则校验）；
6. 构造 Cookiecutter 参数：_make_cookiecutter_args_and_fetch_template把directory映射为 Cookiecutter 的directory参数、checkout映射为其checkout参数，最终调用cookiecutter.main.cookiecutter完成渲染（_create_project），并在成功时打印Congratulations!与项目创建目录。

值得注意的是，源码中把no_input=True与extra_context一起传给 Cookiecutter，意味着所有交互输入最终都会被转成 context 字典，保证模板渲染全程无需二次交互。

相关文档

• 创建新的 Kedro 项目：不借助 Starter 的kedro new交互流程与工具选择
• 如何创建 Kedro Starter：Starter 模板的完整构建教程与入口点扩展细节
• spaceflights 教程：spaceflights-pandas/spaceflights-pyspark示例项目的配套实战教程
• 安装指南：uvx之外的其他 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