Add exceptions to API documentation (backport #10522)

docs/apidocs/exceptions.rst

@@ -0,0 +1,6 @@
+.. _qiskit-exceptions:
+
+.. automodule:: qiskit.exceptions
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidocs/terra.rst

@@ -45,3 +45,4 @@ Qiskit Terra API Reference
    utils_mitigation
    opflow
    algorithms
+   exceptions

qiskit/algorithms/amplitude_estimators/ae.py

@@ -458,7 +458,6 @@ def compute_confidence_interval(
             The (1 - alpha) confidence interval of the specified kind.
 
         Raises:
-            AquaError: If 'mle' is not in self._ret.keys() (i.e. `run` was not called yet).
             NotImplementedError: If the confidence interval method `kind` is not implemented.
         """
         # if statevector simulator the estimate is exact

qiskit/circuit/__init__.py

@@ -348,7 +348,17 @@
 .. currentmodule:: qiskit.circuit.random
 .. autofunction:: random_circuit
 .. currentmodule:: qiskit.circuit
+
+Exceptions
+----------
+
+Almost all circuit functions and methods will raise a :exc:`CircuitError` when encountering an error
+that is particular to usage of Qiskit (as opposed to regular typing or indexing problems, which will
+typically raise the corresponding standard Python error).
+
+.. autoexception:: CircuitError
 """
+from .exceptions import CircuitError
 from .quantumcircuit import QuantumCircuit
 from .classicalregister import ClassicalRegister, Clbit
 from .quantumregister import QuantumRegister, Qubit, AncillaRegister, AncillaQubit

qiskit/circuit/exceptions.py

@@ -17,5 +17,3 @@
 
 class CircuitError(QiskitError):
     """Base class for errors raised while processing a circuit."""
-
-    pass

qiskit/dagcircuit/__init__.py

@@ -34,10 +34,8 @@
 Exceptions
 ==========
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   DAGCircuitError
+.. autoexception:: DAGCircuitError
+.. autoexception:: DAGDependencyError
 
 Utilities
 =========
@@ -53,5 +51,5 @@
 from .dagcircuit import DAGCircuit
 from .dagnode import DAGNode, DAGOpNode, DAGInNode, DAGOutNode
 from .dagdepnode import DAGDepNode
-from .exceptions import DAGCircuitError
+from .exceptions import DAGCircuitError, DAGDependencyError
 from .dagdependency import DAGDependency

qiskit/exceptions.py

@@ -10,7 +10,39 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Exceptions for errors raised by Qiskit."""
+"""
+===============================================
+Top-level exceptions (:mod:`qiskit.exceptions`)
+===============================================
+
+All Qiskit-related errors raised by Qiskit are subclasses of the base:
+
+.. autoexception:: QiskitError
+
+.. note::
+
+    Errors that are just general programming errors, such as incorrect typing, may still raise
+    standard Python errors such as ``TypeError``.  :exc:`QiskitError` is generally for errors raised
+    in usage that is particular to Qiskit.
+
+Many of the Qiskit subpackages define their own more granular error, to help in catching only the
+subset of errors you care about.  For example, :mod:`qiskit.circuit` almost exclusively uses
+:exc:`.CircuitError`, while both :exc:`.QASM2ExportError` and :exc:`.QASM2ParseError` derive from
+:exc:`.QASM2Error` in :mod:`qiskit.qasm2`, which is in turn a type of :exc:`.QiskitError`.
+
+Qiskit has several optional features that depend on other packages that are not required for a
+minimal install.  You can read more about those, and ways to check for their presence, in
+:mod:`qiskit.utils.optionals`.  Trying to use a feature that requires an optional extra will raise a
+particular error, which subclasses both :exc:`QiskitError` and the Python built-in ``ImportError``.
+
+.. autoexception:: MissingOptionalLibraryError
+
+Two more uncommon errors relate to failures in reading user-configuration files, or specifying a
+filename that cannot be used:
+
+.. autoexception:: QiskitUserConfigError
+.. autoexception:: InvalidFileError
+"""
 
 from typing import Optional
 

qiskit/extensions/__init__.py

@@ -53,12 +53,21 @@
    UCRXGate
    UCRYGate
    UCRZGate
+
+Exceptions
+==========
+
+The additional gates in this module will tend to raise a custom exception when they encounter
+problems.
+
+.. autoexception:: ExtensionError
 """
 
 # import all standard gates
 from qiskit.circuit.library.standard_gates import *
 from qiskit.circuit.barrier import Barrier
 
+from .exceptions import ExtensionError
 from .quantum_initializer import (
     Initialize,
     SingleQubitUnitary,

qiskit/opflow/gradients/circuit_gradients/lin_comb.py

@@ -712,7 +712,7 @@ def _gradient_states(
             parameterized gates to compute the product rule.
 
         Raises:
-            AquaError: If one of the circuits could not be constructed.
+            QiskitError: If one of the circuits could not be constructed.
             TypeError: If the operators is of unsupported type.
             ValueError: If the auxiliary operator preparation fails.
         """
@@ -804,7 +804,7 @@ def _hessian_states(
             created per parameterized gates to compute the product rule.
 
         Raises:
-            AquaError: If one of the circuits could not be constructed.
+            QiskitError: If one of the circuits could not be constructed.
             TypeError: If ``operator`` is of unsupported type.
             ValueError: If the auxiliary operator preparation fails.
         """

qiskit/providers/__init__.py

@@ -129,6 +129,7 @@
 .. autoexception:: BackendPropertyError
 .. autoexception:: JobError
 .. autoexception:: JobTimeoutError
+.. autoexception:: BackendConfigurationError
 
 ======================
 Writing a New Provider

qiskit/pulse/__init__.py

@@ -57,6 +57,10 @@
 ==========
 
 .. autoexception:: PulseError
+.. autoexception:: BackendNotSet
+.. autoexception:: NoActiveBuilder
+.. autoexception:: UnassignedDurationError
+.. autoexception:: UnassignedReferenceError
 """
 
 # Builder imports.
@@ -124,7 +128,13 @@
     LoConfig,
     LoRange,
 )
-from qiskit.pulse.exceptions import PulseError
+from qiskit.pulse.exceptions import (
+    PulseError,
+    BackendNotSet,
+    NoActiveBuilder,
+    UnassignedDurationError,
+    UnassignedReferenceError,
+)
 from qiskit.pulse.instruction_schedule_map import InstructionScheduleMap
 from qiskit.pulse.instructions import (
     Acquire,

qiskit/qasm2/__init__.py

@@ -98,6 +98,11 @@
 
 .. autoexception:: QASM2ParseError
 
+Similarly, a failure during the export of an OpenQASM 2 program will raise its own subclass of
+:exc:`QASM2Error`:
+
+.. autoexception:: QASM2ExportError
+
 .. _qasm2-examples:
 
 Examples

qiskit/qpy/__init__.py

@@ -74,6 +74,11 @@
 .. autofunction:: load
 .. autofunction:: dump
 
+These functions will raise a custom subclass of :exc:`.QiskitError` if they encounter problems
+during serialization or deserialization.
+
+.. autoexception:: QpyError
+
 QPY Compatibility
 =================
 
@@ -1265,6 +1270,7 @@ class if it's defined in Qiskit. Otherwise it falls back to the custom
 .. [#f3] https://docs.python.org/3/c-api/complex.html#c.Py_complex
 """
 
+from .exceptions import QpyError
 from .interface import dump, load
 
 # For backward compatibility. Provide, Runtime, Experiment call these private functions.

qiskit/qpy/exceptions.py

@@ -10,7 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Exception for errors raised by the pulse module."""
+"""Exception for errors raised by the QPY module."""
+
 from qiskit.exceptions import QiskitError
 
 

qiskit/transpiler/__init__.py

@@ -1241,19 +1241,18 @@
 Exceptions
 ----------
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   TranspilerError
-   TranspilerAccessError
+.. autoexception:: TranspilerError
+.. autoexception:: TranspilerAccessError
+.. autoexception:: CouplingError
+.. autoexception:: LayoutError
 """
 
 from .runningpassmanager import FlowController, ConditionalController, DoWhileController
 from .passmanager import PassManager
 from .passmanager_config import PassManagerConfig
 from .passmanager import StagedPassManager
 from .propertyset import PropertySet
-from .exceptions import TranspilerError, TranspilerAccessError
+from .exceptions import TranspilerError, TranspilerAccessError, CouplingError, LayoutError
 from .fencedobjs import FencedDAGCircuit, FencedPropertySet
 from .basepasses import AnalysisPass, TransformationPass
 from .coupling import CouplingMap

qiskit/transpiler/passes/synthesis/unitary_synthesis.py

@@ -312,7 +312,7 @@ def __init__(
                 the gate direction with the shorter
                 duration from the backend properties will be used. If
                 set to True, and a natural direction can not be
-                determined, raises :class:`~TranspileError`. If set to None, no
+                determined, raises :class:`.TranspilerError`. If set to None, no
                 exception will be raised if a natural direction can
                 not be determined.
             synth_gates (list[str]): List of gates to synthesize. If None and