配置加载器迁移指南¶

自Kedro 0.18.12版本起，ConfigLoader和TemplatedConfigLoader类已被弃用，并在Kedro 0.19.0中移除。若要使用该版本或更高版本，您必须改用OmegaConfigLoader。本迁移指南概述了旧加载器与OmegaConfigLoader之间的主要区别，并提供了逐步说明，帮助您有效更新代码库以使用新类。

从`ConfigLoader`迁移到`OmegaConfigLoader`¶

1. 安装所需库¶

OmegaConfigLoader 是在 Kedro 0.18.5 版本中引入的，基于 OmegaConf。要使用它，您需要安装 Kedro（版本 0.18.5 或更高）和 omegaconf。您可以使用 pip 安装两者：

pip install kedro==0.18.5

这将是最低要求的Kedro版本，其中包含omegaconf作为依赖项。或者您可以运行：

pip install -U kedro

该命令将安装最新版本的Kedro，其中包含omegaconf作为依赖项。

2. 使用 `OmegaConfigLoader`¶

要在项目中使用OmegaConfigLoader，请在src//settings.py中设置CONFIG_LOADER_CLASS常量：

+ from kedro.config import OmegaConfigLoader  # new import

+ CONFIG_LOADER_CLASS = OmegaConfigLoader

3. 导入语句¶

将ConfigLoader的导入语句替换为OmegaConfigLoader的导入语句：

- from kedro.config import ConfigLoader

+ from kedro.config import OmegaConfigLoader

4. 文件格式支持¶

OmegaConfigLoader 仅支持 yaml 和 json 文件格式。请确保您的所有配置文件都采用其中一种格式。如果您之前使用 ConfigLoader 处理过其他格式的文件，请将它们转换为 yaml 或 json 格式。

5. 加载配置¶

使用OmegaConfigLoader加载配置的方法与ConfigLoader略有不同，后者允许用户通过.get()方法访问配置并要求将模式作为参数传入。当您迁移使用OmegaConfigLoader时，需要通过指向加载器类中指定的配置模式或在settings.py的CONFIG_LOADER_ARGS中提供的配置模式的配置键来获取配置。

- conf_path = str(project_path / settings.CONF_SOURCE)
- conf_loader = ConfigLoader(conf_source=conf_path, env="local")
- catalog = conf_loader.get("catalog*")

+ conf_path = str(project_path / settings.CONF_SOURCE)
+ config_loader = OmegaConfigLoader(conf_source=conf_path, env="local")
+ catalog = config_loader["catalog"]

在这个例子中，"catalog"是OmegaConfigLoader类中指定的默认目录模式的关键字。

6. 异常处理¶

在错误和异常处理方面，大多数错误是相同的。您需要注意原始ConfigLoader与OmegaConfigLoader之间的差异如下：

OmegaConfigLoader 在配置路径不存在时会抛出 MissingConfigException，而不是 ConfigLoader 中使用的 ValueError。
在OmegaConfigLoader中，如果配置文件存在语法错误，会触发ParserError而不是ConfigLoader中使用的BadConfigException。

从`TemplatedConfigLoader`迁移到`OmegaConfigLoader`¶

1. 安装所需库¶

OmegaConfigLoader 是在 Kedro 0.18.5 版本中引入的，基于 OmegaConf。替代 TemplatedConfigLoader 功能的相关特性已在后续版本发布，因此我们建议用户安装 Kedro 0.18.13 或更高版本，以便正确地将 TemplatedConfigLoader 替换为 OmegaConfigLoader。您可以使用 pip 同时安装此 Kedro 版本和 omegaconf：

pip install "kedro>=0.18.13"

这将是最低要求的Kedro版本，其中包含omegaconf作为依赖项，并具备替换TemplatedConfigLoader所需的功能。或者您可以运行：

pip install -U kedro

该命令将安装最新版本的Kedro，其中包含omegaconf作为依赖项。

2. 使用 `OmegaConfigLoader`¶

