Address review comments.

Author: kevinhartman

qiskit/circuit/classical/expr/visitors.py

@@ -138,6 +138,11 @@ def iter_vars(node: expr.Expr) -> typing.Iterator[expr.Var]:
             for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)):
                 if isinstance(node.var, ClassicalRegister):
                     print(node.var.name)
+
+    .. seealso::
+        :func:`iter_identifiers`
+            Get an iterator over all identifier nodes in the expression, including
+            both :class:`~.expr.Var` and :class:`~.expr.Stretch` nodes.
     """
     yield from node.accept(_VAR_WALKER)
 
@@ -158,6 +163,10 @@ def iter_identifiers(node: expr.Expr) -> typing.Iterator[typing.Union[expr.Var,
             for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)):
                 if isinstance(node.var, ClassicalRegister):
                     print(node.var.name)
+
+    .. seealso::
+        :func:`iter_vars`
+            Get an iterator over just the :class:`~.expr.Var` nodes in the expression.
     """
     yield from node.accept(_IDENT_WALKER)
 

qiskit/circuit/controlflow/builder.py

@@ -122,14 +122,14 @@ def add_uninitialized_var(self, var: expr.Var):
         """
 
     @abc.abstractmethod
-    def add_stretch(self, var: expr.Stretch):
-        """Add a stretch variable to the circuit scope.
+    def add_stretch(self, stretch: expr.Stretch):
+        """Add a stretch to the circuit scope.
 
         Args:
-            var: the variable to add, if valid.
+            stretch: the stretch to add, if valid.
 
         Raises:
-            CircuitError: if the variable cannot be added, such as because it invalidly shadows or
+            CircuitError: if the stretch cannot be added, such as because it invalidly shadows or
                 redefines an existing name.
         """
 
@@ -146,14 +146,14 @@ def remove_var(self, var: expr.Var):
         """
 
     @abc.abstractmethod
-    def remove_stretch(self, var: expr.Stretch):
-        """Remove a stretch variable from the locals of this scope.
+    def remove_stretch(self, stretch: expr.Stretch):
+        """Remove a stretch from the locals of this scope.
 
-        This is only called in the case that an exception occurred while initializing the variable,
+        This is only called in the case that an exception occurred while initializing the stretch,
         and is not exposed to users.
 
         Args:
-            var: the variable to remove.  It can be assumed that this was already the subject of an
+            stretch: the stretch to remove.  It can be assumed that this was already the subject of an
                 :meth:`add_stretch` call.
         """
 
@@ -169,25 +169,19 @@ def use_var(self, var: expr.Var):
         Args:
             var: the variable to validate.
 
-        Returns:
-            the same variable.
-
         Raises:
             CircuitError: if the variable is not valid for this scope.
         """
 
     @abc.abstractmethod
-    def use_stretch(self, var: expr.Stretch):
-        """Called for every stretch variable being used by some circuit instruction.
+    def use_stretch(self, stretch: expr.Stretch):
+        """Called for every stretch being used by some circuit instruction.
 
         Args:
-            var: the variable to validate.
-
-        Returns:
-            the same variable.
+            stretch: the stretch to validate.
 
         Raises:
-            CircuitError: if the variable is not valid for this scope.
+            CircuitError: if the stretch is not valid for this scope.
         """
 
     @abc.abstractmethod
@@ -206,16 +200,16 @@ def get_var(self, name: str) -> Optional[expr.Var]:
 
     @abc.abstractmethod
     def get_stretch(self, name: str) -> Optional[expr.Stretch]:
-        """Get the stretch variable (if any) in scope with the given name.
+        """Get the stretch (if any) in scope with the given name.
 
         This should call up to the parent scope if in a control-flow builder scope, in case the
-        variable exists in an outer scope.
+        stretch exists in an outer scope.
 
         Args:
             name: the name of the symbol to lookup.
 
         Returns:
