PyArrow类型存根缺失时，函数重载无法匹配Any类型分支的问题

我明白你的需求了——你想让函数的类型提示在有pyarrow-stubs时精准识别pyarrow.Array并返回int，没有存根时则回退到int | str，而不是返回Any。你的原代码问题在于，当没有存根时，pa.array(...)会被类型检查器识别为Any，但它会优先匹配你定义的PyArrowArray协议重载（因为Any兼容任何协议类型），但由于协议的匹配在无存根时是模糊的，最终导致类型推断成了Any。

我们可以通过条件定义重载的方式来解决这个问题：只有当检测到pyarrow-stubs存在时，才添加针对PyArrow数组的重载分支；否则直接让PyArrow数组的情况回落到Any的重载分支，这样就能得到你想要的int | str类型提示。

修改后的代码如下：

from typing import overload, TYPE_CHECKING, Protocol, Any

# 在类型检查阶段检测pyarrow-stubs是否安装
if TYPE_CHECKING:
    try:
        # 尝试导入存根包来确认其存在
        import pyarrow_stubs  # type: ignore[import]
        HAS_PYARROW_STUBS = True
    except ImportError:
        HAS_PYARROW_STUBS = False

import pyarrow as pa  # type: ignore[import-not-found]

if TYPE_CHECKING and HAS_PYARROW_STUBS:
    # 仅当有存根时，定义匹配pyarrow.Array的协议
    class PyArrowArray(Protocol):
        @property
        def buffers(self) -> Any: ...

# 基础重载分支：处理字符串输入
@overload
def func(a: str) -> str: ...

if TYPE_CHECKING and HAS_PYARROW_STUBS:
    # 仅当有存根时，添加PyArrow数组的重载分支
    @overload
    def func(a: PyArrowArray) -> int: ...

# 兜底重载分支：处理所有其他类型（包括无存根时的PyArrow数组）
@overload
def func(a: Any) -> str | int: ...

def func(a) -> str | int:
    if isinstance(a, pa.Array):
        return 0
    return '0'

reveal_type(func(pa.array([1,2,3])))

代码工作原理说明： #

1. 类型检查时的存根检测：我们在TYPE_CHECKING块里尝试导入pyarrow_stubs，以此判断用户是否安装了存根包——这个判断只在类型检查阶段运行，不会影响代码的实际执行。
2. 条件重载定义：
   • 当有pyarrow-stubs时，我们定义PyArrowArray协议，并添加对应的重载分支，类型检查器会识别pa.array(...)符合这个协议，从而推断返回类型为int。
   • 当没有存根时，这个PyArrow专属的重载分支不会被定义，pa.array(...)会被识别为Any，进而匹配到最后的兜底重载分支，返回类型就是int | str。
3. 运行时无额外开销：所有的类型检查逻辑都在TYPE_CHECKING块里，运行时不会产生额外的导入开销或条件判断。

另外，你原代码里的# type: ignore[import-not-found]保留是合理的，这样即使用户没有安装PyArrow，代码也能通过类型检查（当然运行时还是会报错，但这符合函数本身依赖PyArrow运行时的逻辑）。

备注：内容来源于stack exchange，提问作者ignoring_gravity