Add deprecation warning on use of qiskit.IBMQ (#8080)

* Add deprecation warning on use of qiskit.IBMQ

With the pending release of the qiskit-ibm-provider that superscedes the
qiskit-ibmq-provider package. The qiskit-ibmq-provider is now deprecated
and will be retired/archived in the future. In coordination with that
this commit deprecates the lazy loading fixture qiskit.IBMQ and removes
documentation references to qiskit-ibmq-provider in the repo.

* Fix typos

Co-authored-by: Jim Garrison <jim@garrison.cc>

* Remove superfluous warnings

* Add pip to warning message

* Fix lint

* Update references to qiskit.IBMQ

* Add release note

* Add back ibmq_mock.py file

* Add link to the migration guide in release note

Co-authored-by: Jim Garrison <jim@garrison.cc>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

qiskit/__init__.py

@@ -158,6 +158,16 @@ class IBMQWrapper:
                 from qiskit.providers import ibmq
 
                 self.ibmq = ibmq.IBMQ
+                warnings.warn(
+                    "The qiskit.IBMQ entrypoint and the qiskit-ibmq-provider package ("
+                    "accessible from 'qiskit.providers.ibmq`) are deprecated and will be removed "
+                    "in a future release. Instead you should use the qiskit-ibm-provider package "
+                    "which is accessible from 'qiskit_ibm_provider'. You can install it with "
+                    "'pip install qiskit_ibm_provider'",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
             except ImportError:
                 return False
         return True
@@ -168,6 +178,16 @@ class IBMQWrapper:
                 from qiskit.providers import ibmq
 
                 self.ibmq = ibmq.IBMQ
+                warnings.warn(
+                    "The qiskit.IBMQ entrypoint and the qiskit-ibmq-provider package ("
+                    "accessible from 'qiskit.providers.ibmq`) are deprecated and will be removed "
+                    "in a future release. Instead you should use the qiskit-ibm-provider package "
+                    "which is accessible from 'qiskit_ibm_provider'. You can install it with "
+                    "'pip install qiskit_ibm_provider'. Just replace 'qiskit.IBMQ' with "
+                    "'qiskit_ibm_provider.IBMProvider'",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
             except ImportError as ex:
                 raise MissingOptionalLibraryError(
                     "qiskit-ibmq-provider", "IBMQ provider", "pip install qiskit-ibmq-provider"

qiskit/providers/fake_provider/__init__.py

@@ -70,7 +70,7 @@ Here is an example of using a fake backend for transpilation and simulation.
 
     .. code-block:: python
 
-        from qiskit import IBMQ
+        from qiskit.providers.ibmq import IBMQ
         from qiskit.providers.aer import AerSimulator
 
         # get a real backend from a real provider

qiskit/tools/jupyter/__init__.py

@@ -25,7 +25,7 @@ Overview of all available backends
 
 .. code-block::
 
-    from qiskit import IBMQ
+    from qiskit.providers.ibmq import IBMQ
     import qiskit.tools.jupyter
     %matplotlib inline
 
@@ -39,7 +39,7 @@ Detailed information on a single backend
 
 .. code-block::
 
-    from qiskit import IBMQ
+    from qiskit.providers.ibmq import IBMQ
     import qiskit.tools.jupyter
     %matplotlib inline
 

qiskit/tools/monitor/overview.py

@@ -62,7 +62,7 @@ def backend_monitor(backend):
     Examples:
     .. code-block:: python
 
-       from qiskit import IBMQ
+       from qiskit.providers.ibmq import IBMQ
        from qiskit.tools.monitor import backend_monitor
        provider = IBMQ.get_provider(hub='ibm-q')
        backend_monitor(provider.backends.ibmq_lima)
@@ -175,7 +175,7 @@ def backend_overview():
 
         .. code-block:: python
 
-            from qiskit import IBMQ
+            from qiskit.providers.ibmq import IBMQ
             from qiskit.tools.monitor import backend_overview
             provider = IBMQ.get_provider(hub='ibm-q')
             backend_overview()

qiskit/visualization/gate_map.py

@@ -767,8 +767,9 @@ def plot_circuit_layout(circuit, backend, view="virtual", qubit_coordinates=None
             import numpy as np
             from qiskit import QuantumCircuit, transpile
             from qiskit.providers.fake_provider import FakeVigoV2
-            from qiskit.visualization import plot_histogram, plot_gate_map, plot_circuit_layout
+            from qiskit.visualization import plot_circuit_layout
             from qiskit.tools.monitor import job_monitor
+            from qiskit.providers.fake_provider import FakeVigoV2
             import matplotlib.pyplot as plt
 
             ghz = QuantumCircuit(3, 3)
@@ -849,7 +850,7 @@ def plot_error_map(backend, figsize=(12, 9), show_title=True, qubit_coordinates=
     """Plots the error map of a given backend.
 
     Args:
-        backend (IBMQBackend): Given backend.
+        backend (Backend): Given backend.
         figsize (tuple): Figure size in inches.
         show_title (bool): Show the title or not.
         qubit_coordinates (Sequence): An optional sequence input (list or array being the
@@ -862,7 +863,6 @@ def plot_error_map(backend, figsize=(12, 9), show_title=True, qubit_coordinates=
         Figure: A matplotlib figure showing error map.
 
     Raises:
-        VisualizationError: Input is not IBMQ backend.
         VisualizationError: The backend does not provide gate errors for the 'sx' gate.
         MissingOptionalLibraryError: If seaborn is not installed
 

releasenotes/notes/deprecate-qiskit-ibmq-f0dc372526fe0c57.yaml

@@ -0,0 +1,13 @@
+---
+deprecations:
+  - |
+    The ``qiskit.IBMQ`` object is deprecated. This alias object lazily redirects
+    attribute access to ``qiskit.providers.ibmq.IBMQ``. As the
+    ``qiskit-ibmq-provider`` package has been supersceded by
+    ``qiskit-ibm-provider`` package which maintains its own namespace
+    maintaining this alias is no longer relevant with the new package. If you
+    were relying on the ``qiskit.IBMQ`` alias you should update your usage
+    to use ``qiskit.providers.ibmq.IBMQ`` directly instead (and also consider
+    migrating to ``qiskit-ibm-provider``, see the
+    `migration guide <https://qiskit.org/documentation/partners/qiskit_ibm_provider/tutorials/Migration_Guide_from_qiskit-ibmq-provider.html>`__
+    for more details).

tools/update_fake_backends.py

@@ -19,7 +19,7 @@ from datetime import datetime
 import json
 import os
 
-from qiskit import IBMQ
+from qiskit.providers.ibmq import IBMQ
 from qiskit.circuit.parameterexpression import ParameterExpression