Add since argument to deprecation functions (#9616)

* Add `since` argument to deprecation functions

Co-authored-by: Luciano Bello <lbello@gmail.com>

* Pending deprecations set version to when the deprecation will become official

* Review feedback to `del` since argument

* Revert "Pending deprecations set version to when the deprecation will become official"

This reverts commit dc30bba.

* Clarify how to handle pending deprecations

---------

Co-authored-by: Luciano Bello <lbello@gmail.com>

qiskit/algorithms/amplitude_amplifiers/grover.py

@@ -196,6 +196,7 @@ def __init__(
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self) -> Optional[QuantumInstance]:
         r"""Pending deprecation\; Get the quantum instance.
@@ -211,6 +212,7 @@ def quantum_instance(self) -> Optional[QuantumInstance]:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self, quantum_instance: Union[QuantumInstance, Backend]) -> None:
         r"""Pending deprecation\; Set quantum instance.

qiskit/algorithms/amplitude_estimators/ae.py

@@ -129,6 +129,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -144,6 +145,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/fae.py

@@ -114,6 +114,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -129,6 +130,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/iae.py

@@ -137,6 +137,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -152,6 +153,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/amplitude_estimators/mlae.py

@@ -141,6 +141,7 @@ def sampler(self, sampler: BaseSampler) -> None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self) -> QuantumInstance | None:
         """Pending deprecation; Get the quantum instance.
@@ -156,6 +157,7 @@ def quantum_instance(self) -> QuantumInstance | None:
         "This property will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def quantum_instance(self, quantum_instance: QuantumInstance | Backend) -> None:
         """Pending deprecation; Set quantum instance.

qiskit/algorithms/aux_ops_evaluator.py

@@ -37,6 +37,7 @@
     "This function will be deprecated in a future release and subsequently "
     "removed after that.",
     category=PendingDeprecationWarning,
