transpile: narrow the return type depending on the circuits argument

qiskit/compiler/transpiler.py

@@ -20,7 +20,7 @@
 import pickle
 import sys
 from time import time
-from typing import List, Union, Dict, Callable, Any, Optional, Tuple, Iterable
+from typing import List, Union, Dict, Callable, Any, Optional, Tuple, Iterable, overload
 import warnings
 
 from qiskit import user_config
@@ -58,6 +58,70 @@
 logger = logging.getLogger(__name__)
 
 
+@overload
+def transpile(
+    circuits: QuantumCircuit,
+    backend: Optional[Backend] = ...,
+    basis_gates: Optional[List[str]] = ...,
+    inst_map: Optional[List[InstructionScheduleMap]] = ...,
+    coupling_map: Optional[Union[CouplingMap, List[List[int]]]] = ...,
+    backend_properties: Optional[BackendProperties] = ...,
+    initial_layout: Optional[Union[Layout, Dict, List]] = ...,
+    layout_method: Optional[str] = ...,
+    routing_method: Optional[str] = ...,
+    translation_method: Optional[str] = ...,
+    scheduling_method: Optional[str] = ...,
+    instruction_durations: Optional[InstructionDurationsType] = ...,
+    dt: Optional[float] = ...,
+    approximation_degree: Optional[float] = ...,
+    timing_constraints: Optional[Dict[str, int]] = ...,
+    seed_transpiler: Optional[int] = ...,
+    optimization_level: Optional[int] = ...,
+    callback: Optional[Callable[[BasePass, DAGCircuit, float, PropertySet, int], Any]] = ...,
+    output_name: Optional[Union[str, List[str]]] = ...,
+    unitary_synthesis_method: str = ...,
+    unitary_synthesis_plugin_config: Optional[dict] = ...,
+    target: Optional[Target] = ...,
+    hls_config: Optional[HLSConfig] = ...,
+    init_method: Optional[str] = ...,
+    optimization_method: Optional[str] = ...,
+    ignore_backend_supplied_default_methods: bool = ...,
+) -> QuantumCircuit:
+    ...
+
+
+@overload
+def transpile(
+    circuits: List[QuantumCircuit],
+    backend: Optional[Backend] = ...,
+    basis_gates: Optional[List[str]] = ...,
+    inst_map: Optional[List[InstructionScheduleMap]] = ...,
+    coupling_map: Optional[Union[CouplingMap, List[List[int]]]] = ...,
+    backend_properties: Optional[BackendProperties] = ...,
+    initial_layout: Optional[Union[Layout, Dict, List]] = ...,
+    layout_method: Optional[str] = ...,
+    routing_method: Optional[str] = ...,
+    translation_method: Optional[str] = ...,
+    scheduling_method: Optional[str] = ...,
+    instruction_durations: Optional[InstructionDurationsType] = ...,
+    dt: Optional[float] = ...,
+    approximation_degree: Optional[float] = ...,
+    timing_constraints: Optional[Dict[str, int]] = ...,
+    seed_transpiler: Optional[int] = ...,
+    optimization_level: Optional[int] = ...,
+    callback: Optional[Callable[[BasePass, DAGCircuit, float, PropertySet, int], Any]] = ...,
+    output_name: Optional[Union[str, List[str]]] = ...,
+    unitary_synthesis_method: str = ...,
+    unitary_synthesis_plugin_config: Optional[dict] = ...,
+    target: Optional[Target] = ...,
+    hls_config: Optional[HLSConfig] = ...,
+    init_method: Optional[str] = ...,
+    optimization_method: Optional[str] = ...,
+    ignore_backend_supplied_default_methods: bool = ...,
+) -> List[QuantumCircuit]:
+    ...
+
+
 def transpile(
     circuits: Union[QuantumCircuit, List[QuantumCircuit]],
     backend: Optional[Backend] = None,
@@ -79,11 +143,11 @@ def transpile(
     callback: Optional[Callable[[BasePass, DAGCircuit, float, PropertySet, int], Any]] = None,
     output_name: Optional[Union[str, List[str]]] = None,
     unitary_synthesis_method: str = "default",
-    unitary_synthesis_plugin_config: dict = None,
-    target: Target = None,
+    unitary_synthesis_plugin_config: Optional[dict] = None,
+    target: Optional[Target] = None,
     hls_config: Optional[HLSConfig] = None,
-    init_method: str = None,
-    optimization_method: str = None,
+    init_method: Optional[str] = None,
+    optimization_method: Optional[str] = None,
     ignore_backend_supplied_default_methods: bool = False,
 ) -> Union[QuantumCircuit, List[QuantumCircuit]]:
     """Transpile one or more circuits, according to some desired transpilation targets.

releasenotes/notes/improve-transpile-typing-de1197f4dd13ac0c.yaml

@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    Improved the typing annotations on the top-level `transpile` function.
+    The return type is now narrowed correctly depending on the whether a
+    single circuit or a list of circuit was passed.