如何在Python中注解str类型或含__str__方法的对象？

要给这类参数添加精确的类型注解，Python标准库提供了专门的类型协议来匹配可被str()转换为有效字符串的对象：

推荐写法（Python 3.9+） #

使用typing.SupportsStr（Python 3.10+可直接用collections.abc.SupportsStr），它专门标记实现了__str__()方法的对象——这类对象都能被str()正确转换为字符串：

from typing import SupportsStr

def SomeFunc(param: str | SupportsStr) -> None:
    # 函数逻辑示例
    print(str(param))

备选简化写法（如果不需要严格静态检查） #

如果对类型精确性要求不高，也可以用str | object，但这会包含所有Python对象（因为所有对象都继承自object），不如SupportsStr能明确表达你的参数预期：

def SomeFunc(param: str | object) -> None:
    print(str(param))

关键说明 #

SupportsStr是静态类型检查工具（比如mypy、pyright）能识别的协议，它会验证对象是否拥有合法的__str__方法，完美匹配你“传入str()能返回有效字符串”的需求。

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