要在项目中使用OmegaConfigLoader，请在src/<package_name>/settings.py中设置CONFIG_LOADER_CLASS常量：

+ from kedro.config import OmegaConfigLoader  # new import

+ CONFIG_LOADER_CLASS = OmegaConfigLoader

3. 导入语句¶

将TemplatedConfigLoader的导入语句替换为OmegaConfigLoader的导入语句：

- from kedro.config import TemplatedConfigLoader
+ from kedro.config import OmegaConfigLoader

4. 文件格式支持¶

OmegaConfigLoader 仅支持 yaml 和 json 文件格式。请确保所有配置文件都采用其中一种格式。如果您之前使用 TemplatedConfigLoader 处理其他格式，请将它们转换为 yaml 或 json。

5. 加载配置¶

使用OmegaConfigLoader加载配置的方法与TemplatedConfigLoader略有不同，后者允许用户通过.get()方法访问配置并要求模式作为参数。当您迁移使用OmegaConfigLoader时，需要通过指向加载器类中指定的配置模式或在settings.py的CONFIG_LOADER_ARGS中提供的配置键来获取配置。

- conf_path = str(project_path / settings.CONF_SOURCE)
- conf_loader = TemplatedConfigLoader(conf_source=conf_path, env="local")
- catalog = conf_loader.get("catalog*")

+ conf_path = str(project_path / settings.CONF_SOURCE)
+ config_loader = OmegaConfigLoader(conf_source=conf_path, env="local")
+ catalog = config_loader["catalog"] # note the key accessor syntax

在这个示例中，"catalog"键指向OmegaConfigLoader类中指定的默认目录模式。

6. 值模板化¶

值的模板化是通过原生的OmegaConfigLoader中的变量插值实现的。在TemplatedConfigLoader中需要在一个globals文件或字典中提供模板值，而在OmegaConfigLoader中，您可以在包含占位符的同一文件中或遵循相同配置模式命名的文件中提供这些值。变量插值的作用域限定于特定的配置类型和环境。如果您希望在配置类型和环境之间共享模板值，则需要使用globals。

假设您正在将一个模板化的目录文件从使用TemplatedConfigLoader迁移到OmegaConfigLoader，您需要执行以下操作：

将conf/base/globals.yml重命名为符合catalog指定的模式（["catalog*", "catalog*/**", "**/catalog*"]），例如conf/base/catalog_globals.yml
在任何目录模板值中添加下划线_。由于目录条目验证机制的要求，这一操作是必要的。

- bucket_name: "my_s3_bucket"
+ _bucket_name: "my_s3_bucket" # kedro requires `_` to mark templatable keys
- key_prefix: "my/key/prefix/"
+ _key_prefix: "my/key/prefix/"

- datasets:
+ _datasets:
    csv: "pandas.CSVDataset"
    spark: "spark.SparkDataset"

更新 catalog.yml 文件，在模板值名称的开头添加下划线 _。

raw_boat_data:
-   type: "${datasets.spark}"
+   type: "${_datasets.spark}"
-   filepath: "s3a://${bucket_name}/${key_prefix}/raw/boats.csv"
+   filepath: "s3a://${_bucket_name}/${_key_prefix}/raw/boats.csv"
    file_format: parquet

raw_car_data:
-    type: "${datasets.csv}"
+    type: "${_datasets.csv}"
-    filepath: "s3://${bucket_name}/data/${key_prefix}/raw/cars.csv"
+    filepath: "s3://${_bucket_name}/data/${_key_prefix}/raw/cars.csv"

通过`oc.select`为模板提供默认值¶

要为任何模板值提供默认值，您必须使用omegaconf的oc.select解析器。

boats:
  users:
    - fred
-    - "${write_only_user|ron}"
+    - "${oc.select:write_only_user,ron}"

7. 全局变量¶