-            the stretch variable if it is found, otherwise ``None``.
+            the stretch if it is found, otherwise ``None``.
         """
 
     @abc.abstractmethod
@@ -514,30 +508,36 @@ def add_uninitialized_var(self, var: expr.Var):
             raise CircuitError(f"cannot add '{var}' as its name shadows the existing '{previous}'")
         self._vars_local[var.name] = var
 
-    def add_stretch(self, var: expr.Stretch):
+    def add_stretch(self, stretch: expr.Stretch):
         if self._built:
             raise CircuitError("Cannot add resources after the scope has been built.")
         # We can shadow a name if it was declared in an outer scope, but only if we haven't already
         # captured it ourselves yet.
-        if (previous := self._vars_local.get(var.name)) is not None:
-            raise CircuitError(f"cannot add '{var}' as its name shadows the existing '{previous}'")
-        if (previous := self._stretches_local.get(var.name)) is not None:
-            if previous == var:
-                raise CircuitError(f"'{var}' is already present in the scope")
-            raise CircuitError(f"cannot add '{var}' as its name shadows the existing '{previous}'")
-        if var.name in self._vars_capture or var.name in self._stretches_capture:
-            raise CircuitError(f"cannot add '{var}' as its name shadows the existing '{previous}'")
-        self._stretches_local[var.name] = var
+        if (previous := self._vars_local.get(stretch.name)) is not None:
+            raise CircuitError(
+                f"cannot add '{stretch}' as its name shadows the existing '{previous}'"
+            )
+        if (previous := self._stretches_local.get(stretch.name)) is not None:
+            if previous == stretch:
+                raise CircuitError(f"'{stretch}' is already present in the scope")
+            raise CircuitError(
+                f"cannot add '{stretch}' as its name shadows the existing '{previous}'"
+            )
+        if stretch.name in self._vars_capture or stretch.name in self._stretches_capture:
+            raise CircuitError(
+                f"cannot add '{stretch}' as its name shadows the existing '{previous}'"
+            )
+        self._stretches_local[stretch.name] = stretch
 
     def remove_var(self, var: expr.Var):
         if self._built:
             raise RuntimeError("exception handler 'remove_var' called after scope built")
         self._vars_local.pop(var.name)
 
-    def remove_stretch(self, var: expr.Stretch):
+    def remove_stretch(self, stretch: expr.Stretch):
         if self._built:
             raise RuntimeError("exception handler 'remove_stretch' called after scope built")
-        self._stretches_local.pop(var.name)
+        self._stretches_local.pop(stretch.name)
 
     def get_var(self, name: str):
         if (out := self._vars_local.get(name)) is not None:
@@ -563,19 +563,19 @@ def use_var(self, var: expr.Var):
         self._parent.use_var(var)
         self._vars_capture[var.name] = var
 
-    def use_stretch(self, var: expr.Stretch):
-        if (local := self._vars_local.get(var.name)) is not None:
-            raise CircuitError(f"cannot use '{var}' which is shadowed by the local '{local}'")
-        if (local := self._stretches_local.get(var.name)) is not None:
-            if local == var:
+    def use_stretch(self, stretch: expr.Stretch):
+        if (local := self._vars_local.get(stretch.name)) is not None:
+            raise CircuitError(f"cannot use '{stretch}' which is shadowed by the local '{local}'")
+        if (local := self._stretches_local.get(stretch.name)) is not None:
+            if local == stretch:
                 return
-            raise CircuitError(f"cannot use '{var}' which is shadowed by the local '{local}'")
-        if self._stretches_capture.get(var.name) == var:
+            raise CircuitError(f"cannot use '{stretch}' which is shadowed by the local '{local}'")
+        if self._stretches_capture.get(stretch.name) == stretch:
             return
-        if self._parent.get_stretch(var.name) != var:
-            raise CircuitError(f"cannot close over '{var}', which is not in scope")
-        self._parent.use_stretch(var)
-        self._stretches_capture[var.name] = var
+        if self._parent.get_stretch(stretch.name) != stretch:
+            raise CircuitError(f"cannot close over '{stretch}', which is not in scope")
+        self._parent.use_stretch(stretch)
+        self._stretches_capture[stretch.name] = stretch
 
     def use_qubit(self, qubit: Qubit):
         self._instructions.add_qubit(qubit, strict=False)
@@ -585,15 +585,15 @@ def iter_local_vars(self):
         return self._vars_local.values()
 
     def iter_local_stretches(self):
-        """Iterator over the stretch variables currently declared in this scope."""
+        """Iterator over the stretches currently declared in this scope."""
         return self._stretches_local.values()
 
     def iter_captured_vars(self):
         """Iterator over the variables currently captured in this scope."""
         return self._vars_capture.values()
 
     def iter_captured_stretches(self):
-        """Iterator over the stretch variables currently captured in this scope."""
+        """Iterator over the stretches currently captured in this scope."""
         return self._stretches_capture.values()
 
     def peek(self) -> CircuitInstruction: