box

qiskit/utils/deprecation.py

@@ -16,15 +16,15 @@
 import warnings
 
 
-def deprecate_arguments(kwarg_map, docstring_warning=False):
+def deprecate_arguments(kwarg_map, docstring_version=None):
     """Decorator to automatically alias deprecated argument names and warn upon use."""
 
     def decorator(func):
-        if docstring_warning and kwarg_map:
+        if docstring_version and kwarg_map:
             msg = ["One or more keyword argument are being deprecated:", ""]
             for old_arg, new_arg in kwarg_map.items():
                 msg.append("* The argument {} is being replaced with {}".format(old_arg, new_arg))
-            _extend_docstring(func, msg)
+            _extend_docstring(func, msg, docstring_version)
 
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
@@ -37,22 +37,22 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def deprecate_function(msg, stacklevel=2, docstring_warning=False):
+def deprecate_function(msg, stacklevel=2, docstring_version="0.0.1"):
     """Emit a warning prior to calling decorated function.
 
     Args:
         msg (str): Warning message to emit.
         stacklevel (int): The warning stackevel to use, defaults to 2.
-        docstring_warning (bool): If `True`, extends the docstring with a warning
-           box. Default: True
+        docstring_version (str): If a version number, extends the docstring with a deprecation warning
+           box. Default: None
 
     Returns:
         Callable: The decorated, deprecated callable.
     """
 
     def decorator(func):
-        if docstring_warning:
-            _extend_docstring(func, msg.expandtabs().splitlines())
+        if docstring_version:
+            _extend_docstring(func, msg.expandtabs().splitlines(), docstring_version)
 
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
@@ -80,7 +80,7 @@ def _rename_kwargs(func_name, kwargs, kwarg_map):
             kwargs[new_arg] = kwargs.pop(old_arg)
 
 
-def _extend_docstring(func, msg_lines):
+def _extend_docstring(func, msg_lines, version):
     docstr = func.__doc__
     if docstr:
         docstr_lines = docstr.expandtabs().splitlines()
@@ -94,7 +94,7 @@ def _extend_docstring(func, msg_lines):
     spaces = ""
     if indent != 1000:
         spaces = " " * indent
-    new_doc_str_lines = [docstr_lines[0], spaces + ".. warning::"]
+    new_doc_str_lines = [docstr_lines[0], spaces + f".. deprecated:: {version}"]
     for msg_line in msg_lines:
         new_doc_str_lines.append(spaces + msg_line)
     func.__doc__ = "\n".join(new_doc_str_lines)