如果您需要在不同配置类型（例如参数和目录）以及环境之间共享变量，您需要使用带有OmegaConfigLoader的自定义全局变量解析器。 OmegaConfigLoader要求全局值必须通过globals.yml文件提供。请注意，OmegaConfigLoader不支持使用globals_dict来提供全局变量。以下部分将说明在使用TemplatedConfigLoader和OmegaConfigLoader时处理全局变量的区别。

假设您的项目包含一个conf/base/globals.yml文件，其内容如下：

bucket_name: "my_s3_bucket"
key_prefix: "my/key/prefix/"

datasets:
    csv: "pandas.CSVDataset"
    spark: "spark.SparkDataset"

folders:
    raw: "01_raw"
    int: "02_intermediate"
    pri: "03_primary"
    fea: "04_feature"

您不再需要在src//settings.py中设置CONFIG_LOADER_ARGS变量来查找这个globals.yml文件，因为OmegaConfigLoader默认配置为自动识别名为globals.yml的文件。

- CONFIG_LOADER_ARGS = {"globals_pattern": "*globals.yml"}

您的目录配置中的全局变量模板需要更新为使用全局解析器，如下所示：

raw_boat_data:
-   type: "${datasets.spark}"
+   type: "${globals:datasets.spark}"  # nested paths into global dict are allowed
-   filepath: "s3a://${bucket_name}/${key_prefix}/${folders.raw}/boats.csv"
+   filepath: "s3a://${globals:bucket_name}/${globals:key_prefix}/${globals:folders.raw}/boats.csv"
    file_format: parquet

raw_car_data:
-   type: "${datasets.csv}"
+   type: "${globals:datasets.csv}"
-   filepath: "s3://${bucket_name}/data/${key_prefix}/${folders.raw}/${filename|cars.csv}"  # default to 'cars.csv' if the 'filename' key is not found in the global dict
+   filepath: "s3://${globals:bucket_name}/data/${globals:key_prefix}/${globals:folders.raw}/${globals:filename,'cars.csv'}"  # default to 'cars.csv' if the 'filename' key is not found in the global dict

8. 弃用Jinja2¶

OmegaConfigLoader 不支持在配置中使用Jinja2语法。不过，用户可以通过结合使用OmegaConfigLoader和dataset factories来实现类似功能。以下示例展示了如何重写您的Jinja2配置以适配OmegaConfigLoader：

# catalog.yml
- {% for speed in ['fast', 'slow'] %}
- {{ speed }}-trains:
+ "{speed}-trains":
    type: MemoryDataset

- {{ speed }}-cars:
+ "{speed}-cars":
    type: pandas.CSVDataset
-    filepath: s3://${bucket_name}/{{ speed }}-cars.csv
+    filepath: s3://${bucket_name}/{speed}-cars.csv
    save_args:
        index: true

- {% endfor %}

9. 异常处理¶

在错误和异常处理方面，大多数错误是相同的。您需要注意原始TemplatedConfigLoader与OmegaConfigLoader之间的主要差异如下：

对于缺失的模板值，OmegaConfigLoader会抛出omegaconf.errors.InterpolationKeyError错误。

配置加载器迁移指南¶

从ConfigLoader迁移到OmegaConfigLoader¶

1. 安装所需库¶

2. 使用 OmegaConfigLoader¶

3. 导入语句¶

4. 文件格式支持¶

5. 加载配置¶

6. 异常处理¶

从TemplatedConfigLoader迁移到OmegaConfigLoader¶

1. 安装所需库¶

2. 使用 OmegaConfigLoader¶

3. 导入语句¶

4. 文件格式支持¶

5. 加载配置¶

6. 值模板化¶

通过oc.select为模板提供默认值¶

7. 全局变量¶

8. 弃用Jinja2¶

9. 异常处理¶

从`ConfigLoader`迁移到`OmegaConfigLoader`¶

2. 使用 `OmegaConfigLoader`¶

从`TemplatedConfigLoader`迁移到`OmegaConfigLoader`¶

2. 使用 `OmegaConfigLoader`¶

通过`oc.select`为模板提供默认值¶