PyLance严格模式下如何为NetworkX代码添加类型断言消除警告

在Python 3.11 + VS Code + PyLance严格模式环境中，以下NetworkX代码触发三类类型警告：

from typing import List, Tuple
import networkx as nx

graph = nx.MultiDiGraph()

# .add_edge(source node, sink node, edge type)
graph.add_edge("node1", "node2", (0, 0))
graph.add_edge("node1", "node2", (0, 1))
graph.add_edge("node2", "node3", (0, 2))

triplets: List[Tuple[str, str, Tuple[int, int]]] = []
for u, v, e_type in graph.edges(keys=True):
    triplets.append((u, v, e_type))

警告内容：

• add_edge函数参数类型均为Unknown
• 循环变量u、v、e_type类型未知
• append方法接收tuple[Unknown, Unknown, Unknown]，类型不匹配

使用assert isinstance虽能缓解，但存在运行时开销，且无法直接检查e_type是否为Tuple[int, int]。以下是无需运行时开销、直接告知PyLance信任类型的方案：

方案1：给NetworkX实例添加泛型类型注解（最优） #

NetworkX的图类支持泛型参数，明确指定节点类型和边键类型后，PyLance能自动推断所有相关变量的类型，从根源消除警告：

from typing import List, Tuple
import networkx as nx

# 明确指定节点类型为str，边键类型为Tuple[int, int]
graph: nx.MultiDiGraph[str, Tuple[int, int]] = nx.MultiDiGraph()

graph.add_edge("node1", "node2", (0, 0))
graph.add_edge("node1", "node2", (0, 1))
graph.add_edge("node2", "node3", (0, 2))

triplets: List[Tuple[str, str, Tuple[int, int]]] = []
# 此时u、v、e_type的类型已被PyLance正确识别
for u, v, e_type in graph.edges(keys=True):
    triplets.append((u, v, e_type))

方案2：使用typing.cast做静态类型断言 #

cast仅作用于类型检查阶段，不会产生任何运行时开销，专门用于告知PyLance变量的实际类型：

from typing import List, Tuple, cast
import networkx as nx

graph = nx.MultiDiGraph()

graph.add_edge("node1", "node2", (0, 0))
graph.add_edge("node1", "node2", (0, 1))
graph.add_edge("node2", "node3", (0, 2))

triplets: List[Tuple[str, str, Tuple[int, int]]] = []
for u, v, e_type in graph.edges(keys=True):
    # 明确告知PyLance各变量的类型
    u_str = cast(str, u)
    v_str = cast(str, v)
    edge_type = cast(Tuple[int, int], e_type)
    triplets.append((u_str, v_str, edge_type))

方案3：用类型别名简化重复注解（可选） #

如果Tuple[int, int]多次出现，可以定义类型别名提升代码可读性：

from typing import List, Tuple, TypeAlias
import networkx as nx

# 定义边类型别名
EdgeType: TypeAlias = Tuple[int, int]

graph: nx.MultiDiGraph[str, EdgeType] = nx.MultiDiGraph()

graph.add_edge("node1", "node2", (0, 0))
graph.add_edge("node1", "node2", (0, 1))
graph.add_edge("node2", "node3", (0, 2))

triplets: List[Tuple[str, str, EdgeType]] = []
for u, v, e_type in graph.edges(keys=True):
    triplets.append((u, v, e_type))

内容的提问来源于stack exchange，提问作者Antoine