Consistent typehints for NLocal family (#10479) (#10507)

* consistent typehints

* lint

* attempt to fix docs 1/?

* fix accidental default change

* fix lint

* fix , instead of |

(cherry picked from commit eda570c)

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

qiskit/circuit/library/evolved_operator_ansatz.py

@@ -14,7 +14,6 @@
 
 from __future__ import annotations
 from collections.abc import Sequence
-from typing import Optional
 
 import numpy as np
 
@@ -41,7 +40,7 @@ def __init__(
         name: str = "EvolvedOps",
         parameter_prefix: str | Sequence[str] = "t",
         initial_state: QuantumCircuit | None = None,
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ):
         """
         Args:

qiskit/circuit/library/n_local/efficient_su2.py

@@ -12,13 +12,19 @@
 
 """The EfficientSU2 2-local circuit."""
 
-from typing import Union, Optional, List, Tuple, Callable, Any
+from __future__ import annotations
+import typing
+from collections.abc import Callable
+
 from numpy import pi
 
-from qiskit.circuit import QuantumCircuit, Instruction
+from qiskit.circuit import QuantumCircuit
 from qiskit.circuit.library.standard_gates import RYGate, RZGate, CXGate
 from .two_local import TwoLocal
 
+if typing.TYPE_CHECKING:
+    import qiskit  # pylint: disable=cyclic-import
+
 
 class EfficientSU2(TwoLocal):
     r"""The hardware efficient SU(2) 2-local circuit.
@@ -76,28 +82,24 @@ class EfficientSU2(TwoLocal):
 
     def __init__(
         self,
-        num_qubits: Optional[int] = None,
-        su2_gates: Optional[
-            Union[
-                str,
-                type,
-                Instruction,
-                QuantumCircuit,
-                List[Union[str, type, Instruction, QuantumCircuit]],
-            ]
-        ] = None,
-        entanglement: Union[str, List[List[int]], Callable[[int], List[int]]] = "reverse_linear",
+        num_qubits: int | None = None,
+        su2_gates: str
+        | type
+        | qiskit.circuit.Instruction
+        | QuantumCircuit
+        | list[str | type | qiskit.circuit.Instruction | QuantumCircuit]
+        | None = None,
+        entanglement: str | list[list[int]] | Callable[[int], list[int]] = "reverse_linear",
         reps: int = 3,
         skip_unentangled_qubits: bool = False,
         skip_final_rotation_layer: bool = False,
         parameter_prefix: str = "θ",
         insert_barriers: bool = False,
-        initial_state: Optional[Any] = None,
+        initial_state: QuantumCircuit | None = None,
         name: str = "EfficientSU2",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ) -> None:
-        """Create a new EfficientSU2 2-local circuit.
-
+        """
         Args:
             num_qubits: The number of qubits of the EfficientSU2 circuit.
             reps: Specifies how often the structure of a rotation layer followed by an entanglement
@@ -151,7 +153,7 @@ def __init__(
         )
 
     @property
-    def parameter_bounds(self) -> List[Tuple[float, float]]:
+    def parameter_bounds(self) -> list[tuple[float, float]]:
         """Return the parameter bounds.
 
         Returns:

qiskit/circuit/library/n_local/excitation_preserving.py

@@ -12,7 +12,8 @@
 
 """The ExcitationPreserving 2-local circuit."""
 
-from typing import Union, Optional, List, Tuple, Callable, Any
+from __future__ import annotations
+from collections.abc import Callable
 from numpy import pi
 
 from qiskit.circuit import QuantumCircuit, Parameter
@@ -90,20 +91,19 @@ class ExcitationPreserving(TwoLocal):
 
     def __init__(
         self,
-        num_qubits: Optional[int] = None,
+        num_qubits: int | None = None,
         mode: str = "iswap",
-        entanglement: Union[str, List[List[int]], Callable[[int], List[int]]] = "full",
+        entanglement: str | list[list[int]] | Callable[[int], list[int]] = "full",
         reps: int = 3,
         skip_unentangled_qubits: bool = False,
         skip_final_rotation_layer: bool = False,
         parameter_prefix: str = "θ",
         insert_barriers: bool = False,
-        initial_state: Optional[Any] = None,
+        initial_state: QuantumCircuit | None = None,
         name: str = "ExcitationPreserving",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ) -> None:
-        """Create a new ExcitationPreserving 2-local circuit.
-
+        """
         Args:
             num_qubits: The number of qubits of the ExcitationPreserving circuit.
             mode: Choose the entangler mode, can be `'iswap'` or `'fsim'`.
@@ -167,7 +167,7 @@ def __init__(
         )
 
     @property
-    def parameter_bounds(self) -> List[Tuple[float, float]]:
+    def parameter_bounds(self) -> list[tuple[float, float]]:
         """Return the parameter bounds.
 
         Returns:

qiskit/circuit/library/n_local/n_local.py

@@ -13,9 +13,9 @@
 """The n-local circuit class."""
 
 from __future__ import annotations
-
 import typing
-from typing import Union, Optional, Any, Sequence, Callable, Mapping
+from collections.abc import Callable, Mapping, Sequence
+
 from itertools import combinations
 
 import numpy
@@ -90,10 +90,9 @@ def __init__(
         skip_unentangled_qubits: bool = False,
         initial_state: QuantumCircuit | None = None,
         name: str | None = "nlocal",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ) -> None:
-        """Create a new n-local circuit.
-
+        """
         Args:
             num_qubits: The number of qubits of the circuit.
             rotation_blocks: The blocks used in the rotation layers. If multiple are passed,
@@ -123,9 +122,6 @@ def __init__(
                 to set this flag to ``True`` to avoid a large performance
                 overhead for parameter binding.
 
-        Examples:
-            TODO
-
         Raises:
             ValueError: If ``reps`` parameter is less than or equal to 0.
             TypeError: If ``reps`` parameter is not an int value.
@@ -207,7 +203,7 @@ def flatten(self, flatten: bool) -> None:
         self._invalidate()
         self._flatten = flatten
 
-    def _convert_to_block(self, layer: Any) -> QuantumCircuit:
+    def _convert_to_block(self, layer: typing.Any) -> QuantumCircuit:
         """Try to convert ``layer`` to a QuantumCircuit.
 
         Args:
@@ -289,17 +285,9 @@ def entanglement_blocks(
     @property
     def entanglement(
         self,
-    ) -> Union[
-        str,
-        list[str],
-        list[list[str]],
-        list[int],
-        list[list[int]],
-        list[list[list[int]]],
-        list[list[list[list[int]]]],
-        Callable[[int], str],
-        Callable[[int], list[list[int]]],
-    ]:
+    ) -> str | list[str] | list[list[str]] | list[int] | list[list[int]] | list[
+        list[list[int]]
+    ] | list[list[list[list[int]]]] | Callable[[int], str] | Callable[[int], list[list[int]]]:
         """Get the entanglement strategy.
 
         Returns:
@@ -311,19 +299,16 @@ def entanglement(
     @entanglement.setter
     def entanglement(
         self,
-        entanglement: Optional[
-            Union[
-                str,
-                list[str],
-                list[list[str]],
-                list[int],
-                list[list[int]],
-                list[list[list[int]]],
-                list[list[list[list[int]]]],
-                Callable[[int], str],
-                Callable[[int], list[list[int]]],
-            ]
-        ],
+        entanglement: str
+        | list[str]
+        | list[list[str]]
+        | list[int]
+        | list[list[int]]
+        | list[list[list[int]]]
+        | list[list[list[list[int]]]]
+        | Callable[[int], str]
+        | Callable[[int], list[list[int]]]
+        | None,
     ) -> None:
         """Set the entanglement strategy.
 
@@ -730,7 +715,7 @@ def parameter_bounds(self, bounds: list[tuple[float, float]]) -> None:
 
     def add_layer(
         self,
-        other: Union["NLocal", qiskit.circuit.Instruction, QuantumCircuit],
+        other: QuantumCircuit | qiskit.circuit.Instruction,
         entanglement: list[int] | str | list[list[int]] | None = None,
         front: bool = False,
     ) -> "NLocal":

qiskit/circuit/library/n_local/qaoa_ansatz.py

@@ -14,7 +14,6 @@
 
 # pylint: disable=cyclic-import
 from __future__ import annotations
-from typing import Optional
 
 import numpy as np
 
@@ -41,7 +40,7 @@ def __init__(
         initial_state: QuantumCircuit | None = None,
         mixer_operator=None,
         name: str = "QAOA",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ):
         r"""
         Args:

qiskit/circuit/library/n_local/real_amplitudes.py

@@ -12,9 +12,12 @@
 
 """The real-amplitudes 2-local circuit."""
 
-from typing import Union, Optional, List, Tuple, Callable, Any
+from __future__ import annotations
+from collections.abc import Callable
+
 import numpy as np
 
+from qiskit.circuit import QuantumCircuit
 from qiskit.circuit.library.standard_gates import RYGate, CXGate
 from .two_local import TwoLocal
 
@@ -115,19 +118,18 @@ class RealAmplitudes(TwoLocal):
 
     def __init__(
         self,
-        num_qubits: Optional[int] = None,
-        entanglement: Union[str, List[List[int]], Callable[[int], List[int]]] = "reverse_linear",
+        num_qubits: int | None = None,
+        entanglement: str | list[list[int]] | Callable[[int], list[int]] = "reverse_linear",
         reps: int = 3,
         skip_unentangled_qubits: bool = False,
         skip_final_rotation_layer: bool = False,
         parameter_prefix: str = "θ",
         insert_barriers: bool = False,
-        initial_state: Optional[Any] = None,
+        initial_state: QuantumCircuit | None = None,
         name: str = "RealAmplitudes",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ) -> None:
-        """Create a new RealAmplitudes 2-local circuit.
-
+        """
         Args:
             num_qubits: The number of qubits of the RealAmplitudes circuit.
             reps: Specifies how often the structure of a rotation layer followed by an entanglement
@@ -178,7 +180,7 @@ def __init__(
         )
 
     @property
-    def parameter_bounds(self) -> List[Tuple[float, float]]:
+    def parameter_bounds(self) -> list[tuple[float, float]]:
         """Return the parameter bounds.
 
         Returns:

qiskit/circuit/library/n_local/two_local.py

@@ -13,7 +13,8 @@
 """The two-local gate circuit."""
 
 from __future__ import annotations
-from typing import Union, Optional, List, Callable, Any, Sequence
+import typing
+from collections.abc import Callable, Sequence
 
 from qiskit.circuit.quantumcircuit import QuantumCircuit
 from qiskit.circuit import Gate, Instruction, Parameter
@@ -46,6 +47,9 @@
     CHGate,
 )
 
+if typing.TYPE_CHECKING:
+    import qiskit  # pylint: disable=cyclic-import
+
 
 class TwoLocal(NLocal):
     r"""The two-local circuit.
@@ -158,25 +162,30 @@ class TwoLocal(NLocal):
 
     def __init__(
         self,
-        num_qubits: Optional[int] = None,
-        rotation_blocks: Optional[
-            Union[str, List[str], type, List[type], QuantumCircuit, List[QuantumCircuit]]
-        ] = None,
-        entanglement_blocks: Optional[
-            Union[str, List[str], type, List[type], QuantumCircuit, List[QuantumCircuit]]
-        ] = None,
-        entanglement: Union[str, List[List[int]], Callable[[int], List[int]]] = "full",
+        num_qubits: int | None = None,
+        rotation_blocks: str
+        | type
+        | qiskit.circuit.Instruction
+        | QuantumCircuit
+        | list[str | type | qiskit.circuit.Instruction | QuantumCircuit]
+        | None = None,
+        entanglement_blocks: str
+        | type
+        | qiskit.circuit.Instruction
+        | QuantumCircuit
+        | list[str | type | qiskit.circuit.Instruction | QuantumCircuit]
+        | None = None,
+        entanglement: str | list[list[int]] | Callable[[int], list[int]] = "full",
         reps: int = 3,
         skip_unentangled_qubits: bool = False,
         skip_final_rotation_layer: bool = False,
         parameter_prefix: str = "θ",
         insert_barriers: bool = False,
-        initial_state: Optional[Any] = None,
+        initial_state: QuantumCircuit | None = None,
         name: str = "TwoLocal",
-        flatten: Optional[bool] = None,
+        flatten: bool | None = None,
     ) -> None:
-        """Construct a new two-local circuit.
-
+        """
         Args:
             num_qubits: The number of qubits of the two-local circuit.
             rotation_blocks: The gates used in the rotation layer. Can be specified via the name of
@@ -233,7 +242,7 @@ def __init__(
             flatten=flatten,
         )
 
-    def _convert_to_block(self, layer: Union[str, type, Gate, QuantumCircuit]) -> QuantumCircuit:
+    def _convert_to_block(self, layer: str | type | Gate | QuantumCircuit) -> QuantumCircuit:
         """For a layer provided as str (e.g. ``'ry'``) or type (e.g. :class:`.RYGate`) this function
          returns the
          according layer type along with the number of parameters (e.g. ``(RYGate, 1)``).