Add deprecated_aliases to runopt and add warning (meta-pytorch#1142)

Summary:

Lets introduce `deprecated_aliases` that would warn folks that a specific alias is deprecated.

Differential Revision: D84180061

Author: AbishekS

torchx/specs/api.py

@@ -15,6 +15,7 @@
 import pathlib
 import re
 import typing
+import warnings
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -897,6 +898,7 @@ class runopt:
     is_required: bool
     help: str
     aliases: Optional[List[str]] = None
+    deprecated_aliases: Optional[List[str]] = None
 
     @property
     def is_type_list_of_str(self) -> bool:
@@ -1037,12 +1039,21 @@ def resolve(self, cfg: Mapping[str, CfgVal]) -> Dict[str, CfgVal]:
             if val is not None:
                 if cfg_key not in cfg_keys_checked:
                     cfg_keys_checked.update(runopt.aliases or [])
+                    if runopt.deprecated_aliases is not None:
+                        for alias in runopt.deprecated_aliases or []:
+                            if alias in resolved_cfg:
+                                warnings.warn(
+                                    f"Run option: {cfg_key}, is deprecated.",
+                                    DeprecationWarning,
+                                    stacklevel=2,
+                                )
                 else:
                     raise InvalidRunConfigException(
                         f"Run option: {cfg_key}, is an alias of another run option already used in the cfg.",
                         cfg_key,
                         cfg,
                     )
+
             # check required opt
             if runopt.is_required and val is None:
                 raise InvalidRunConfigException(
@@ -1161,6 +1172,7 @@ def add(
         help: str,
         default: CfgVal = None,
         required: bool = False,
+        deprecated_aliases: Optional[List[str]] = None,
     ) -> None:
         """
         Adds the ``config`` option with the given help string and ``default``
@@ -1178,7 +1190,7 @@ def add(
                     f"Option: {cfg_key}, must be of type: {type_}."
                     f" Given: {default} ({type(default).__name__})"
                 )
-        opt = runopt(default, type_, required, help, aliases)
+        opt = runopt(default, type_, required, help, aliases, deprecated_aliases)
         for alias in aliases:
             if alias in self._opts:
                 raise ValueError(

torchx/specs/test/api_test.py

@@ -13,6 +13,7 @@
 import tempfile
 import time
 import unittest
+import warnings
 from dataclasses import asdict
 from pathlib import Path
 from typing import Dict, List, Mapping, Tuple, Union
@@ -592,6 +593,21 @@ def test_runopts_resolve_with_aliases(self) -> None:
         with self.assertRaises(InvalidRunConfigException):
             opts.resolve({"run_as": "foobar", "run_as_alias": "foobar_alias"})
 
+    def test_runopts_add_with_deprecated_aliases(self) -> None:
+        opts = runopts()
+        opts.add(
+            ["run_as", "run_as_alias"],
+            type_=str,
+            help="run as user",
+            deprecated_aliases=["run_as_alias"],
+        )
+        opts.resolve({"run_as": "foobar"})
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            opts.resolve({"run_as_alias": "foobar"})
+            self.assertEqual(len(w), 1)
+            self.assertEqual(w[0].category, DeprecationWarning)
+
     def get_runopts(self) -> runopts:
         opts = runopts()
         opts.add("run_as", type_=str, help="run as user", required=True)