Deprecate legacy provider interface (#6337)

* Deprecate legacy provider interface

In the 0.16.0 release we added a new versioned providers interface that
included a V1 version of the Backend, Job, and Provider classes. Since
then we've updated and unified almost all of the providers that exist to
use the current interface. Having everything use the new interface means
that we're now able to both evolve the interface in a controlled manner
uniformly and also deprecate the legacy interface to signal to any other
providers out there (especially those we don't maintain) that we'll only
be supporting the versioned interface moving forward.

* Fix lint

* Run black

* Add deprecation warning assertion on legacy backends tests

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

qiskit/providers/__init__.py

@@ -499,6 +499,11 @@ def status(self):
 Legacy Provider Interface Base Objects (:mod:`qiskit.providers`)
 ================================================================
 
+These abstract interfaces are deprecated and will be removed in a future
+release. The documentation here is left for reference purposes while they're
+still supported, but if you're creating or maintaining a provider you should
+be using the versioned interface.
+
 .. currentmodule:: qiskit.providers
 
 Base Objects

qiskit/providers/basebackend.py

@@ -17,6 +17,7 @@
 """
 
 from abc import ABC, abstractmethod
+import warnings
 
 from qiskit.version import VERSION as __version__
 from .models import BackendStatus
@@ -27,7 +28,7 @@ class BaseBackend(ABC):
 
     @abstractmethod
     def __init__(self, configuration, provider=None):
-        """Base class for backends.
+        """DEPRECATED Legacy base class for backends.
 
         This method should initialize the module and its configuration, and
         raise an exception if a component of the module is
@@ -40,6 +41,15 @@ def __init__(self, configuration, provider=None):
         Raises:
             QiskitError: if an error occurred when instantiating the backend.
         """
+        warnings.warn(
+            "The BaseBackend abstract interface is deprecated as of "
+            "the 0.18.0 release and will be removed in a future "
+            "release. Instead you should build your backends using "
+            "the BackendV1 abstract class (which is the current "
+            "latest version of the backend interface)",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self._configuration = configuration
         self._provider = provider
 

qiskit/providers/basejob.py

@@ -19,14 +19,15 @@
 from abc import ABC, abstractmethod
 from typing import Callable, Optional
 import time
+import warnings
 
 from .jobstatus import JobStatus, JOB_FINAL_STATES
 from .exceptions import JobTimeoutError
 from .basebackend import BaseBackend
 
 
 class BaseJob(ABC):
-    """Legacy Class to handle asynchronous jobs"""
+    """DEPRECATED Legacy Class to handle asynchronous jobs"""
 
     def __init__(self, backend: BaseBackend, job_id: str) -> None:
         """Initializes the asynchronous job.
@@ -36,6 +37,15 @@ def __init__(self, backend: BaseBackend, job_id: str) -> None:
             job_id: a unique id in the context of the backend used to run
                 the job.
         """
+        warnings.warn(
+            "The BaseJob abstract interface is deprecated as of "
+            "the 0.18.0 release and will be removed in a future "
+            "release. Instead you should build your backends using "
+            "the JobV1 abstract class (which is the current "
+            "latest version of the backend interface)",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self._job_id = job_id
         self._backend = backend
 

qiskit/providers/baseprovider.py

@@ -13,14 +13,24 @@
 """Base class for a backend provider."""
 
 from abc import ABC, abstractmethod
+import warnings
 
 from .exceptions import QiskitBackendNotFoundError
 
 
 class BaseProvider(ABC):
     """Base class for a Backend Provider."""
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs):  # pylint: disable=unused-argument
+        warnings.warn(
+            "The BaseProvider abstract interface is deprecated as of "
+            "the 0.18.0 release and will be removed in a future "
+            "release. Instead you should build your backends using "
+            "the ProviderV1 abstract class (which is the current "
+            "latest version of the provider interface).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         pass
 
     def get_backend(self, name=None, **kwargs):

releasenotes/notes/deprecate-legacy-providers-383bf4142153297a.yaml

@@ -0,0 +1,14 @@
+---
+deprecations:
+  - |
+    The legacy providers interface, which consisted of the
+    :class:`qiskit.providers.BaseBackend`, :class:`qiskit.providers.BaseJob`,
+    and :class:`qiskit.providers.BaseProvider` abstract classes, has been
+    deprecated and will be removed in a future release. Instead you should use
+    the versioned interface, which the current abstract class versions are
+    :class:`qiskit.providers.BackendV1`, :class:`qiskit.providers.JobV1`, and
+    :class:`qiskit.providers.ProvidersV1`. The V1 objects are mostly backwards
+    compatible to ease migration from the legacy interface to the versioned
+    one. However, expect future versions of the abstract interfaces to diverge
+    more. You can refer to the :mod:`qiskit.providers` documentation for
+    more high level details about the versioned interface.

test/python/providers/test_fake_backends.py

@@ -78,14 +78,15 @@ def test_circuit_on_fake_legacy_backend(self, backend, optimization_level):
                 "Unable to run fake_backend %s without qiskit-aer"
                 % backend.configuration().backend_name
             )
-        job = execute(
-            self.circuit,
-            backend,
-            optimization_level=optimization_level,
-            seed_simulator=42,
-            seed_transpiler=42,
-        )
-        result = job.result()
+        with self.assertWarns(DeprecationWarning):
+            job = execute(
+                self.circuit,
+                backend,
+                optimization_level=optimization_level,
+                seed_simulator=42,
+                seed_transpiler=42,
+            )
+            result = job.result()
         counts = result.get_counts()
         max_count = max(counts.items(), key=operator.itemgetter(1))[0]
         self.assertEqual(max_count, "11")