如何为接收AnyStr类型参数且默认值为str的函数添加类型注解？

一、正确的AnyStr默认参数注解方式 #

你遇到的报错本质是AnyStr的特性导致的：它是一个绑定到str和bytes的类型变量，当你给参数设置str类型的默认值时，mypy会担心如果函数以bytes类型调用（比如传入b"test"），默认值"."无法匹配bytes类型，因此抛出类型不兼容的错误。

解决这个问题的标准做法是使用函数重载，明确区分str和bytes两种场景的签名：

from typing import AnyStr, overload

@overload
def func(s: str = ".") -> str:
    ...

@overload
def func(s: bytes) -> bytes:
    ...

def func(s: AnyStr = ".") -> AnyStr:
    return s

这种写法的优势很明显：

• 当不传入参数（使用默认值）或传入str时，mypy会精准推断返回类型为str
• 当传入bytes时，自动匹配到对应的重载签名，返回类型为bytes
• 完全贴合AnyStr的设计意图，同时彻底解决了默认值的类型冲突问题

如果你觉得重载有点繁琐，也可以用Union结合Literal的写法，但重载的方式在类型推断上更精准，也更符合Python类型注解的最佳实践：

from typing import AnyStr, Literal, Union

def func(s: Union[AnyStr, Literal["."]] = ".") -> AnyStr:
    return s

二、解决拆分.py和.pyi文件后的类型检查失效问题 #

拆分文件后mypy没检查func(42)的调用，大概率是以下几个原因之一：

1. 文件名不匹配 #

确保.py和.pyi文件的文件名完全一致（比如func.py对应func.pyi），并且放在同一个目录下。mypy会自动关联同名的实现文件和类型签名文件，读取.pyi的签名来检查.py里的代码逻辑和外部调用。

2. 未指定检查包含调用的文件 #

如果你只运行mypy func.pyi，mypy只会校验类型签名本身，不会检查.py文件里的调用代码。你需要在运行mypy时指定包含调用逻辑的文件，比如：

mypy your_script.py func.py

或者直接检查整个项目目录，让mypy自动扫描所有相关文件：

mypy .

3. mypy配置存在排除规则 #

检查你的mypy.ini（或pyproject.toml）配置文件，确保没有将你的函数文件或调用文件加入到exclude排除列表中，否则mypy会跳过这些文件的检查。

另外，要保证.pyi的签名和.py的实现逻辑一致：比如.py里函数的参数数量、名称要和.pyi完全对应，.pyi中用...表示默认值是允许的，只要.py里的默认值符合签名逻辑即可。

举个正确的拆分示例：

• .py文件：

def func(s = "."):
    return s

• .pyi文件：

from typing import AnyStr, overload

@overload
def func(s: str = ".") -> str: ...

@overload
def func(s: bytes) -> bytes: ...

def func(s: AnyStr = ...) -> AnyStr: ...

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