+    since="0.23.0",
 )
 def eval_observables(
     quantum_instance: Union[QuantumInstance, Backend],

qiskit/algorithms/eigen_solvers/eigen_solver.py

@@ -42,6 +42,7 @@ class Eigensolver(ABC):
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         pass
@@ -94,6 +95,7 @@ class EigensolverResult(AlgorithmResult):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/eigen_solvers/numpy_eigen_solver.py

@@ -55,6 +55,7 @@ class NumPyEigensolver(Eigensolver):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/eigen_solvers/vqd.py

@@ -102,6 +102,7 @@ class VQD(VariationalAlgorithm, Eigensolver):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,
@@ -772,6 +773,7 @@ class VQDResult(VariationalResult, EigensolverResult):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/evolvers/evolution_problem.py

@@ -39,6 +39,7 @@ class EvolutionProblem:
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/evolvers/evolution_result.py

@@ -37,6 +37,7 @@ class EvolutionResult(AlgorithmResult):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/evolvers/imaginary_evolver.py

@@ -35,6 +35,7 @@ class ImaginaryEvolver(ABC):
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/evolvers/real_evolver.py

@@ -35,6 +35,7 @@ class RealEvolver(ABC):
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/evolvers/trotterization/trotter_qrte.py

@@ -70,6 +70,7 @@ class TrotterQRTE(RealEvolver):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/factorizers/shor.py

@@ -60,7 +60,8 @@ class Shor:
         """The Shor class is deprecated as of Qiskit Terra 0.22.0 and will be removed
         no sooner than 3 months after the release date.
         It is replaced by the tutorial at https://qiskit.org/textbook/ch-algorithms/shor.html
-        """
+        """,
+        since="0.22.0",
     )
     def __init__(self, quantum_instance: Optional[Union[QuantumInstance, Backend]] = None) -> None:
         """

qiskit/algorithms/linear_solvers/hhl.py

@@ -110,7 +110,8 @@ class HHL(LinearSolver):
         """The HHL class is deprecated as of Qiskit Terra 0.22.0 and will be removed
         no sooner than 3 months after the release date.
         It is replaced by the tutorial at https://qiskit.org/textbook/ch-applications/hhl_tutorial.html"
-        """
+        """,
+        since="0.22.0",
     )
     def __init__(
         self,

qiskit/algorithms/linear_solvers/linear_solver.py

@@ -34,7 +34,8 @@ class LinearSolverResult(AlgorithmResult):
 
     @deprecate_function(
         "The LinearSolverResult class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(self) -> None:
         super().__init__()
@@ -102,7 +103,8 @@ class LinearSolver(ABC):
 
     @deprecate_function(
         "The LinearSolver class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/linear_solvers/matrices/linear_system_matrix.py

@@ -25,7 +25,8 @@ class LinearSystemMatrix(BlueprintCircuit, ABC):
 
     @deprecate_function(
         "The LinearSystemMatrix class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(
         self,

qiskit/algorithms/linear_solvers/matrices/numpy_matrix.py

@@ -48,7 +48,8 @@ class NumPyMatrix(LinearSystemMatrix):
 
     @deprecate_function(
         "The NumPyMatrix class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(
         self,

qiskit/algorithms/linear_solvers/matrices/tridiagonal_toeplitz.py

@@ -60,7 +60,8 @@ class TridiagonalToeplitz(LinearSystemMatrix):
 
     @deprecate_function(
         "The TridiagonalToeplitz class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(
         self,

qiskit/algorithms/linear_solvers/numpy_linear_solver.py

@@ -53,7 +53,8 @@ class NumPyLinearSolver(LinearSolver):
 
     @deprecate_function(
         "The NumPyLinearSolver class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date. ",
+        since="0.22.0",
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/linear_solvers/observables/absolute_average.py

@@ -63,7 +63,8 @@ class AbsoluteAverage(LinearSystemObservable):
 
     @deprecate_function(
         "The AbsoluteAverage class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/linear_solvers/observables/linear_system_observable.py

@@ -26,7 +26,8 @@ class LinearSystemObservable(ABC):
 
     @deprecate_function(
         "The LinearSystemObservable class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(self) -> None:
         pass

qiskit/algorithms/linear_solvers/observables/matrix_functional.py

@@ -75,7 +75,8 @@ class MatrixFunctional(LinearSystemObservable):
 
     @deprecate_function(
         "The MatrixFunctional class is deprecated as of Qiskit Terra 0.22.0 "
-        "and will be removed no sooner than 3 months after the release date. "
+        "and will be removed no sooner than 3 months after the release date.",
+        since="0.22.0",
     )
     def __init__(self, main_diag: float, off_diag: int) -> None:
         """

qiskit/algorithms/minimum_eigen_solvers/minimum_eigen_solver.py

@@ -42,6 +42,7 @@ class MinimumEigensolver(ABC):
         "This interface will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         pass
@@ -98,6 +99,7 @@ class MinimumEigensolverResult(AlgorithmResult):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         super().__init__()

qiskit/algorithms/minimum_eigen_solvers/numpy_minimum_eigen_solver.py

@@ -43,6 +43,7 @@ class NumPyMinimumEigensolver(MinimumEigensolver):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/minimum_eigen_solvers/qaoa.py

@@ -65,6 +65,7 @@ class QAOA(VQE):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,

qiskit/algorithms/minimum_eigen_solvers/vqe.py

@@ -133,6 +133,7 @@ def my_minimizer(fun, x0, jac=None, bounds=None) -> OptimizerResult:
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(
         self,
@@ -672,6 +673,7 @@ class VQEResult(VariationalResult, MinimumEigensolverResult):
         "This class will be deprecated in a future release and subsequently "
         "removed after that.",
         category=PendingDeprecationWarning,
+        since="0.23.0",
     )
     def __init__(self) -> None:
         with warnings.catch_warnings():

qiskit/algorithms/optimizers/adam_amsgrad.py

@@ -198,7 +198,8 @@ def load_params(self, load_dir: str) -> None:
             "objective_function": "fun",
             "initial_point": "x0",
             "gradient_function": "jac",
-        }
+        },
+        since="0.19.0",
     )
     # pylint: disable=arguments-differ
     def minimize(

qiskit/algorithms/optimizers/spsa.py

@@ -651,7 +651,8 @@ def get_support_level(self):
         "The SPSA.optimize method is deprecated as of Qiskit Terra 0.21.0 and will be removed no "
         "sooner than 3 months after the release date. Instead, use SPSA.minimize as a replacement, "
         "which supports the same arguments but follows the interface of scipy.optimize and returns "
-        "a complete result object containing additional information."
+        "a complete result object containing additional information.",
+        since="0.21.0",
     )
     def optimize(
         self,

qiskit/algorithms/phase_estimators/phase_estimation_result.py

@@ -69,8 +69,9 @@ def circuit_result(self) -> Result:
     @property
     @deprecate_function(
         """The 'PhaseEstimationResult.most_likely_phase' attribute
-                        is deprecated as of 0.18.0 and will be removed no earlier than 3 months
-                        after the release date. It has been renamed as the 'phase' attribute."""
+        is deprecated as of 0.18.0 and will be removed no earlier than 3 months
+        after the release date. It has been renamed as the 'phase' attribute.""",
+        since="0.18.0",
     )
     def most_likely_phase(self) -> float:
         r"""DEPRECATED - Return the most likely phase as a number in :math:`[0.0, 1.0)`.

qiskit/circuit/classicalregister.py

@@ -61,7 +61,8 @@ class ClassicalRegister(Register):
     @deprecate_function(
         "Register.qasm() is deprecated since Terra 0.23, as correct exporting to OpenQASM 2 is "
         "the responsibility of a larger exporter; it cannot safely be done on an object-by-object "
-        "basis without context. No replacement will be provided, because the premise is wrong."
+        "basis without context. No replacement will be provided, because the premise is wrong.",
+        since="0.23.0",
     )
     def qasm(self):
         """Return OPENQASM string for this register."""

qiskit/circuit/quantumregister.py

@@ -61,7 +61,8 @@ class QuantumRegister(Register):
     @deprecate_function(
         "Register.qasm() is deprecated since Terra 0.23, as correct exporting to OpenQASM 2 is "
         "the responsibility of a larger exporter; it cannot safely be done on an object-by-object "
-        "basis without context. No replacement will be provided, because the premise is wrong."
+        "basis without context. No replacement will be provided, because the premise is wrong.",
+        since="0.23.0",
     )
     def qasm(self):
         """Return OPENQASM string for this register."""

qiskit/dagcircuit/dagcircuit.py

@@ -530,7 +530,8 @@ def _add_op_node(self, op, qargs, cargs):
         """The DAGCircuit._copy_circuit_metadata method is deprecated as of 0.20.0. It will be removed
         no earlier than 3 months after the release date. You should use the DAGCircuit.copy_empty_like
         method instead, which acts identically.
-        """
+        """,
+        since="0.20.0",
     )
     def _copy_circuit_metadata(self):
         """DEPRECATED"""