Deprecate qiskit.tools

This commit deprecates the qiskit.tools module. Most of the
functionality in this module will be removed in the Qiskit 1.0.0
release. The sole exception is the qiskit.tools.parallel module and it's
associated public function qiskit.tools.parallel_map which has been
moved to qiskit.utils.

qiskit/passmanager/passmanager.py

@@ -21,7 +21,7 @@
 
 import dill
 
-from qiskit.tools.parallel import parallel_map
+from qiskit.utils.parallel import parallel_map
 from .base_tasks import Task, PassManagerIR
 from .exceptions import PassManagerError
 from .flow_controllers import FlowControllerLinear

qiskit/test/base.py

@@ -28,7 +28,7 @@
 import unittest
 from unittest.util import safe_repr
 
-from qiskit.tools.parallel import get_platform_parallel_default
+from qiskit.utils.parallel import get_platform_parallel_default
 from qiskit.utils import optionals as _optionals
 from qiskit.circuit import QuantumCircuit
 from .decorators import enforce_subclasses_call

qiskit/tools/__init__.py

@@ -17,15 +17,6 @@
 
 .. currentmodule:: qiskit.tools
 
-Parallel Routines
------------------
-
-A helper function for calling a custom function with python ``ProcessPoolExecutor``.
-Tasks can be executed in parallel using this function.
-It has a built-in event publisher to show the progress of the parallel tasks.
-
-.. autofunction:: parallel_map
-
 Monitoring
 ----------
 
@@ -38,7 +29,34 @@
 .. automodule:: qiskit.tools.events
 
 """
-
-from .parallel import parallel_map
-from .monitor import job_monitor, backend_monitor, backend_overview
-from .events import progressbar
+import importlib
+import warnings
+
+
+_DEPRECATED_NAMES = {
+    "parallel_map": "qiskit.utils",
+    "parallel": "qiskit.utils.parallel",
+}
+
+
+_DEPRECATED_REMOVALS = {"job_monitor", "backend_monitor", "backend_overview", "progressbar"}
+
+
+def __getattr__(name):
+    if name in _DEPRECATED_NAMES:
+        module_name = _DEPRECATED_NAMES[name]
+        warnings.warn(
+            f"Accessing '{name}' from '{__name__}' is deprecated since Qiskit 0.46.0 "
+            f"and will be removed in Qiskit 1.0.0. Import from '{module_name}' instead ",
+            DeprecationWarning,
+            2,
+        )
+        return getattr(importlib.import_module(module_name), name)
+    if name in _DEPRECATED_REMOVALS:
+        warnings.warn(
+            f"'{name}' has been deprecated and will be removed in Qiskit 1.0.0.",
+            DeprecationWarning,
+            2,
+        )
+        return getattr(importlib.import_module(".monitor", "qiskit.tools"), name)
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

qiskit/tools/events/__init__.py

@@ -21,5 +21,10 @@
 
 .. autoclass:: TextProgressBar
 """
+import warnings
 
 from .progressbar import TextProgressBar
+
+warnings.warn(
+    "qiskit.tools.events is deprecated and will be removed in Qiskit 1.0.0", DeprecationWarning, 2
+)

qiskit/tools/events/progressbar.py

@@ -48,7 +48,7 @@
 import time
 import datetime
 import sys
-from qiskit.tools.events.pubsub import Subscriber
+from .pubsub import Subscriber
 
 
 class BaseProgressBar(Subscriber):

qiskit/tools/jupyter/__init__.py

@@ -109,6 +109,10 @@
 from .monospace import MonospacedOutput
 from .job_watcher import JobWatcher, JobWatcherMagic
 
+warnings.warn(
+    "qiskit.tools.jupyter is deprecated and will be removed in Qiskit 1.0.0", DeprecationWarning, 2
+)
+
 _IP = get_ipython()
 if _IP is not None:
     _IP.register_magics(ProgressBarMagic)

qiskit/tools/monitor/__init__.py

@@ -12,5 +12,12 @@
 
 """A module for monitoring jobs, backends, etc."""
 
+import warnings
+
 from .job_monitor import job_monitor
 from .overview import backend_monitor, backend_overview
+
+
+warnings.warn(
+    "qiskit.tools.monitor is deprecated and will be removed in Qiskit 1.0.0", DeprecationWarning, 2
+)

qiskit/transpiler/passes/layout/sabre_layout.py

@@ -43,7 +43,7 @@
 from qiskit.transpiler.passes.routing.sabre_swap import _build_sabre_dag, _apply_sabre_result
 from qiskit.transpiler.target import Target
 from qiskit.transpiler.coupling import CouplingMap
