[wip] Better handle pending deprecations

qiskit/algorithms/amplitude_amplifiers/grover.py

@@ -195,7 +195,7 @@ def __init__(
         "The Grover.quantum_instance getter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self) -> Optional[QuantumInstance]:
         r"""Pending deprecation\; Get the quantum instance.
@@ -210,7 +210,7 @@ def quantum_instance(self) -> Optional[QuantumInstance]:
         "The Grover.quantum_instance setter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self, quantum_instance: Union[QuantumInstance, Backend]) -> None:
         r"""Pending deprecation\; Set quantum instance.

qiskit/algorithms/amplitude_estimators/ae.py

@@ -128,7 +128,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "The AmplitudeEstimation.quantum_instance getter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -143,7 +143,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "The AmplitudeEstimation.quantum_instance setter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/fae.py

@@ -113,7 +113,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "The FasterAmplitudeEstimation.quantum_instance getter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -128,7 +128,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "The FasterAmplitudeEstimation.quantum_instance setter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/iae.py

@@ -136,7 +136,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "The IterativeAmplitudeEstimation.quantum_instance getter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -151,7 +151,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "The IterativeAmplitudeEstimation.quantum_instance setter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/mlae.py

@@ -140,7 +140,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "The MaximumLikelihoodAmplitudeEstimation.quantum_instance getter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -155,7 +155,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "The MaximumLikelihoodAmplitudeEstimation.quantum_instance setter is pending deprecation. "
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/aux_ops_evaluator.py

@@ -36,7 +36,7 @@
     "qiskit.algorithms.observables_evaluator.estimate_observables function. "
     "This function will be deprecated in a future release and subsequently "
     "removed after that.",
-    category=PendingDeprecationWarning,
+    pending=True,
 )
 def eval_observables(
     quantum_instance: Union[QuantumInstance, Backend],

qiskit/algorithms/eigen_solvers/eigen_solver.py

@@ -41,7 +41,7 @@ class Eigensolver(ABC):
         "qiskit.algorithms.eigensolvers.Eigensolver interface. "
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         pass
@@ -93,7 +93,7 @@ class EigensolverResult(AlgorithmResult):
         "qiskit.algorithms.eigensolvers.EigensolverResult class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/eigen_solvers/numpy_eigen_solver.py

@@ -54,7 +54,7 @@ class NumPyEigensolver(Eigensolver):
         "qiskit.algorithms.eigensolvers.NumPyEigensolver class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/eigen_solvers/vqd.py

@@ -101,7 +101,7 @@ class VQD(VariationalAlgorithm, Eigensolver):
         "qiskit.algorithms.eigensolvers.VQD class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,
@@ -771,7 +771,7 @@ class VQDResult(VariationalResult, EigensolverResult):
         "qiskit.algorithms.eigensolvers.VQDResult class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/evolvers/evolution_problem.py

@@ -38,7 +38,7 @@ class EvolutionProblem:
         "qiskit.algorithms.time_evolvers.TimeEvolutionProblem class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/evolvers/evolution_result.py

@@ -36,7 +36,7 @@ class EvolutionResult(AlgorithmResult):
         "qiskit.algorithms.time_evolvers.TimeEvolutionResult class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/evolvers/imaginary_evolver.py

@@ -34,7 +34,7 @@ class ImaginaryEvolver(ABC):
         "qiskit.algorithms.time_evolvers.ImaginaryTimeEvolver interface. "
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/evolvers/real_evolver.py

@@ -34,7 +34,7 @@ class RealEvolver(ABC):
         "qiskit.algorithms.time_evolvers.RealTimeEvolver interface. "
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/evolvers/trotterization/trotter_qrte.py

@@ -69,7 +69,7 @@ class TrotterQRTE(RealEvolver):
         "qiskit.algorithms.time_evolvers.trotterization.TrotterQRTE class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/minimum_eigen_solvers/minimum_eigen_solver.py

@@ -41,7 +41,7 @@ class MinimumEigensolver(ABC):
         "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolver interface. "
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         pass
@@ -97,7 +97,7 @@ class MinimumEigensolverResult(AlgorithmResult):
         "qiskit.algorithms.minimum_eigensolvers.MinimumEigensolverResult class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/minimum_eigen_solvers/numpy_minimum_eigen_solver.py

@@ -42,7 +42,7 @@ class NumPyMinimumEigensolver(MinimumEigensolver):
         "qiskit.algorithms.minimum_eigensolvers.NumPyMinimumEigensolver class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/minimum_eigen_solvers/qaoa.py

@@ -64,7 +64,7 @@ class QAOA(VQE):
         "qiskit.algorithms.minimum_eigensolvers.QAOA class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,

qiskit/algorithms/minimum_eigen_solvers/vqe.py

@@ -132,7 +132,7 @@ def my_minimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult:
         "qiskit.algorithms.minimum_eigensolvers.VQE class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(
         self,
@@ -671,7 +671,7 @@ class VQEResult(VariationalResult, MinimumEigensolverResult):
         "qiskit.algorithms.minimum_eigensolvers.VQEResult class. "
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
-        category=PendingDeprecationWarning,
+        pending=True,
     )
     def __init__(self) -> None:
         with warnings.catch_warnings():

