如何为兼容Python3.9的_pairwise函数添加正确类型提示？

我维护一个最低支持Python3.9的代码库，需要给_pairwise函数添加准确的类型提示，原实现及遇到的问题如下：

原函数实现：

from typing import TypeVar
import itertools

T = TypeVar('T')

def _pairwise(iterable: T.Iterable, end=None) -> T.Iterable:
    left, right = itertools.tee(iterable)
    next(right, None)
    return itertools.zip_longest(left, right, fillvalue=end)

这个函数用于遍历正则匹配结果，提取起止索引进行切片，最后用end（默认None）填充，让最后一个切片能延伸至字符串末尾。

根据函数逻辑，它的实际类型签名应该是：

_pairwise(iterable: Iterable[T], end: Optional[T] = None) -> Iterator[tuple[T, Optional[T]]]

因为left的长度必然大于等于right，返回元组的第一个元素一定是T类型，第二个才可能是Optional[T]。但使用zip_longest的实现无法让类型检查器（如pyright）识别该签名，会被判定为Iterator[tuple[Optional[T], Optional[T]]]。

我自己重写了一个能通过类型检查的版本，但存在几个不满意的点：

from typing import Iterable, Iterator, Optional, TypeVar
import itertools

T = TypeVar('T')

def _pairwise(
    iterable: Iterable[T], end: Optional[T] = None
) -> Iterator[tuple[T, Optional[T]]]:
    left, right = itertools.tee(iterable)
    next(right, None)
    for x, y in zip(right, left):
        yield y, x
    if (last := next(left, None)) is not None:
        yield last, end

• 必须交换zip的参数才能避免left多走一步，逻辑不够直观；
• 需要手动处理空可迭代对象的情况；
• 当T为NoneType时，功能不符合预期（虽实际使用无问题，但不够严谨）。

解决方案1：使用类型断言 #

保留原zip_longest的简洁实现，通过类型断言直接告知类型检查器返回值的准确类型，这是最贴近原代码逻辑的方案：

from typing import Iterable, Iterator, Optional, TypeVar, cast
import itertools

T = TypeVar('T')

def _pairwise(iterable: Iterable[T], end: Optional[T] = None) -> Iterator[tuple[T, Optional[T]]]:
    left, right = itertools.tee(iterable)
    next(right, None)
    return cast(Iterator[tuple[T, Optional[T]]], itertools.zip_longest(left, right, fillvalue=end))

优点：完全保留原实现的简洁性，核心逻辑不变，无需额外处理边界情况。
缺点：依赖类型断言，若后续核心逻辑变更，需同步更新断言，否则类型提示会失效。

解决方案2：生成器包装+断言校验 #

保持原zip_longest的核心逻辑，用生成器遍历结果并通过断言明确第一个元素的类型，让类型检查器能正确推导：

from typing import Iterable, Iterator, Optional, TypeVar
import itertools

T = TypeVar('T')

def _pairwise(iterable: Iterable[T], end: Optional[T] = None) -> Iterator[tuple[T, Optional[T]]]:
    left, right = itertools.tee(iterable)
    next(right, None)
    for x, y in itertools.zip_longest(left, right, fillvalue=end):
        assert x is not None, "left iterator must have at least as many elements as right"
        yield x, y

优点：核心逻辑不变，断言既帮助类型检查器推导类型，又能在运行时做正确性校验，提前发现逻辑错误。
缺点：多了一层生成器遍历，存在微小性能损耗（多数场景可忽略）。

解决方案3：重载处理NoneType场景 #

如果在意T为NoneType时的类型准确性，可以通过函数重载优化类型提示：

from typing import Iterable, Iterator, Optional, TypeVar, overload
import itertools

T = TypeVar('T')
T_non_none = TypeVar('T_non_none', bound=object)

@overload
def _pairwise(iterable: Iterable[T_non_none], end: Optional[T_non_none] = None) -> Iterator[tuple[T_non_none, Optional[T_non_none]]]:
    ...

@overload
def _pairwise(iterable: Iterable[None], end: None = None) -> Iterator[tuple[None, None]]:
    ...

def _pairwise(iterable, end=None):
    left, right = itertools.tee(iterable)
    next(right, None)
    yield from itertools.zip_longest(left, right, fillvalue=end)

优点：针对NoneType的输入给出更精准的类型提示，避免类型歧义。
缺点：增加了重载逻辑，代码复杂度提升，对不需要严格区分NoneType的场景来说略显冗余。

内容的提问来源于stack exchange，提问作者J.N.