Unify OpenQASM 2 exceptions (#9956)

* Unify OpenQASM 2 exceptions

Since gh-9784 added a new `qiskit.qasm2` package and suitable exceptions
for both import and export of OpenQASM 2 programs, this commit now
unifies the exception handling through the rest of the library to use
these exceptions.

To avoid breaks in compatibility, the old `qiskit.qasm.QasmError` is now
a re-export of `qiskit.qasm2.QASM2Error`.  This is the base error of
both the exporter and importers, despite the old documentation of
`QasmError` claiming to be specifically for parser errors.  In practice,
the exporter also emitted `QasmError`, so having that be `QASM2Error`
allows people catching that error to get the same behaviour in these new
forms.  The actual exporter and importer are updated to emit the precise
subclasses.

* Add newly-imported gates to exclude

The slight change in import order means that two new `Gate` class
bodies got executed during the imports for this particular part of the
test suite.  These gates were internal to the `qasm2.load`
functionality and should be exempt from the automated
definition-equivalence testing.

qiskit/circuit/instruction.py

@@ -40,7 +40,6 @@
 from qiskit.circuit.exceptions import CircuitError
 from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.circuit.classicalregister import ClassicalRegister, Clbit
-from qiskit.qasm.exceptions import QasmError
 from qiskit.qobj.qasm_qobj import QasmQobjInstruction
 from qiskit.circuit.parameter import ParameterExpression
 from qiskit.circuit.operation import Operation
@@ -438,10 +437,12 @@ def __deepcopy__(self, _memo=None):
 
     def _qasmif(self, string):
         """Print an if statement if needed."""
+        from qiskit.qasm2 import QASM2ExportError  # pylint: disable=cyclic-import
+
         if self.condition is None:
             return string
         if not isinstance(self.condition[0], ClassicalRegister):
-            raise QasmError(
+            raise QASM2ExportError(
                 "OpenQASM 2 can only condition on registers, but got '{self.condition[0]}'"
             )
         return "if(%s==%d) " % (self.condition[0].name, self.condition[1]) + string

qiskit/circuit/quantumcircuit.py

@@ -46,7 +46,6 @@
 from qiskit.circuit.instruction import Instruction
 from qiskit.circuit.gate import Gate
 from qiskit.circuit.parameter import Parameter
-from qiskit.qasm.exceptions import QasmError
 from qiskit.circuit.exceptions import CircuitError
 from qiskit.utils import optionals as _optionals
 from .classical import expr
@@ -1646,11 +1645,14 @@ def qasm(
         Raises:
             MissingOptionalLibraryError: If pygments is not installed and ``formatted`` is
                 ``True``.
-            QasmError: If circuit has free parameters.
+            QASM2ExportError: If circuit has free parameters.
         """
+        from qiskit.qasm2 import QASM2ExportError  # pylint: disable=cyclic-import
 
         if self.num_parameters > 0:
-            raise QasmError("Cannot represent circuits with unbound parameters in OpenQASM 2.")
+            raise QASM2ExportError(
+                "Cannot represent circuits with unbound parameters in OpenQASM 2."
+            )
 
         existing_gate_names = {
             "barrier",

qiskit/qasm/__init__.py

@@ -24,7 +24,6 @@
    :toctree: ../stubs/
 
    Qasm
-   QasmError
 
 
 Pygments

qiskit/qasm/exceptions.py

@@ -10,21 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-Exception for errors raised while parsing OPENQASM.
-"""
+"""Exception for errors raised while handling OpenQASM 2.0."""
 
-from qiskit.exceptions import QiskitError
-
-
-class QasmError(QiskitError):
-    """Base class for errors raised while parsing OPENQASM."""
-
-    def __init__(self, *msg):
-        """Set the error message."""
-        super().__init__(*msg)
-        self.msg = " ".join(msg)
-
-    def __str__(self):
-        """Return the message."""
-        return repr(self.msg)
+# Re-export from the new place to ensure that old code continues to work.
+from qiskit.qasm2.exceptions import QASM2Error as QasmError  # pylint: disable=unused-import

test/python/circuit/test_gate_definitions.py

@@ -282,6 +282,8 @@ class TestGateEquivalenceEqual(QiskitTestCase):
         "PermutationGate",
         "Commuting2qBlock",
         "PauliEvolutionGate",
+        "_U0Gate",
+        "_DefinedGate",
     }
     # Amazingly, Python's scoping rules for class bodies means that this is the closest we can get
     # to a "natural" comprehension or functional iterable definition: