Primitive V1 deprecation follow-up (#12824)

* Apply tweaks to deprecation messages, docstrings and release notes.

* Fix missing backtick

* Apply suggestions from Luciano's code review

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

* Update qiskit/primitives/statevector_sampler.py

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

* Update qiskit/primitives/backend_sampler.py

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

* Update qiskit/primitives/primitive_job.py

Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>

* Update qiskit/primitives/base/base_estimator.py

Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>

---------

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>
Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>

qiskit/primitives/backend_estimator.py

@@ -9,9 +9,8 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
-"""
-Expectation value class
-"""
+
+"""Estimator V1 implementation for an arbitrary Backend object."""
 
 from __future__ import annotations
 
@@ -37,7 +36,7 @@
 )
 from qiskit.utils.deprecation import deprecate_func
 
-from .base import BaseEstimator, EstimatorResult
+from .base import BaseEstimatorV1, EstimatorResult
 from .primitive_job import PrimitiveJob
 from .utils import _circuit_key, _observable_key, init_observable
 
@@ -89,23 +88,29 @@ def _prepare_counts(results: list[Result]):
     return counts
 
 
-class BackendEstimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
+class BackendEstimator(BaseEstimatorV1[PrimitiveJob[EstimatorResult]]):
     """Evaluates expectation value using Pauli rotation gates.
 
     The :class:`~.BackendEstimator` class is a generic implementation of the
-    :class:`~.BaseEstimator` interface that is used to wrap a :class:`~.BackendV2`
-    (or :class:`~.BackendV1`) object in the :class:`~.BaseEstimator` API. It
+    :class:`~.BaseEstimatorV1` interface that is used to wrap a :class:`~.BackendV2`
+    (or :class:`~.BackendV1`) object in the :class:`~.BaseEstimatorV1` API. It
     facilitates using backends that do not provide a native
-    :class:`~.BaseEstimator` implementation in places that work with
-    :class:`~.BaseEstimator`. However,
-    if you're using a provider that has a native implementation of
-    :class:`~.BaseEstimator`, it is a better choice to leverage that native
-    implementation as it will likely include additional optimizations and be
-    a more efficient implementation. The generic nature of this class
-    precludes doing any provider- or backend-specific optimizations.
+    :class:`~.BaseEstimatorV1` implementation in places that work with
+    :class:`~.BaseEstimatorV1`.
+    However, if you're using a provider that has a native implementation of
+    :class:`~.BaseEstimatorV1` or :class:`~.BaseEstimatorV2`, it is a better
+    choice to leverage that native implementation as it will likely include
+    additional optimizations and be a more efficient implementation.
+    The generic nature of this class precludes doing any provider- or
+    backend-specific optimizations.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use BackendEstimatorV2 instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="All implementations of the `BaseEstimatorV1` interface "
+        "have been deprecated in favor of their V2 counterparts. "
+        "The V2 alternative for the `BackendEstimator` class is `BackendEstimatorV2`.",
+    )
     def __init__(
         self,
         backend: BackendV1 | BackendV2,
@@ -114,10 +119,10 @@ def __init__(
         bound_pass_manager: PassManager | None = None,
         skip_transpilation: bool = False,
     ):
-        """Initialize a new BackendEstimator instance
+        """Initialize a new BackendEstimator (V1) instance
 
         Args:
-            backend: Required: the backend to run the primitive on
+            backend: (required) the backend to run the primitive on
             options: Default options.
             abelian_grouping: Whether the observable should be grouped into
                 commuting

qiskit/primitives/backend_sampler.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Sampler implementation for an arbitrary Backend object."""
+"""Sampler V1 implementation for an arbitrary Backend object."""
 
 from __future__ import annotations
 
@@ -26,39 +26,45 @@
 from qiskit.utils.deprecation import deprecate_func
 
 from .backend_estimator import _prepare_counts, _run_circuits
-from .base import BaseSampler, SamplerResult
+from .base import BaseSamplerV1, SamplerResult
 from .primitive_job import PrimitiveJob
 from .utils import _circuit_key
 
 
-class BackendSampler(BaseSampler[PrimitiveJob[SamplerResult]]):
-    """A :class:`~.BaseSampler` implementation that provides an interface for
-    leveraging the sampler interface from any backend.
+class BackendSampler(BaseSamplerV1[PrimitiveJob[SamplerResult]]):
+    """A :class:`~.BaseSamplerV1` implementation that provides a wrapper for
+    leveraging the Sampler V1 interface from any backend.
 
     This class provides a sampler interface from any backend and doesn't do
     any measurement mitigation, it just computes the probability distribution
     from the counts. It facilitates using backends that do not provide a
