From 51b39a94e436d5c09b26efce38da81391c184e46 Mon Sep 17 00:00:00 2001
From: xiemoyuan <71377852+xiemoyuan@users.noreply.github.com>
Date: Thu, 6 May 2021 19:14:47 +0800
Subject: [PATCH] [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                |  5 +++
 python/paddle/dataset/conll05.py              |  4 ++
 python/paddle/dataset/flowers.py              |  3 ++
 python/paddle/dataset/imdb.py                 |  5 +++
 python/paddle/dataset/imikolov.py             |  3 ++
 python/paddle/dataset/mnist.py                |  3 ++
 python/paddle/dataset/movielens.py            |  9 ++++
 python/paddle/dataset/uci_housing.py          |  4 ++
 python/paddle/dataset/voc2012.py              |  3 ++
 python/paddle/dataset/wmt14.py                |  5 +++
 python/paddle/dataset/wmt16.py                |  5 +++
 .../fluid/dygraph/varbase_patch_methods.py    |  6 ++-
 .../unittests/test_deprecated_decorator.py    | 41 +++++++++++++++++++
 python/paddle/nn/__init__.py                  |  9 ++--
 python/paddle/nn/functional/loss.py           |  8 +++-
 python/paddle/utils/deprecated.py             | 31 ++++++++++----
 16 files changed, 130 insertions(+), 14 deletions(-)

diff --git a/python/paddle/dataset/cifar.py b/python/paddle/dataset/cifar.py
index e3d239e2cdf..9a9f9018e42 100644
--- a/python/paddle/dataset/cifar.py
+++ b/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)
diff --git a/python/paddle/dataset/conll05.py b/python/paddle/dataset/conll05.py
index 65cf04f05b7..f09163ea424 100644
--- a/python/paddle/dataset/conll05.py
+++ b/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)
diff --git a/python/paddle/dataset/flowers.py b/python/paddle/dataset/flowers.py
index 3b437a1f074..2f38c563136 100644
--- a/python/paddle/dataset/flowers.py
+++ b/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):
     '''
diff --git a/python/paddle/dataset/imdb.py b/python/paddle/dataset/imdb.py
index 9a6c8e837ed..961d238b0ad 100644
--- a/python/paddle/dataset/imdb.py
+++ b/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)
diff --git a/python/paddle/dataset/imikolov.py b/python/paddle/dataset/imikolov.py
index 7a4efe27aa9..85fe011fa14 100644
--- a/python/paddle/dataset/imikolov.py
+++ b/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)
diff --git a/python/paddle/dataset/mnist.py b/python/paddle/dataset/mnist.py
index e4f724bd66d..02cdd307083 100644
--- a/python/paddle/dataset/mnist.py
+++ b/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)
diff --git a/python/paddle/dataset/movielens.py b/python/paddle/dataset/movielens.py
index 862ac586bc9..9af06e088ca 100644
--- a/python/paddle/dataset/movielens.py
+++ b/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)
diff --git a/python/paddle/dataset/uci_housing.py b/python/paddle/dataset/uci_housing.py
index 0ac65f0fda4..dea2dfc8c98 100644
--- a/python/paddle/dataset/uci_housing.py
+++ b/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)
diff --git a/python/paddle/dataset/voc2012.py b/python/paddle/dataset/voc2012.py
index 5784e739b41..1ab91db2cc3 100644
--- a/python/paddle/dataset/voc2012.py
+++ b/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():
     """
diff --git a/python/paddle/dataset/wmt14.py b/python/paddle/dataset/wmt14.py
index c842ceaa091..9f8abb2c4bf 100644
--- a/python/paddle/dataset/wmt14.py
+++ b/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)
diff --git a/python/paddle/dataset/wmt16.py b/python/paddle/dataset/wmt16.py
index 320ef139f77..f313da98f0a 100644
--- a/python/paddle/dataset/wmt16.py
+++ b/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.
diff --git a/python/paddle/fluid/dygraph/varbase_patch_methods.py b/python/paddle/fluid/dygraph/varbase_patch_methods.py
index bb84b2ca970..37900b7880a 100644
--- a/python/paddle/fluid/dygraph/varbase_patch_methods.py
+++ b/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):
diff --git a/python/paddle/fluid/tests/unittests/test_deprecated_decorator.py b/python/paddle/fluid/tests/unittests/test_deprecated_decorator.py
index 97b6594eb38..7dc5dc70618 100755
--- a/python/paddle/fluid/tests/unittests/test_deprecated_decorator.py
+++ b/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()
diff --git a/python/paddle/nn/__init__.py b/python/paddle/nn/__init__.py
index 2a824898b82..c4f4b6cbc1f 100644
--- a/python/paddle/nn/__init__.py
+++ b/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
diff --git a/python/paddle/nn/functional/loss.py b/python/paddle/nn/functional/loss.py
index b89da3d82e3..aa0bd8a8c5e 100755
--- a/python/paddle/nn/functional/loss.py
+++ b/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,
diff --git a/python/paddle/utils/deprecated.py b/python/paddle/utils/deprecated.py
index 5390dea69fe..e3839d9767d 100755
--- a/python/paddle/utils/deprecated.py
+++ b/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(".")]
-- 
GitLab