qiskit/utils/deprecation.py

@@ -14,31 +14,31 @@
 
 import functools
 import warnings
-from typing import Type
+from typing import Any, Dict, Optional, Type
 
 
-def deprecate_arguments(kwarg_map, category: Type[Warning] = DeprecationWarning):
+def deprecate_arguments(kwarg_map: Dict[str, Optional[str]], *, pending: bool = False):
     """Decorator to automatically alias deprecated argument names and warn upon use."""
 
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             if kwargs:
-                _rename_kwargs(func.__name__, kwargs, kwarg_map, category)
+                _rename_kwargs(func.__name__, kwargs, kwarg_map, pending=pending)
             return func(*args, **kwargs)
 
         return wrapper
 
     return decorator
 
 
-def deprecate_function(msg: str, stacklevel: int = 2, category: Type[Warning] = DeprecationWarning):
+def deprecate_function(msg: str, *, stacklevel: int = 2, pending: bool = False):
     """Emit a warning prior to calling decorated function.
 
     Args:
         msg: Warning message to emit.
-        stacklevel: The warning stackevel to use, defaults to 2.
-        category: warning category, defaults to DeprecationWarning
+        stacklevel: The warning stacklevel to use, defaults to 2.
+        pending: if True, use PendingDeprecationWarning rather than DeprecationWarning
 
     Returns:
         Callable: The decorated, deprecated callable.
@@ -47,30 +47,45 @@ def deprecate_function(msg: str, stacklevel: int = 2, category: Type[Warning] =
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
-            warnings.warn(msg, category=category, stacklevel=stacklevel)
+            warnings.warn(
+                msg,
+                category=PendingDeprecationWarning if pending else DeprecationWarning,
+                stacklevel=stacklevel,
+            )
             return func(*args, **kwargs)
 
         return wrapper
 
     return decorator
 
 
-def _rename_kwargs(func_name, kwargs, kwarg_map, category: Type[Warning] = DeprecationWarning):
+def _rename_kwargs(
+    func_name: str,
+    kwargs: Dict[str, Any],
+    kwarg_map: Dict[str, Optional[str]],
+    pending: bool,
+) -> None:
+    if pending:
+        category = PendingDeprecationWarning
+        deprecation_desc = "pending deprecation"
+    else:
+        category = DeprecationWarning
+        deprecation_desc = "deprecated"
     for old_arg, new_arg in kwarg_map.items():
         if old_arg in kwargs:
             if new_arg in kwargs:
                 raise TypeError(f"{func_name} received both {new_arg} and {old_arg} (deprecated).")
 
             if new_arg is None:
                 warnings.warn(
-                    f"{func_name} keyword argument {old_arg} is deprecated and "
-                    "will in future be removed.",
+                    f"{func_name}'s keyword argument {old_arg} is {deprecation_desc} and "
+                    "will in the future be removed.",
                     category=category,
                     stacklevel=3,
                 )
             else:
                 warnings.warn(
-                    f"{func_name} keyword argument {old_arg} is deprecated and "
+                    f"{func_name}'s keyword argument {old_arg} is {deprecation_desc} and "
                     f"replaced with {new_arg}.",
                     category=category,
                     stacklevel=3,