Add PEP 484 type hints to transpiler analysis and utility passes (#15832)

* docs: add PEP 484 type hints to transpiler analysis and utility passes

Add `from __future__ import annotations` and PEP 484 type annotations to all 9 analysis passes (CountOps, Depth, Size, Width, NumQubits, NumTensorFactors, CountOpsLongestPath, DAGLongestPath, ResourceEstimation) and 3 utility passes (DAGFixedPoint, FixedPoint, ContainsInstruction).

Changes include:

- Type-annotate __init__ parameters and run() method signatures with DAGCircuit, bool, str, and -> None return types

- Expand sparse docstrings with Args blocks where missing

- Fix copy-paste module docstring in contains_instruction.py (was incorrectly 'Check if a property reached a fixed point')

- Rename placeholder parameter '_' to 'dag' in ResourceEstimation.run() for clarity

* Refactor import statements in count_ops.py

* Refactor imports and update docstring formatting

* Refactor import statements and update docstring

* Refactor imports and update docstring formatting

* Refactor import statement for TYPE_CHECKING

* Apply suggestion from @Cryoris

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* Refactor imports and docstring formatting

* Refactor import statements and docstring formatting

* Refactor imports and update docstring format

* Refactor import statements in width.py

* Update instruction_name type to Iterable in ContainsInstruction

* Update dag_fixed_point.py

* Refactor imports and docstrings in fixed_point.py

* Add copyright notice and docstring to count_ops.py

* Add docstring for counting operations in DAGCircuit

* Add type checking for DAGCircuit import

* Add copyright notice and docstring to depth.py

* Add copyright notice and docstring to num_qubits.py

* Import DAGCircuit for type checking

Add import statement for DAGCircuit in num_tensor_factors.py

* Update resource_estimation.py for type checking

* Add copyright notice and docstring to size.py

* Update width.py

* Update copyright notice in contains_instruction.py

* Update copyright notice in dag_fixed_point.py

* Add copyright notice and docstring to fixed_point.py

* Update fixed point tracking in DAG utility

* Fix fixed point property update logic

* Remove unnecessary blank line in fixed_point.py

* Remove unnecessary blank line in dag_fixed_point.py

* fix: use from __future__ import annotations with TYPE_CHECKING guard

Add from __future__ import annotations to all 12 files so that
type hints are treated as strings at runtime (fixing Python 3.10
NameError). Keep TYPE_CHECKING guard for DAGCircuit import to
satisfy ruff F821. This matches the pattern used in basepasses.py
and layout.py.

Also fixes contains_instruction.py module docstring (was copy-paste
from fixed_point.py).

---------

Co-authored-by: Julien Gacon <gaconju@gmail.com>

Author: Hadar01

qiskit/transpiler/passes/analysis/count_ops.py

@@ -12,6 +12,13 @@
 
 """Count the operations in a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -21,10 +28,15 @@ class CountOps(AnalysisPass):
     The result is saved in ``property_set['count_ops']`` as an integer.
     """
 
-    def __init__(self, *, recurse=True):
+    def __init__(self, *, recurse: bool = True) -> None:
+        """
+        Args:
+            recurse: If ``True`` (default), recursively count operations
+                inside control-flow blocks.
+        """
         super().__init__()
         self.recurse = recurse
 
-    def run(self, dag):
-        """Run the CountOps pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the CountOps pass on ``dag``."""
         self.property_set["count_ops"] = dag.count_ops(recurse=self.recurse)

qiskit/transpiler/passes/analysis/count_ops_longest_path.py

@@ -12,6 +12,13 @@
 
 """Count the operations on the longest path in a DAGCircuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -21,6 +28,6 @@ class CountOpsLongestPath(AnalysisPass):
     The result is saved in ``property_set['count_ops_longest_path']`` as an integer.
     """
 
-    def run(self, dag):
-        """Run the CountOpsLongestPath pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the CountOpsLongestPath pass on ``dag``."""
         self.property_set["count_ops_longest_path"] = dag.count_ops_longest_path()

qiskit/transpiler/passes/analysis/dag_longest_path.py

@@ -12,13 +12,20 @@
 
 """Return the longest path in a :class:`.DAGCircuit` as a list of DAGNodes."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
 class DAGLongestPath(AnalysisPass):
     """Return the longest path in a :class:`.DAGCircuit` as a list of
     :class:`.DAGOpNode`\\ s, :class:`.DAGInNode`\\ s, and :class:`.DAGOutNode`\\ s."""
 
-    def run(self, dag):
-        """Run the DAGLongestPath pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the DAGLongestPath pass on ``dag``."""
         self.property_set["dag_longest_path"] = dag.longest_path()

qiskit/transpiler/passes/analysis/depth.py

@@ -12,13 +12,20 @@
 
 """Calculate the depth of a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
 class Depth(AnalysisPass):
     """Calculate the depth of a DAG circuit."""
 
-    def __init__(self, *, recurse=False):
+    def __init__(self, *, recurse: bool = False) -> None:
         """
         Args:
             recurse: whether to allow recursion into control flow.  If this is ``False`` (default),
@@ -28,6 +35,6 @@ def __init__(self, *, recurse=False):
         super().__init__()
         self.recurse = recurse
 
-    def run(self, dag):
-        """Run the Depth pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the Depth pass on ``dag``."""
         self.property_set["depth"] = dag.depth(recurse=self.recurse)

qiskit/transpiler/passes/analysis/num_qubits.py

@@ -12,6 +12,13 @@
 
 """Calculate the number of qubits of a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -21,6 +28,6 @@ class NumQubits(AnalysisPass):
     The result is saved in ``property_set['num_qubits']`` as an integer.
     """
 
-    def run(self, dag):
-        """Run the NumQubits pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the NumQubits pass on ``dag``."""
         self.property_set["num_qubits"] = dag.num_qubits()

qiskit/transpiler/passes/analysis/num_tensor_factors.py

@@ -12,6 +12,13 @@
 
 """Calculate the number of tensor factors of a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -21,6 +28,6 @@ class NumTensorFactors(AnalysisPass):
     The result is saved in ``property_set['num_tensor_factors']`` as an integer.
     """
 
-    def run(self, dag):
-        """Run the NumTensorFactors pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the NumTensorFactors pass on ``dag``."""
         self.property_set["num_tensor_factors"] = dag.num_tensor_factors()

qiskit/transpiler/passes/analysis/resource_estimation.py

@@ -12,6 +12,13 @@
 
 """Automatically require analysis passes for resource estimation."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 from qiskit.transpiler.passes.analysis.depth import Depth
 from qiskit.transpiler.passes.analysis.width import Width
@@ -25,16 +32,18 @@ class ResourceEstimation(AnalysisPass):
     """Automatically require analysis passes for resource estimation.
 
     An analysis pass for automatically running:
+
     * Depth()
     * Width()
     * Size()
     * CountOps()
     * NumTensorFactors()
+    * NumQubits()
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
         self.requires += [Depth(), Width(), Size(), CountOps(), NumTensorFactors(), NumQubits()]
 
-    def run(self, _):
-        """Run the ResourceEstimation pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the ResourceEstimation pass on ``dag``."""

qiskit/transpiler/passes/analysis/size.py

@@ -12,6 +12,13 @@
 
 """Calculate the size of a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -21,7 +28,7 @@ class Size(AnalysisPass):
     The result is saved in ``property_set['size']`` as an integer.
     """
 
-    def __init__(self, *, recurse=False):
+    def __init__(self, *, recurse: bool = False) -> None:
         """
         Args:
             recurse: whether to allow recursion into control flow.  If this is ``False`` (default),
@@ -31,6 +38,6 @@ def __init__(self, *, recurse=False):
         super().__init__()
         self.recurse = recurse
 
-    def run(self, dag):
-        """Run the Size pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the Size pass on ``dag``."""
         self.property_set["size"] = dag.size(recurse=self.recurse)

qiskit/transpiler/passes/analysis/width.py

@@ -12,6 +12,13 @@
 
 """Calculate the width of a DAG circuit."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 from qiskit.transpiler.basepasses import AnalysisPass
 
 
@@ -22,6 +29,6 @@ class Width(AnalysisPass):
     contains the number of qubits + the number of clbits.
     """
 
-    def run(self, dag):
-        """Run the Width pass on `dag`."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the Width pass on ``dag``."""
         self.property_set["width"] = dag.width()

qiskit/transpiler/passes/utils/contains_instruction.py

@@ -10,7 +10,15 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Check if a property reached a fixed point."""
+"""Check if the DAG contains a specific instruction."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
 
 from qiskit.transpiler.basepasses import AnalysisPass
 
@@ -23,23 +31,22 @@ class ContainsInstruction(AnalysisPass):
     that instruction and ``False`` if it does not.
     """
 
-    def __init__(self, instruction_name, recurse: bool = True):
-        """ContainsInstruction initializer.
-
+    def __init__(self, instruction_name: str | Iterable[str], recurse: bool = True) -> None:
+        """
         Args:
-            instruction_name (str | Iterable[str]): The instruction or instructions to check are in
+            instruction_name: The instruction or instructions to check are in
                 the DAG. The output in the property set is set to ``contains_`` prefixed on each
                 value for this parameter.
-            recurse (bool): if ``True`` (default), then recurse into control-flow operations.
+            recurse: if ``True`` (default), then recurse into control-flow operations.
         """
         super().__init__()
         self._instruction_names = (
             {instruction_name} if isinstance(instruction_name, str) else set(instruction_name)
         )
         self._recurse = recurse
 
-    def run(self, dag):
-        """Run the ContainsInstruction pass on dag."""
+    def run(self, dag: DAGCircuit) -> None:
+        """Run the ContainsInstruction pass on ``dag``."""
         names = dag.count_ops(recurse=self._recurse)
         for name in self._instruction_names:
             self.property_set[f"contains_{name}"] = name in names