Simplify return type of DAGCircuit::control_flow_op_nodes (Qiskit#13892)

Technically this is a breaking change, not because of the type change
(we're returning a subset of what we previously did), but because the
docstring previously _explicitly_ said that `None` was used for the
empty list.  In practice, this is a bit of a footgun (as I found), and
inconsistent with the other `DAGCircuit` methods.  It's not clear that
it has a performance advantage; technically it can save a single Python
empty-list allocation (`None` is a singleton), but this cost is pretty
trivial.

Author: jakelishman

crates/circuit/src/dag_circuit.rs

@@ -3628,28 +3628,24 @@ def _format(operand):
     /// Get a list of "op" nodes in the dag that contain control flow instructions.
     ///
     /// Returns:
-    ///     list[DAGOpNode] | None: The list of dag nodes containing control flow ops. If there
-    ///         are no control flow nodes None is returned
-    fn control_flow_op_nodes(&self, py: Python) -> PyResult<Option<Vec<Py<PyAny>>>> {
-        if self.has_control_flow() {
-            let result: PyResult<Vec<Py<PyAny>>> = self
-                .dag
-                .node_references()
-                .filter_map(|(node_index, node_type)| match node_type {
-                    NodeType::Operation(ref node) => {
-                        if node.op.control_flow() {
-                            Some(self.unpack_into(py, node_index, node_type))
-                        } else {
-                            None
-                        }
-                    }
-                    _ => None,
-                })
-                .collect();
-            Ok(Some(result?))
-        } else {
-            Ok(None)
+    ///     list[DAGOpNode]: The list of dag nodes containing control flow ops.
+    fn control_flow_op_nodes(&self, py: Python) -> PyResult<Vec<Py<PyAny>>> {
+        if !self.has_control_flow() {
+            return Ok(vec![]);
         }
+        self.dag
+            .node_references()
+            .filter_map(|(node_index, node_type)| match node_type {
+                NodeType::Operation(ref node) => {
+                    if node.op.control_flow() {
+                        Some(self.unpack_into(py, node_index, node_type))
+                    } else {
+                        None
+                    }
+                }
+                _ => None,
+            })
+            .collect()
     }
 
     /// Get the list of gate nodes in the dag.

qiskit/transpiler/passes/optimization/consolidate_blocks.py

@@ -138,11 +138,9 @@ def _handle_control_flow_ops(self, dag):
             pass_manager.append(Collect2qBlocks())
 
         pass_manager.append(self)
-        control_flow_nodes = dag.control_flow_op_nodes()
-        if control_flow_nodes is not None:
-            for node in control_flow_nodes:
-                dag.substitute_node(
-                    node,
-                    node.op.replace_blocks(pass_manager.run(block) for block in node.op.blocks),
-                )
+        for node in dag.control_flow_op_nodes():
+            dag.substitute_node(
+                node,
+                node.op.replace_blocks(pass_manager.run(block) for block in node.op.blocks),
+            )
         return dag

qiskit/transpiler/passes/utils/control_flow.py

@@ -54,13 +54,8 @@ def out(self, dag):
         def bound_wrapped_method(dag):
             return out(self, dag)
 
-        control_flow_nodes = dag.control_flow_op_nodes()
-        if control_flow_nodes is not None:
-            for node in control_flow_nodes:
-                dag.substitute_node(
-                    node,
-                    map_blocks(bound_wrapped_method, node.op),
-                )
+        for node in dag.control_flow_op_nodes():
+            dag.substitute_node(node, map_blocks(bound_wrapped_method, node.op))
         return method(self, dag)
 
     return out

releasenotes/notes/control-flow-op-nodes-ceece8c398bd30ee.yaml

@@ -0,0 +1,11 @@
+---
+upgrade_circuits:
+  - |
+    :meth:`.DAGCircuit.control_flow_op_nodes` now always returns a list, even if empty.  Previously,
+    it returned ``None`` if empty, and never returned the empty list, which required special handling.
+    If you need to explicitly test for emptiness in both Qiskit 1.x and 2.x, you can do::
+
+      control_flow_nodes = dag.control_flow_op_nodes()
+      if not control_flow_nodes:
+          # There are no control-flow nodes.
+          pass