Deprecate legacy qasm2 parser for 0.46 (#11347)

* Deprecate legacy qasm2 parser for 0.46

The legacy qasm2 parser was remvoed on the main branch already
in #11308 for the 1.0.0 release. To ensure that users of the 0.x release
series are warned of this API change this commit marks the functionality
removed in #11308 as deprecated for the 0.46.0 release.

* Update qiskit/converters/ast_to_dag.py

---------

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>

qiskit/circuit/quantumcircuit.py

@@ -1594,6 +1594,11 @@ def decompose(
         # do not copy operations, this is done in the conversion with circuit_to_dag
         return dag_to_circuit(dag, copy_operations=False)
 
+    @deprecate_func(
+        since="0.46",
+        additional_msg="Instead use the qiskit.qasm2.dump() or qiskit.qasm2.dumps() function",
+        removal_timeline="in the 1.0.0 release",
+    )
     def qasm(
         self,
         formatted: bool = False,

qiskit/converters/ast_to_dag.py

@@ -26,8 +26,14 @@
 from qiskit.circuit.barrier import Barrier
 from qiskit.circuit.delay import Delay
 from qiskit.circuit.library import standard_gates as std
+from qiskit.utils.deprecation import deprecate_func
 
 
+@deprecate_func(
+    since="0.46",
+    additional_msg="Instead use the qiskit.qasm2.dump() or qiskit.qasm2.dumps() function",
+    removal_timeline="in the 1.0.0 release",
+)
 def ast_to_dag(ast):
     """Build a ``DAGCircuit`` object from an AST ``Node`` object.
 

qiskit/qasm/__init__.py

@@ -17,6 +17,12 @@
 
 .. currentmodule:: qiskit.qasm
 
+.. deprecated:: 0.46.0
+
+   The :mod:`qiskit.qasm` module has been deprecated and superseded by the :mod:`qiskit.qasm2`
+   module which provides a faster more correct parser.
+
+
 QASM Routines
 =============
 
@@ -36,6 +42,8 @@
     :class-doc-from: class
 """
 
+import warnings
+
 from numpy import pi
 
 from qiskit.utils.optionals import HAS_PYGMENTS
@@ -44,6 +52,14 @@
 from .exceptions import QasmError
 
 
+warnings.warn(
+    "The `qiskit.qasm` has been deprecated and superseded by the `qiskit.qasm2` module. "
+    "`qiskit.qasm` will be removed in the Qiskit 1.0.0 release.",
+    category=DeprecationWarning,
+    stacklevel=2,
+)
+
+
 def __getattr__(name):
     if name in ("OpenQASMLexer", "QasmHTMLStyle", "QasmTerminalStyle"):
         import qiskit.qasm.pygments

releasenotes/notes/deprecate-qasm-legacy-d0b6025493da453a.yaml

@@ -0,0 +1,29 @@
+---
+deprecations:
+  - |
+    The legacy OpenQASM 2 parser module previously present in :mod:`qiskit.qasm` has been
+    deprecated. It will be removed in the Qiskit 1.0.0 release. The legacy
+    OpenQASM 2 parser has been superseded by the :mod:`qiskit.qasm2` module
+    which provides a faster more correct parser for OpenQASM 2.
+  - |
+    The ``qiskit.converters.ast_to_dag`` function has been deprecated and
+    will be removed in the Qiskit 1.0.0 release. It previously was used to
+    convert the abstract syntax tree generated by the legacy OpenQASM 2 parser
+    (in the :mod:`qiskit.qasm` module which has been deprecated) and convert
+    that directly to a :class:`.DAGCircuit`. As the legacy OpenQASM 2 parser
+    has been deprecated this function will no longer serves a purpose after the
+    legacy parser is removed. If you were previously using this, you can
+    instead parse your OpenQASM 2 files into a :class:`.QuantumCircuit` using
+    the :meth:`.QuantumCircuit.from_qasm_file` or
+    :meth:`.QuantumCircuit.from_qasm_str` constructor methods and then
+    converting that :class:`.QuantumCircuit` into a :class:`.DAGCircuit`
+    with :func:`.circuit_to_dag`.
+  - |
+    The :meth:`.QuantumCircuit.qasm` method used to generate a OpenQASM 2
+    representation of the :class:`.QuantumCircuit` object has been deprecated
+    and will be removed in the Qiskit 1.0.0 release. Instead the
+    :func:`.qasm2.dump` or :func:`.qasm2.dumps` functions which provide similar
+    functionality should be used. If you were using the :meth:`.QuantumCircuit.qasm`
+    method to generate pygments formatted output you should instead look at the standalone
+    ``openqasm-pygments`` package to provide this functionality (as :func:`.qasm2.dump`
+    and :func:`.qasm2.dumps` do not provide pygments colored output).

test/python/basicaer/test_qasm_simulator.py

@@ -306,7 +306,8 @@ def test_teleport(self):
             "1": data["1 0 0"] + data["1 1 0"] + data["1 0 1"] + data["1 1 1"],
         }
         self.log.info("test_teleport: circuit:")
-        self.log.info(circuit.qasm())
+        with self.assertWarns(DeprecationWarning):
+            self.log.info(circuit.qasm())
         self.log.info("test_teleport: data %s", data)
         self.log.info("test_teleport: alice %s", alice)
         self.log.info("test_teleport: bob %s", bob)

test/python/circuit/library/test_permutation.py

@@ -162,7 +162,8 @@ def test_qasm(self):
             "permutation__2_4_3_0_1_ q0[0],q0[1],q0[2],q0[3],q0[4];\n"
             "h q0[0];\n"
         )
-        self.assertEqual(expected_qasm, circuit.qasm())
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(expected_qasm, circuit.qasm())
 
     def test_qpy(self):
         """Test qpy for circuits with permutations."""