如何为类方法装饰器的self参数添加类型标注并避免循环导入

方案合规性说明 #

你目前使用的字符串形式前向标注完全符合Python类型标注规范，是PEP 484明确支持的语法，专门用于解决循环导入、类型定义晚于标注使用场景的类型标注问题，运行时不会解析字符串标注内容，类型检查器（如mypy、pyright）和主流代码编辑器都可以正常识别该标注，满足你补全类属性、限制装饰器适用范围的需求。

更优实现方案 #

推荐使用「类型检查时延迟导入+自动字符串标注」的组合方案，完全避免运行时循环导入风险，代码可读性也更高：

1. 首先在decorators.py开头开启自动字符串标注特性（Python 3.7+支持），并使用TYPE_CHECKING常量实现仅类型检查阶段导入目标类：

# decorators.py
from __future__ import annotations
import functools
from typing import Callable, TypeVar, TYPE_CHECKING

# 仅类型检查阶段导入，运行时不会执行，完全规避循环导入
if TYPE_CHECKING:
    from someclass import SomeClass

# 绑定类型变量，支持SomeClass及其子类的方法适配
T = TypeVar("T", bound="SomeClass")

def something_todo(f: Callable[[T, ...], object]) -> Callable[[T, ...], object]:
    @functools.wraps(f)
    def decorator(self: T, *args, **kwargs):
        # do something
        return f(self, *args, **kwargs)
    return decorator

2. 该方案的优势：

• 无需手动给类型标注加引号，代码写法和普通标注完全一致，可读性更高
• 运行时不会导入someclass模块，从根源避免循环导入问题，也不会污染当前模块的命名空间
• 对装饰器入参也添加了类型限制，类型检查器会直接阻止该装饰器被应用到非SomeClass及其子类的方法上，约束能力更强
• 编辑器可以正常识别self的类型，支持类属性、方法的自动补全，无需跳转查看类定义

如果你的项目仅支持Python 3.11+，还可以使用typing.Self类型进一步简化标注，不需要显式导入SomeClass就能直接标注实例自身类型。

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