diff --git a/RELEASE.md b/RELEASE.md index a1fac7935a..71b8a4748b 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -17,6 +17,7 @@ * Updated `kedro pipeline create` and `kedro catalog create` to use new `/conf` file structure. ## Documentation changes +* Added migration guide from the `ConfigLoader` to the `OmegaConfigLoader`. The `ConfigLoader` is deprecated and will be removed in the `0.19.0` release. ## Breaking changes to the API diff --git a/docs/source/configuration/config_loader_migration.md b/docs/source/configuration/config_loader_migration.md new file mode 100644 index 0000000000..f27b244afe --- /dev/null +++ b/docs/source/configuration/config_loader_migration.md @@ -0,0 +1,62 @@ +# Migration guide for config loaders +The `ConfigLoader` and `TemplatedConfigLoader` classes have been deprecated since Kedro `0.18.12` and will be removed in Kedro `0.19.0`. To ensure a smooth transition, we strongly recommend you adopt the [`OmegaConfigLoader`](/kedro.config.OmegaConfigLoader) as soon as possible. +This migration guide outlines the primary distinctions between the old loaders and the `OmegaConfigLoader`, providing step-by-step instructions on updating your code base to utilise the new class effectively. + +## [`ConfigLoader`](/kedro.config.ConfigLoader) to [`OmegaConfigLoader`](/kedro.config.OmegaConfigLoader) + +### 1. Install the Required Library +The [`OmegaConfigLoader`](advanced_configuration.md#omegaconfigloader) was introduced in Kedro `0.18.5` and is based on [OmegaConf](https://omegaconf.readthedocs.io/). In order to use it you need to ensure you have both a version of Kedro of `0.18.5` or above and `omegaconf` installed. +You can install both using `pip`: + +```bash +pip install kedro==0.18.5 +``` +This would be the minimum required Kedro version which includes `omegaconf` as a dependency. +Or you can run: +```bash +pip install -U kedro +``` + +This command installs the most recent version of Kedro which also includes `omegaconf` as a dependency. + +### 2. Use the `OmegaConfigLoader` +To use `OmegaConfigLoader` in your project, set the `CONFIG_LOADER_CLASS` constant in your [`src//settings.py`](../kedro_project_setup/settings.md): + +```diff ++ from kedro.config import OmegaConfigLoader # new import + ++ CONFIG_LOADER_CLASS = OmegaConfigLoader +``` + +### 3. Import Statements +Replace the import statement for `ConfigLoader` with the one for `OmegaConfigLoader`: + +```diff +- from kedro.config import ConfigLoader + ++ from kedro.config import OmegaConfigLoader +``` + +### 4. File Format Support +`OmegaConfigLoader` supports only `yaml` and `json` file formats. Make sure that all your configuration files are in one of these formats. If you previously used other formats with `ConfigLoader`, convert them to `yaml` or `json`. + +### 5. Load Configuration +The method to load the configuration using `OmegaConfigLoader` differs slightly from that used by `ConfigLoader`, which allowed users to access configuration through the `.get()` method and required patterns as argument. +When you migrate to use `OmegaConfigLoader` it requires you to fetch configuration through a configuration key that points to [configuration patterns specified in the loader class](configuration_basics.md#configuration-patterns) or [provided in the `CONFIG_LOADER_ARGS`](advanced_configuration.md#how-to-change-which-configuration-files-are-loaded) in `settings.py`. + +```diff +- 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"] +``` + +In this example, `"catalog"` is the key to the default catalog patterns specified in the `OmegaConfigLoader` class. + +### 6. Exception Handling +For error and exception handling, most errors are the same. Those you need to be aware of that are different between the original `ConfigLoader` and `OmegaConfigLoader` are as follows: +* `OmegaConfigLoader` throws a `MissingConfigException` when configuration paths don't exist, rather than the `ValueError` used in `ConfigLoader`. +* In `OmegaConfigLoader`, if there is bad syntax in your configuration files, it will trigger a `ParserError` instead of a `BadConfigException` used in `ConfigLoader`. diff --git a/docs/source/configuration/index.md b/docs/source/configuration/index.md index 3f554e1e91..291a4fbf65 100644 --- a/docs/source/configuration/index.md +++ b/docs/source/configuration/index.md @@ -6,5 +6,6 @@ configuration_basics credentials parameters +config_loader_migration advanced_configuration ```