Support deprecation info in Config (#1275)

* Support deprecation checking in Config

* add unittest for config deprecation

* support reference link in deprecation info

* add doc

* Update config.md

docs/understand_mmcv/config.md

@@ -177,3 +177,24 @@ item1 = 'a'
 item2 = dict(item3='b')
 item = dict(a='a', b='b')
 ```
+
+### Add deprecation information in configs
+
+Deprecation information can be added in a config file, which will trigger a `UserWarning` when this config file is loaded.
+
+`deprecated_cfg.py`
+
+```python
+_base_ = 'expected_cfg.py'
+
+_deprecation_ = dict(
+    expected = 'expected_cfg.py',  # optional to show expected config path in the warning information
+    reference = 'url to related PR'  # optional to show reference link in the warning information
+)
+```
+
+```python
+>>> cfg = Config.fromfile('./deprecated_cfg.py')
+
+UserWarning: The config file deprecated.py will be deprecated in the future. Please use expected_cfg.py instead. More information can be found at https://github.com/open-mmlab/mmcv/pull/1275
+```

mmcv/utils/config.py

@@ -26,6 +26,7 @@ else:
 
 BASE_KEY = '_base_'
 DELETE_KEY = '_delete_'
+DEPRECATION_KEY = '_deprecation_'
 RESERVED_KEYS = ['filename', 'text', 'pretty_text']
 
 
@@ -217,6 +218,19 @@ class Config:
             # close temp file
             temp_config_file.close()
 
+        # check deprecation information
+        if DEPRECATION_KEY in cfg_dict:
+            deprecation_info = cfg_dict.pop(DEPRECATION_KEY)
+            warning_msg = f'The config file {filename} will be deprecated ' \
+                'in the future.'
+            if 'expected' in deprecation_info:
+                warning_msg += f' Please use {deprecation_info["expected"]} ' \
+                    'instead.'
+            if 'reference' in deprecation_info:
+                warning_msg += ' More information can be found at ' \
+                    f'{deprecation_info["reference"]}'
+            warnings.warn(warning_msg)
+
         cfg_text = filename + '\n'
         with open(filename, 'r', encoding='utf-8') as f:
             # Setting encoding explicitly to resolve coding issue on windows

tests/data/config/deprecated.py

+_base_ = './expected.py'
+
+_deprecation_ = dict(
+    expected='tests/data/config/expected.py',
+    reference='https://github.com/open-mmlab/mmcv/pull/1275')

tests/data/config/deprecated_as_base.py

+_base_ = './deprecated.py'
\ No newline at end of file

tests/data/config/expected.py

+item1 = 'expected'

tests/test_utils/test_config.py

@@ -513,3 +513,15 @@ def test_pickle_support():
         pkl_cfg = load(pkl_cfg_filename)
 
     assert pkl_cfg._cfg_dict == cfg._cfg_dict
+
+
+def test_deprecation():
+    deprecated_cfg_files = [
+        osp.join(data_path, 'config/deprecated.py'),
+        osp.join(data_path, 'config/deprecated_as_base.py')
+    ]
+
+    for cfg_file in deprecated_cfg_files:
+        with pytest.warns(UserWarning):
+            cfg = Config.fromfile(cfg_file)
+        assert cfg.item1 == 'expected'