-from qiskit.tools.parallel import CPU_COUNT
+from qiskit.utils.parallel import CPU_COUNT
 
 logger = logging.getLogger(__name__)
 

qiskit/utils/__init__.py

@@ -52,6 +52,15 @@
 are run on a device or simulator by passing a QuantumInstance setup with the desired
 backend etc.
 
+Parallel Routines
+-----------------
+A helper function for calling a custom function with python
+``ProcessPoolExecutor``. Tasks can be executed in parallel using this function.
+It has a built-in event publisher to show the progress of the parallel
+tasks.
+
+.. autofunction:: parallel_map
+
 
 Optional Dependency Checkers (:mod:`qiskit.utils.optionals`)
 ============================================================
@@ -81,6 +90,8 @@
 from .name_unnamed_args import name_args
 from .algorithm_globals import algorithm_globals
 
+from .parallel import parallel_map
+
 
 __all__ = [
     "LazyDependencyManager",
@@ -102,4 +113,5 @@
     "local_hardware_info",
     "is_main_process",
     "apply_prefix",
+    "parallel_map",
 ]

qiskit/utils/mitigation/_filters.py

@@ -29,7 +29,6 @@
 
 import qiskit
 from qiskit import QiskitError
-from qiskit.tools import parallel_map
 from qiskit.utils.mitigation.circuits import count_keys
 from qiskit.utils.deprecation import deprecate_func
 
@@ -112,6 +111,7 @@ def apply(self, raw_data, method="least_squares"):
         """
         from scipy.optimize import minimize
         from scipy import linalg as la
+        from .. import parallel_map
 
         # check forms of raw_data
         if isinstance(raw_data, dict):
@@ -365,6 +365,7 @@ def apply(
         """
         from scipy.optimize import minimize
         from scipy import linalg as la
+        from .. import parallel_map
 
         all_states = count_keys(self.nqubits)
         num_of_states = 2**self.nqubits

qiskit/tools/parallel.py → qiskit/utils/parallel.py

@@ -53,7 +53,7 @@
 import sys
 
 from qiskit.exceptions import QiskitError
-from qiskit.utils.multiprocessing import local_hardware_info
+from .multiprocessing import local_hardware_info
 from qiskit.tools.events.pubsub import Publisher
 from qiskit import user_config
 

releasenotes/notes/deprecate-tools-392582e5d3c698eb.yaml

@@ -0,0 +1,39 @@
+---
+deprecations:
+  - |
+    The ``qiskit.tools.jupyter`` module has been deprecated and will be removed
+    in Qiskit 1.0.0. This module is deprecated because the functionality in
+    this module is tied to the legacy ``qiskit-ibmq-provider`` package which is
+    no longer supported and also only supported :class:`.BackendV1`. If you're
+    using this functionality currently, similar jupyter tools exist in the
+    `qiskit-ibm-provider <https://github.com/Qiskit/qiskit-ibm-provider>`__
+    package which can be used instead. The documentation for this module can
+    be found here:
+
+    https://docs.quantum.ibm.com/api/qiskit-ibm-provider/ibm_jupyter
+
+  - |
+    The ``qiskit.tools.monitor`` module has been deprecated and will be removed
+    in Qiskit 1.0.0. This module is deprecated because the functionality in
+    this module is tied to the legacy ``qiskit-ibmq-provider`` package which is
+    no longer supported and also only supported :class:`.BackendV1`.
+  - |
+    The ``qiskit.tools.visualization`` module has been deprecated and will be
+    removed in Qiskit 1.0.0. This module was a legacy redirect from the original
+    location of Qiskit's visualization module and was moved to
+    :mod:`qiskit.visualization` in Qiskit 0.8.0. If you're still using this
+    path you can just update your imports from ``qiskit.tools.visualization``
+    to :mod:`qiskit.visualization`.
+  - |
+    The ``qiskit.tools.events`` module and the :func:`.progressbar` utility
+    it exposed has been deprecated and will be removed in the Qiskit 1.0.0
+    release. This module's functionality was not widely used and better covered
+    by dedicated packages such as `tqdm <https://github.com/tqdm/tqdm>`__.
+  - |
+    The ``qiskit.tools`` module has been deprecated and will be removed in
+    Qiskit 1.0.0. Except as noted in the release notes above for specific
+    submodules (``qiskit.tools.jupyter``, ``qiskit.tools.monitor``, ``qiskit.tools.events`` and
+    ``qiskit.tools.visualization``) the functionality in this module have
+    been migrated to :mod:`qiskit.utils`. If you're using any functionality
+    in this module you can update your imports from ``qiskit.tools`` to
+    :mod:`qiskit.utils`.