-    native :class:`~.BaseSampler` implementation in places that work with
-    :class:`~.BaseSampler`.
+    native :class:`~.BaseSamplerV1` implementation in places that work with
+    :class:`~.BaseSamplerV1`.
     However, if you're using a provider that has a native implementation of
-    :class:`~.BaseSampler`, it is a better choice to leverage that native
-    implementation as it will likely include additional optimizations and be
-    a more efficient implementation. The generic nature of this class
-    precludes doing any provider- or backend-specific optimizations.
+    :class:`~.BaseSamplerV1` or :class:`~.BaseESamplerV2`, it is a better
+    choice to leverage that native implementation as it will likely include
+    additional optimizations and be a more efficient implementation.
+    The generic nature of this class precludes doing any provider- or
+    backend-specific optimizations.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use BackendSamplerV2 instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="All implementations of the `BaseSamplerV1` interface "
+        "have been deprecated in favor of their V2 counterparts. "
+        "The V2 alternative for the `BackendSampler` class is `BackendSamplerV2`.",
+    )
     def __init__(
         self,
         backend: BackendV1 | BackendV2,
         options: dict | None = None,
         bound_pass_manager: PassManager | None = None,
         skip_transpilation: bool = False,
     ):
-        """Initialize a new BackendSampler
+        """Initialize a new BackendSampler (V1) instance
 
         Args:
-            backend: Required: the backend to run the sampler primitive on
+            backend: (required) the backend to run the sampler primitive on
             options: Default options.
             bound_pass_manager: An optional pass manager to run after
                 parameter binding.

qiskit/primitives/base/base_estimator.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Base Estimator Classes"""
+"""Base Estimator V1 and V2 classes"""
 
 from __future__ import annotations
 
@@ -110,7 +110,7 @@ def __init__(
         options: dict | None = None,
     ):
         """
-        Creating an instance of an Estimator, or using one in a ``with`` context opens a session that
+        Creating an instance of an Estimator V1, or using one in a ``with`` context opens a session that
         holds resources until the instance is ``close()`` ed or the context is exited.
 
         Args:
@@ -189,12 +189,19 @@ def _run(
 
 
 class BaseEstimator(BaseEstimatorV1[T]):
-    """DEPRECATED. Type alias of Estimator V1 base class.
+    """DEPRECATED. Type alias for Estimator V1 base class.
 
     See :class:`.BaseEstimatorV1` for details.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use BaseEstimatorV2 instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="The `BaseEstimator` class is a type alias for the `BaseEstimatorV1` "
+        "interface that has been deprecated in favor of explicitly versioned interface classes. "
+        "It is recommended to migrate all implementations to use `BaseEstimatorV2`. "
+        "However, for implementations incompatible with `BaseEstimatorV2`, `BaseEstimator` can "
+        "be replaced with the explicitly versioned `BaseEstimatorV1` class.",
+    )
     def __init__(
         self,
         *,

qiskit/primitives/base/base_sampler.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Base Sampler Classes"""
+"""Base Sampler V1 and V2 classes"""
 
 from __future__ import annotations
 
@@ -152,12 +152,19 @@ def _run(
 
 
 class BaseSampler(BaseSamplerV1[T]):
-    """DEPRECATED. Type alias of Sampler V1 base class
+    """DEPRECATED. Type alias for Sampler V1 base class
 
     See :class:`.BaseSamplerV1` for details.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use BaseSamplerV2 instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="The `BaseSampler` class is a type alias for the `BaseSamplerV1` "
+        "interface that has been deprecated in favor of explicitly versioned interface classes. "
+        "It is recommended to migrate all implementations to use `BaseSamplerV2`. "
+        "However, for implementations incompatible with `BaseSamplerV2`, `BaseSampler` can "
+        "be replaced with the explicitly versioned `BaseSamplerV1` class.",
+    )
     def __init__(
         self,
         *,

qiskit/primitives/estimator.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Estimator class
+Estimator V1 reference implementation
 """
 
 from __future__ import annotations
@@ -26,7 +26,7 @@
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 from qiskit.utils.deprecation import deprecate_func
 
-from .base import BaseEstimator, EstimatorResult
+from .base import BaseEstimatorV1, EstimatorResult
 from .primitive_job import PrimitiveJob
 from .utils import (
     _circuit_key,
@@ -36,9 +36,9 @@
 )
 
 
-class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
+class Estimator(BaseEstimatorV1[PrimitiveJob[EstimatorResult]]):
     """
-    Reference implementation of :class:`BaseEstimator`.
+    Reference implementation of :class:`BaseEstimatorV1`.
 
     :Run Options:
 
@@ -52,7 +52,12 @@ class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
           this option is ignored.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use StatevectorEstimator instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="All implementations of the `BaseEstimatorV1` interface "
+        "have been deprecated in favor of their V2 counterparts. "
+        "The V2 alternative for the `Estimator` class is `StatevectorEstimator`.",
+    )
     def __init__(self, *, options: dict | None = None):
         """
         Args:

qiskit/primitives/primitive_job.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Job implementation for the reference implementations of Primitives.
+Job for the reference implementations of Primitives V1 and V2.
 """
 
 import uuid

qiskit/primitives/sampler.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Sampler class
+Sampler V1 reference implementation
 """
 
 from __future__ import annotations
@@ -26,7 +26,7 @@
 from qiskit.result import QuasiDistribution
 from qiskit.utils.deprecation import deprecate_func
 
-from .base import BaseSampler, SamplerResult
+from .base import BaseSamplerV1, SamplerResult
 from .primitive_job import PrimitiveJob
 from .utils import (
     _circuit_key,
@@ -36,11 +36,11 @@
 )
 
 
-class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]):
+class Sampler(BaseSamplerV1[PrimitiveJob[SamplerResult]]):
     """
-    Sampler class.
+    Sampler V1 class.
 
-    :class:`~Sampler` is a reference implementation of :class:`~BaseSampler`.
+    :class:`~Sampler` is a reference implementation of :class:`~BaseSamplerV1`.
 
     :Run Options:
 
@@ -53,7 +53,12 @@ class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]):
           option is ignored.
     """
 
