Add exceptions to API documentation (backport #10522) (#10628)

* Add exceptions to API documentation (#10522) The big change here is that `QiskitError` is added to the API documentation, which causes 400--500 previously failing Sphinx lookups (stemming from "Raises:" documentation) to now succeed. This commit also corrects several other places where exceptions were not being fully documented (and in several cases makes the imports more convenient as well), and corrects a couple of places with incorrect references to exceptions. (cherry picked from commit 982807e) # Conflicts: # docs/apidocs/exceptions.rst # qiskit/dagcircuit/__init__.py # qiskit/passmanager/__init__.py # qiskit/transpiler/__init__.py * Fix merge conflicts This commit fixes several merge conflicts in the backport. They were mostly minor differences between main and the stable branch that needed to be corrected. --------- Co-authored-by: Jake Lishman <[email protected]> Co-authored-by: Matthew Treinish <[email protected]>
Qiskit · Aug 15, 2023 · 43ce89f · 43ce89f
1 parent ef8ae34
commit 43ce89f
Show file tree

Hide file tree

Showing 16 changed files with 95 additions and 20 deletions.
diff --git a/docs/apidocs/exceptions.rst b/docs/apidocs/exceptions.rst
@@ -0,0 +1,6 @@
+.. _qiskit-exceptions:
+
+.. automodule:: qiskit.exceptions
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
diff --git a/docs/apidocs/terra.rst b/docs/apidocs/terra.rst
@@ -45,3 +45,4 @@ Qiskit Terra API Reference
    utils_mitigation
    opflow
    algorithms
+   exceptions
diff --git a/qiskit/algorithms/amplitude_estimators/ae.py b/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

diff --git a/qiskit/circuit/__init__.py b/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

diff --git a/qiskit/circuit/exceptions.py b/qiskit/circuit/exceptions.py
@@ -17,5 +17,3 @@
 
 class CircuitError(QiskitError):
     """Base class for errors raised while processing a circuit."""
-
-    pass
diff --git a/qiskit/dagcircuit/__init__.py b/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
diff --git a/qiskit/exceptions.py b/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
 

diff --git a/qiskit/extensions/__init__.py b/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,

diff --git a/qiskit/opflow/gradients/circuit_gradients/lin_comb.py b/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.
         """

diff --git a/qiskit/providers/__init__.py b/qiskit/providers/__init__.py
@@ -129,6 +129,7 @@
 .. autoexception:: BackendPropertyError
 .. autoexception:: JobError
 .. autoexception:: JobTimeoutError
+.. autoexception:: BackendConfigurationError
 
 ======================
 Writing a New Provider

diff --git a/qiskit/pulse/__init__.py b/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,

diff --git a/qiskit/qasm2/__init__.py b/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

diff --git a/qiskit/qpy/__init__.py b/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.

diff --git a/qiskit/qpy/exceptions.py b/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
 
 

diff --git a/qiskit/transpiler/__init__.py b/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

diff --git a/qiskit/transpiler/passes/synthesis/unitary_synthesis.py b/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