Add @deprecate_func and @deprecate_arg decorators (Qiskit#9676)

* Add `@deprecate_func` and `@deprecate_arg` decorators

* Update the release note

* Apply suggestions from code review

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

* lint

* Use PyPI package_name rather than loose English

---------

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

qiskit/utils/__init__.py

@@ -21,7 +21,10 @@
 .. autosummary::
    :toctree: ../stubs/
 
+   add_deprecation_to_docstring
+   deprecate_arg
    deprecate_arguments
+   deprecate_func
    deprecate_function
    local_hardware_info
    is_main_process
@@ -64,8 +67,13 @@
 """
 
 from .quantum_instance import QuantumInstance
-from .deprecation import deprecate_arguments
-from .deprecation import deprecate_function
+from .deprecation import (
+    add_deprecation_to_docstring,
+    deprecate_arg,
+    deprecate_arguments,
+    deprecate_func,
+    deprecate_function,
+)
 from .multiprocessing import local_hardware_info
 from .multiprocessing import is_main_process
 from .units import apply_prefix, detach_prefix
@@ -93,7 +101,10 @@
     "has_aer",
     "name_args",
     "algorithm_globals",
+    "add_deprecation_to_docstring",
+    "deprecate_arg",
     "deprecate_arguments",
+    "deprecate_func",
     "deprecate_function",
     "local_hardware_info",
     "is_main_process",

qiskit/utils/deprecation.py

@@ -14,7 +14,173 @@
 
 import functools
 import warnings
-from typing import Any, Callable, Dict, Optional, Type
+from typing import Any, Callable, Dict, Optional, Type, Tuple, Union
+
+
+def deprecate_func(
+    *,
+    since: str,
+    additional_msg: Optional[str] = None,
+    pending: bool = False,
+    package_name: str = "qiskit-terra",
+    removal_timeline: str = "no earlier than 3 months after the release date",
+    is_property: bool = False,
+):
+    """Decorator to indicate a function has been deprecated.
+
+    It should be placed beneath other decorators like `@staticmethod` and property decorators.
+
+    When deprecating a class, set this decorator on its `__init__` function.
+
+    Args:
+        since: The version the deprecation started at. If the deprecation is pending, set
+            the version to when that started; but later, when switching from pending to
+            deprecated, update ``since`` to the new version.
+        additional_msg: Put here any additional information, such as what to use instead.
+            For example, "Instead, use the function ``new_func`` from the module
+            ``<my_module>.<my_submodule>``, which is similar but uses GPU acceleration."
+        pending: Set to ``True`` if the deprecation is still pending.
+        package_name: The PyPI package name, e.g. "qiskit-nature".
+        removal_timeline: How soon can this deprecation be removed? Expects a value
+            like "no sooner than 6 months after the latest release" or "in release 9.99".
+        is_property: If the deprecated function is a `@property`, set this to True so that the
+            generated message correctly describes it as such. (This isn't necessary for
+            property setters, as their docstring is ignored by Python.)
+
+    Returns:
+        Callable: The decorated callable.
+    """
+
+    def decorator(func):
+        qualname = func.__qualname__  # For methods, `qualname` includes the class name.
+        mod_name = func.__module__
+
+        # Detect what function type this is.
+        if is_property:
+            # `inspect.isdatadescriptor()` doesn't work because you must apply our decorator
+            # before `@property`, so it looks like the function is a normal method.
+            deprecated_entity = f"The property ``{mod_name}.{qualname}``"
+        # To determine if's a method, we use the heuristic of looking for a `.` in the qualname.
+        # This is because top-level functions will only have the function name. This is not
+        # perfect, e.g. it incorrectly classifies nested/inner functions, but we don't expect
+        # those to be deprecated.
+        #
+        # We can't use `inspect.ismethod()` because that only works when calling it on an instance
+        # of the class, rather than the class type itself, i.e. `ismethod(C().foo)` vs
+        # `ismethod(C.foo)`.
+        elif "." in qualname:
+            if func.__name__ == "__init__":
+                cls_name = qualname[: -len(".__init__")]
+                deprecated_entity = f"The class ``{mod_name}.{cls_name}``"
+            else:
+                deprecated_entity = f"The method ``{mod_name}.{qualname}()``"
+        else:
+            deprecated_entity = f"The function ``{mod_name}.{qualname}()``"
+
+        msg, category = _write_deprecation_msg(
+            deprecated_entity=deprecated_entity,
+            package_name=package_name,
+            since=since,
+            pending=pending,
+            additional_msg=additional_msg,
+            removal_timeline=removal_timeline,
+        )
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(msg, category=category, stacklevel=2)
+            return func(*args, **kwargs)
+
+        add_deprecation_to_docstring(wrapper, msg, since=since, pending=pending)
+        return wrapper
+
+    return decorator
+
+
+def deprecate_arg(
+    name: str,
+    *,
+    since: str,
+    additional_msg: Optional[str] = None,
+    deprecation_description: Optional[str] = None,
+    pending: bool = False,
+    package_name: str = "qiskit-terra",
+    new_alias: Optional[str] = None,
+    predicate: Optional[Callable[[Any], bool]] = None,
+    removal_timeline: str = "no earlier than 3 months after the release date",
+):
+    """Decorator to indicate an argument has been deprecated in some way.
+
+    This decorator may be used multiple times on the same function, once per deprecated argument.
+    It should be placed beneath other decorators like ``@staticmethod`` and property decorators.
+
+    Args:
+        name: The name of the deprecated argument.
+        since: The version the deprecation started at. If the deprecation is pending, set
+            the version to when that started; but later, when switching from pending to
+            deprecated, update `since` to the new version.
+        deprecation_description: What is being deprecated? E.g. "Setting my_func()'s `my_arg`
+            argument to `None`." If not set, will default to "{func_name}'s argument `{name}`".
+        additional_msg: Put here any additional information, such as what to use instead
+            (if new_alias is not set). For example, "Instead, use the argument `new_arg`,
+            which is similar but does not impact the circuit's setup."
+        pending: Set to `True` if the deprecation is still pending.
+        package_name: The PyPI package name, e.g. "qiskit-nature".
+        new_alias: If the arg has simply been renamed, set this to the new name. The decorator will
+            dynamically update the `kwargs` so that when the user sets the old arg, it will be
+            passed in as the `new_alias` arg.
+        predicate: Only log the runtime warning if the predicate returns True. This is useful to
+            deprecate certain values or types for an argument, e.g.
+            `lambda my_arg: isinstance(my_arg, dict)`. Regardless of if a predicate is set, the
+            runtime warning will only log when the user specifies the argument.
+        removal_timeline: How soon can this deprecation be removed? Expects a value
+            like "no sooner than 6 months after the latest release" or "in release 9.99".
+
+    Returns:
+        Callable: The decorated callable.
+    """
+
+    def decorator(func):
+        # For methods, `__qualname__` includes the class name.
+        func_name = f"{func.__module__}.{func.__qualname__}()"
+        deprecated_entity = deprecation_description or f"``{func_name}``'s argument ``{name}``"
+
+        if new_alias:
+            alias_msg = f"Instead, use the argument ``{new_alias}``, which behaves identically."
+            if additional_msg:
+                final_additional_msg = f"{alias_msg}. {additional_msg}"
+            else:
+                final_additional_msg = alias_msg
+        else:
+            final_additional_msg = additional_msg
+
+        msg, category = _write_deprecation_msg(
+            deprecated_entity=deprecated_entity,
+            package_name=package_name,
+            since=since,
+            pending=pending,
+            additional_msg=final_additional_msg,
+            removal_timeline=removal_timeline,
+        )
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if kwargs:
+                _maybe_warn_and_rename_kwarg(
+                    func_name,
+                    kwargs,
+                    old_arg=name,
+                    new_alias=new_alias,
+                    warning_msg=msg,
+                    category=category,
+                    predicate=predicate,
+                )
+            return func(*args, **kwargs)
+
+        add_deprecation_to_docstring(wrapper, msg, since=since, pending=pending)
+        return wrapper
+
+    return decorator
 
 
 def deprecate_arguments(
@@ -23,7 +189,7 @@ def deprecate_arguments(
     *,
     since: Optional[str] = None,
 ):
-    """Decorator to automatically alias deprecated argument names and warn upon use.
+    """Deprecated. Instead, use `@deprecate_arg`.
 
     Args:
         kwarg_map: A dictionary of the old argument name to the new name.
@@ -51,7 +217,16 @@ def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             if kwargs:
-                _rename_kwargs(func_name, kwargs, old_kwarg_to_msg, kwarg_map, category)
+                for old, new in kwarg_map.items():
+                    _maybe_warn_and_rename_kwarg(
+                        func_name,
+                        kwargs,
+                        old_arg=old,
+                        new_alias=new,
+                        warning_msg=old_kwarg_to_msg[old],
+                        category=category,
+                        predicate=None,
+                    )
             return func(*args, **kwargs)
 
         for msg in old_kwarg_to_msg.values():
@@ -70,7 +245,7 @@ def deprecate_function(
     *,
     since: Optional[str] = None,
 ):
-    """Emit a warning prior to calling decorated function.
+    """Deprecated. Instead, use `@deprecate_func`.
 
     Args:
         msg: Warning message to emit.
@@ -99,21 +274,52 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def _rename_kwargs(
+def _maybe_warn_and_rename_kwarg(
     func_name: str,
     kwargs: Dict[str, Any],
-    old_kwarg_to_msg: Dict[str, str],
-    kwarg_map: Dict[str, Optional[str]],
-    category: Type[Warning] = DeprecationWarning,
+    *,
+    old_arg: str,
+    new_alias: Optional[str],
+    warning_msg: str,
+    category: Type[Warning],
+    predicate: Optional[Callable[[Any], bool]],
 ) -> None:
-    for old_arg, new_arg in kwarg_map.items():
-        if old_arg not in kwargs:
-            continue
-        if new_arg in kwargs:
-            raise TypeError(f"{func_name} received both {new_arg} and {old_arg} (deprecated).")
-        warnings.warn(old_kwarg_to_msg[old_arg], category=category, stacklevel=3)
-        if new_arg is not None:
-            kwargs[new_arg] = kwargs.pop(old_arg)
+    if old_arg not in kwargs:
+        return
+    if new_alias and new_alias in kwargs:
+        raise TypeError(f"{func_name} received both {new_alias} and {old_arg} (deprecated).")
+    if predicate and not predicate(kwargs[old_arg]):
+        return
+    warnings.warn(warning_msg, category=category, stacklevel=3)
+    if new_alias is not None:
+        kwargs[new_alias] = kwargs.pop(old_arg)
+
+
+def _write_deprecation_msg(
+    *,
+    deprecated_entity: str,
+    package_name: str,
+    since: str,
+    pending: bool,
+    additional_msg: str,
+    removal_timeline: str,
+) -> Tuple[str, Union[Type[DeprecationWarning], Type[PendingDeprecationWarning]]]:
+    if pending:
+        category = PendingDeprecationWarning
+        deprecation_status = "pending deprecation"
+        removal_desc = f"marked deprecated in a future release, and then removed {removal_timeline}"
+    else:
+        category = DeprecationWarning
+        deprecation_status = "deprecated"
+        removal_desc = f"removed {removal_timeline}"
+
+    msg = (
+        f"{deprecated_entity} is {deprecation_status} as of {package_name} {since}. "
+        f"It will be {removal_desc}."
+    )
+    if additional_msg:
+        msg += f" {additional_msg}"
+    return msg, category
 
 
 # We insert deprecations in-between the description and Napoleon's meta sections. The below is from

releasenotes/notes/new-deprecation-utilities-066aff05e221d7b1.yaml

@@ -1,8 +1,18 @@
 ---
 features:
   - |
-    Added the function ``qiskit.util.deprecation.add_deprecation_to_docstring()``.
-    It will rewrite the function's docstring to include a Sphinx ``.. deprecated::` directive
-    so that the deprecation shows up in docs and with ``help()``. The deprecation decorators
-    from ``qiskit.util.deprecation`` call ``add_deprecation_to_docstring()`` already for you;
-    but you can call it directly if you are using different mechanisms for deprecations.
+    Added the functions ``add_deprecation_to_docstring()``, ``@deprecate_arg``, and
+    ``@deprecate_func`` to ``qiskit.util.deprecation``.
+
+    ``add_deprecation_to_docstring()`` will rewrite the function's docstring to include a
+    Sphinx ``.. deprecated::`` directive so that the deprecation shows up in docs and with
+    ``help()``. The deprecation decorators from ``qiskit.util.deprecation`` call
+    ``add_deprecation_to_docstring()`` already for you; but you can call it directly if you
+    are using different mechanisms for deprecations.
+
+    ``@deprecate_func`` replaces ``@deprecate_function``. It will auto-generate most of the
+    deprecation message for you.
+
+    ``@deprecate_arg`` replaces ``@deprecate_arguments``. It will generate a more useful message
+    than before. It is also more flexible, like allowing you to set a ``predicate`` so that you
+    only deprecate certain situations, such as using a deprecated value or data type.