-    @deprecate_func(since="1.2", additional_msg="Use StatevectorSampler instead.")
+    @deprecate_func(
+        since="1.2",
+        additional_msg="All implementations of the `BaseSamplerV1` interface "
+        "have been deprecated in favor of their V2 counterparts. "
+        "The V2 alternative for the `Sampler` class is `StatevectorSampler`.",
+    )
     def __init__(self, *, options: dict | None = None):
         """
         Args:

qiskit/primitives/statevector_estimator.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Estimator class
+Statevector Estimator V2 class
 """
 
 from __future__ import annotations

qiskit/primitives/statevector_sampler.py

@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Statevector Sampler class
+Statevector Sampler V2 class
 """
 
 from __future__ import annotations

releasenotes/notes/deprecate-primitives-v1.yaml

@@ -1,17 +1,23 @@
 ---
 deprecations_primitives:
   - |
-    Primitives V1 is now deprecated and will be removed in no less than 3 months from the release date.
+    Primitive V1 implementations and V1-exclusive non-versioned type aliases are now 
+    deprecated in favor of their V2 counterparts. The deprecation is extended to the 
+    following classes implementing V1 interfaces:
 
-    The following Primitives V1 classes are deprecated:
+    * :class:`.Estimator`, in favor of the V2 equivalent, :class:`.StatevectorEstimator`
+    * :class:`.Sampler`, in favor of the V2 equivalent, :class:`.StatevectorSampler`
+    * :class:`.BackendEstimator`, in favor of the V2 equivalent, :class:`.BackendEstimatorV2`
+    * :class:`.BackendSampler`, in favor of the V2 equivalent, :class:`.BackendSamplerV2`
 
-    * :class:`.BaseEstimator`, use :class:`.BaseEstimatorV2` instead,
-    * :class:`.BaseSampler`, use :class:`.BaseSamplerV2` instead,
-    * :class:`.Estimator`, use :class:`.StatevectorEstimator` instead,
-    * :class:`.Sampler`, use :class:`.StatevectorSampler` instead,
-    * :class:`.BackendEstimator`, use :class:`.BackendEstimatorV2` instead,
-    * :class:`.BackendSampler`, use :class:`.BackendSamplerV2` instead,
+    As well as the following non-versioned type aliases:
+    
+    * :class:`.BaseEstimator`, alias for :class:`.BaseEstimatorV1`
+    * :class:`.BaseSampler`, alias for :class:`.BaseSamplerV1`
 
+    This deprecation does NOT affect the explicitly-versioned :class:`BaseEstimatorV1` 
+    and :class:`BaseSamplerV1` abstract
+    interface definitions or related result and job classes.
 
     In addition, the following utility functions are deprecated: