[2.1 API] Enable printing deprecated warning info. (#32712)

* Add deprecated warning info.

* Add unittest for deprecated decorator.

* Add warning info for tensor.grad

python/paddle/dataset/cifar.py

@@ -79,6 +79,7 @@ def reader_creator(filename, sub_name, cycle=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Cifar100",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train100():
     """
@@ -98,6 +99,7 @@ def train100():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Cifar100",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test100():
     """
@@ -117,6 +119,7 @@ def test100():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Cifar10",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train10(cycle=False):
     """
@@ -139,6 +142,7 @@ def train10(cycle=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Cifar10",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test10(cycle=False):
     """
@@ -161,6 +165,7 @@ def test10(cycle=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Cifar10",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(CIFAR10_URL, 'cifar', CIFAR10_MD5)

python/paddle/dataset/conll05.py

@@ -206,6 +206,7 @@ def reader_creator(corpus_reader,
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Conll05st",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def get_dict():
     """
@@ -223,6 +224,7 @@ def get_dict():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Conll05st",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def get_embedding():
     """
@@ -234,6 +236,7 @@ def get_embedding():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Conll05st",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test():
     """
@@ -258,6 +261,7 @@ def test():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Conll05st",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(WORDDICT_URL, 'conll05st', WORDDICT_MD5)

python/paddle/dataset/flowers.py

@@ -156,6 +156,7 @@ def reader_creator(data_file,
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Flowers",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train(mapper=train_mapper, buffered_size=1024, use_xmap=True, cycle=False):
     '''
@@ -189,6 +190,7 @@ def train(mapper=train_mapper, buffered_size=1024, use_xmap=True, cycle=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Flowers",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test(mapper=test_mapper, buffered_size=1024, use_xmap=True, cycle=False):
     '''
@@ -222,6 +224,7 @@ def test(mapper=test_mapper, buffered_size=1024, use_xmap=True, cycle=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.Flowers",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def valid(mapper=test_mapper, buffered_size=1024, use_xmap=True):
     '''

python/paddle/dataset/imdb.py

@@ -80,6 +80,7 @@ def build_dict(pattern, cutoff):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imdb",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def reader_creator(pos_pattern, neg_pattern, word_idx):
     UNK = word_idx['<unk>']
@@ -102,6 +103,7 @@ def reader_creator(pos_pattern, neg_pattern, word_idx):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imdb",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train(word_idx):
     """
@@ -123,6 +125,7 @@ def train(word_idx):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imdb",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test(word_idx):
     """
@@ -144,6 +147,7 @@ def test(word_idx):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imdb",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def word_dict():
     """
@@ -159,6 +163,7 @@ def word_dict():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imdb",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(URL, 'imdb', MD5)

python/paddle/dataset/imikolov.py

@@ -115,6 +115,7 @@ def reader_creator(filename, word_idx, n, data_type):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imikolov",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train(word_idx, n, data_type=DataType.NGRAM):
     """
@@ -139,6 +140,7 @@ def train(word_idx, n, data_type=DataType.NGRAM):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imikolov",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test(word_idx, n, data_type=DataType.NGRAM):
     """
@@ -163,6 +165,7 @@ def test(word_idx, n, data_type=DataType.NGRAM):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Imikolov",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(URL, "imikolov", MD5)

python/paddle/dataset/mnist.py

@@ -93,6 +93,7 @@ def reader_creator(image_filename, label_filename, buffer_size):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.MNIST",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train():
     """
@@ -114,6 +115,7 @@ def train():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.MNIST",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test():
     """
@@ -134,6 +136,7 @@ def test():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.MNIST",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(TRAIN_IMAGE_URL, 'mnist', TRAIN_IMAGE_MD5)

python/paddle/dataset/movielens.py

@@ -168,6 +168,7 @@ def __reader__(rand_seed=0, test_ratio=0.1, is_test=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def __reader_creator__(**kwargs):
     return lambda: __reader__(**kwargs)
@@ -180,6 +181,7 @@ test = functools.partial(__reader_creator__, is_test=True)
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def get_movie_title_dict():
     """
@@ -199,6 +201,7 @@ def __max_index_info__(a, b):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def max_movie_id():
     """
@@ -211,6 +214,7 @@ def max_movie_id():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def max_user_id():
     """
@@ -230,6 +234,7 @@ def __max_job_id_impl__(a, b):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def max_job_id():
     """
@@ -243,6 +248,7 @@ def max_job_id():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def movie_categories():
     """
@@ -255,6 +261,7 @@ def movie_categories():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def user_info():
     """
@@ -267,6 +274,7 @@ def user_info():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def movie_info():
     """
@@ -288,6 +296,7 @@ def unittest():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.Movielens",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(URL, "movielens", MD5)

python/paddle/dataset/uci_housing.py

@@ -87,6 +87,7 @@ def load_data(filename, feature_num=14, ratio=0.8):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.UCIHousing",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train():
     """
@@ -111,6 +112,7 @@ def train():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.UCIHousing",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test():
     """
@@ -146,6 +148,7 @@ def fluid_model():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.UCIHousing",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def predict_reader():
     """
@@ -162,6 +165,7 @@ def predict_reader():
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.UCIHousing",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(URL, 'uci_housing', MD5)

python/paddle/dataset/voc2012.py

@@ -69,6 +69,7 @@ def reader_creator(filename, sub_name):
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.VOC2012",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train():
     """
@@ -80,6 +81,7 @@ def train():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.VOC2012",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test():
     """
@@ -91,6 +93,7 @@ def test():
 @deprecated(
     since="2.0.0",
     update_to="paddle.vision.datasets.VOC2012",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def val():
     """

python/paddle/dataset/wmt14.py

@@ -114,6 +114,7 @@ def reader_creator(tar_file, file_name, dict_size):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT14",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train(dict_size):
     """
@@ -134,6 +135,7 @@ def train(dict_size):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT14",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test(dict_size):
     """
@@ -154,6 +156,7 @@ def test(dict_size):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT14",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def gen(dict_size):
     return reader_creator(
@@ -164,6 +167,7 @@ def gen(dict_size):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT14",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def get_dict(dict_size, reverse=True):
     # if reverse = False, return dict = {'a':'001', 'b':'002', ...}
@@ -179,6 +183,7 @@ def get_dict(dict_size, reverse=True):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT14",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     paddle.dataset.common.download(URL_TRAIN, 'wmt14', MD5_TRAIN)

python/paddle/dataset/wmt16.py

@@ -142,6 +142,7 @@ def reader_creator(tar_file, file_name, src_dict_size, trg_dict_size, src_lang):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT16",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def train(src_dict_size, trg_dict_size, src_lang="en"):
     """
@@ -195,6 +196,7 @@ def train(src_dict_size, trg_dict_size, src_lang="en"):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT16",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def test(src_dict_size, trg_dict_size, src_lang="en"):
     """
@@ -248,6 +250,7 @@ def test(src_dict_size, trg_dict_size, src_lang="en"):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT16",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def validation(src_dict_size, trg_dict_size, src_lang="en"):
     """
@@ -299,6 +302,7 @@ def validation(src_dict_size, trg_dict_size, src_lang="en"):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT16",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def get_dict(lang, dict_size, reverse=False):
     """
@@ -333,6 +337,7 @@ def get_dict(lang, dict_size, reverse=False):
 @deprecated(
     since="2.0.0",
     update_to="paddle.text.datasets.WMT16",
+    level=1,
     reason="Please use new dataset API which supports paddle.io.DataLoader")
 def fetch():
     """download the entire dataset.

python/paddle/fluid/dygraph/varbase_patch_methods.py

@@ -241,7 +241,8 @@ def monkey_patch_varbase():
     @framework.dygraph_only
     @deprecated(
         since="2.1.0",
-        reason="Please use x.grad, which returns the tensor value of the gradient."
+        level=1,
+        reason="Please use tensor.grad, which returns the tensor value of the gradient."
     )
     def gradient(self):
         """
@@ -367,6 +368,9 @@ def monkey_patch_varbase():
                 # Tensor(shape=[1], dtype=float32, place=CUDAPlace(0), stop_gradient=False, [500.])
 
         """
+        msg = "tensor.grad will return the tensor value of the gradient."
+        warning_msg = "\033[93m\nWarning:\n%s \033[0m" % (msg)
+        warnings.warn(warning_msg)
         return self._grad_ivar()
 
     def clear_grad(self):

python/paddle/fluid/tests/unittests/test_deprecated_decorator.py

@@ -21,6 +21,8 @@ from paddle.static import Program, program_guard
 import unittest
 import paddle.fluid.core as core
 import sys
+import warnings
+import paddle.utils.deprecated as deprecated
 
 LOWEST_WARNING_POSTION = 3
 ERROR_WARNING_POSTION = sys.maxsize
@@ -149,6 +151,45 @@ class TestDeprecatedDocorator(unittest.TestCase):
         # testting
         self.assertGreater(expected, captured)
 
+    def test_tensor_gradient(self):
+        paddle.__version__ = '2.1.0'
+
+        x = paddle.to_tensor(5., stop_gradient=False)
+        y = paddle.pow(x, 4.0)
+        y.backward()
+
+        with warnings.catch_warnings(record=True) as w:
+            grad = x.gradient()
+            assert (
+                'API "paddle.fluid.dygraph.varbase_patch_methods.gradient" is '
+                'deprecated since 2.1.0') in str(w[-1].message)
+
+    def test_softmax_with_cross_entropy(self):
+        paddle.__version__ = '2.0.0'
+
+        data = np.random.rand(128).astype("float32")
+        label = np.random.rand(1).astype("int64")
+        data = paddle.to_tensor(data)
+        label = paddle.to_tensor(label)
+        linear = paddle.nn.Linear(128, 100)
+        x = linear(data)
+
+        with warnings.catch_warnings(record=True) as w:
+            out = paddle.nn.functional.softmax_with_cross_entropy(
+                logits=x, label=label)
+            assert (
+                'API "paddle.nn.functional.loss.softmax_with_cross_entropy" is '
+                'deprecated since 2.0.0') in str(w[-1].message)
+
+    def test_deprecated_error(self):
+        paddle.__version__ = '2.1.0'
+
+        @deprecated(since="2.1.0", level=2)
+        def deprecated_error_func():
+            pass
+
+        self.assertRaises(RuntimeError, deprecated_error_func)
+
 
 if __name__ == '__main__':
     unittest.main()

python/paddle/nn/__init__.py

@@ -146,7 +146,8 @@ import paddle.utils.deprecated as deprecated
 @deprecated(
     since="2.0.0",
     update_to="paddle.nn.funcitional.diag_embed",
-    reason="diag_embed in paddle.nn will removed in future")
+    level=1,
+    reason="diag_embed in paddle.nn will be removed in future")
 def diag_embed(*args):
     '''
         alias name of paddle.nn.functional.diag_embed
@@ -157,7 +158,8 @@ def diag_embed(*args):
 @deprecated(
     since="2.0.0",
     update_to="paddle.nn.utils.remove_weight_norm",
-    reason="remove_weight_norm in paddle.nn will removed in future")
+    level=1,
+    reason="remove_weight_norm in paddle.nn will be removed in future")
 def remove_weight_norm(*args):
     '''
         alias name of paddle.nn.utils.remove_weight_norm
@@ -168,7 +170,8 @@ def remove_weight_norm(*args):
 @deprecated(
     since="2.0.0",
     update_to="paddle.nn.utils.weight_norm",
-    reason="weight_norm in paddle.nn will removed in future")
+    level=1,
+    reason="weight_norm in paddle.nn will be removed in future")
 def weight_norm(*args):
     '''
         alias name of paddle.nn.utils.weight_norm

python/paddle/nn/functional/loss.py

@@ -1096,7 +1096,13 @@ def ctc_loss(log_probs,
     return loss_out
 
 
-@deprecated(since="2.0.0", update_to="paddle.nn.functional.cross_entropy")
+@deprecated(
+    since="2.0.0",
+    update_to="paddle.nn.functional.cross_entropy",
+    level=1,
+    reason=(
+        'Please notice that behavior of "paddle.nn.functional.softmax_with_cross_entropy" '
+        'and "paddle.nn.functional.cross_entropy" is different.'))
 def softmax_with_cross_entropy(logits,
                                label,
                                soft_label=False,

python/paddle/utils/deprecated.py

@@ -30,7 +30,7 @@ __all__ = []
 warnings.simplefilter('default', DeprecationWarning)
 
 
-def deprecated(update_to="", since="", reason=""):
+def deprecated(update_to="", since="", reason="", level=0):
     """Decorate a function to signify its deprecation.
 
        This function wraps a method that will soon be removed and does two things:
@@ -39,9 +39,14 @@ def deprecated(update_to="", since="", reason=""):
            - Raises a :class:`~exceptions.DeprecatedWarning` when old API is called.
 
        Args:
-           since(str): The version at which the decorated method is considered deprecated.
-           update_to(str): The new API users should use.
-           reason(str): The reason why the API is deprecated.
+            since(str, optional): The version at which the decorated method is considered deprecated.
+            update_to(str, optional): The new API users should use.
+            reason(str, optional): The reason why the API is deprecated.
+            level(int, optional): The deprecated warning log level. It must be 
+                an Integer and must be one of 0, 1, 2. 
+                If `level == 0`, the warning message will not be showed. 
+                If `level == 1`, the warning message will be showed normally.
+                If `level == 2`, it will raise `RuntimeError`.
            
        Returns:
            decorator: decorated function or class.
@@ -54,6 +59,9 @@ def deprecated(update_to="", since="", reason=""):
         assert isinstance(update_to, str), 'type of "update_to" must be str.'
         assert isinstance(since, str), 'type of "since" must be str.'
         assert isinstance(reason, str), 'type of "reason" must be str.'
+        assert isinstance(level, int) and level >= 0 and level < 3, (
+            'type of "level" must be int and must be one of 0, 1, 2. But '
+            'received: {}.'.format(level))
 
         _since = since.strip()
         _update_to = update_to.strip()
@@ -71,12 +79,12 @@ def deprecated(update_to="", since="", reason=""):
                 update_to)
             msg += ' Please use "{}" instead.'.format(_update_to)
         if len(_reason) > 0:
-            msg += "\n reason: {}".format(_reason)
+            msg += "\nreason: {}".format(_reason)
         if func.__doc__:
             func.__doc__ = ('\n\nWarning: ' + msg + '\n') + func.__doc__
-        # TODO(Joejiong) Early returning the wrapper function, currently we disable the warning wrapper, 
-        # because the 2.0beta APIs are still under development, we will restore the warning functionality when 2.0 rc APIs become stable.
-        return func
+
+        if level == 0:
+            return func
 
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
@@ -85,7 +93,12 @@ def deprecated(update_to="", since="", reason=""):
                2. since version is empty, in this case, API is deprecated in all versions.
                3. current version is newer than since version.
             """
-            warningmsg = "\033[93mWarning %s \033[0m" % (msg)
+
+            if level == 2:
+                raise RuntimeError('API "{}.{}" has been deprecated.'.format(
+                    func.__module__, func.__name__))
+
+            warningmsg = "\033[93m\nWarning:\n%s \033[0m" % (msg)
             v_current = [int(i) for i in paddle.__version__.split(".")]
             v_current += [0] * (4 - len(v_current))
             v_since = [int(i) for i in _since.split(".")]