如何让Python代码检查工具捕获装饰器导致的函数名遮蔽？

场景示例 #

import functools
def my_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # 装饰器逻辑代码
    return wrapper

def f():
    # 函数业务代码
    return

f = my_decorator(f)

手动执行f = my_decorator(f)会遮蔽原函数f，可能导致后续调用f()出现意外行为。

已尝试的代码检查工具及结果 #

• MyPy：仅当f的类型完全改变（如f = "I am a string now"）时能捕获遮蔽，但无法检测当前场景的遮蔽；
• Pylint：与MyPy情况一致；
• Ruff：与MyPy情况一致；

上述工具均能捕获内置变量遮蔽，当前场景无法检测的核心原因是：f经过装饰器包装后类型未发生变化，工具无法识别这是“非预期的遮蔽”。

问题 #

• 是否存在未发现的配置项可让这些工具更严格以检测该问题？
• 是否有其他可行的替代工具？

解答 #

现有工具的配置项情况 #

1. MyPy：目前无直接检测此类场景的配置项。MyPy核心关注类型一致性，装饰器返回同类型可调用对象时，会判定为合法赋值，即便开启--strict模式也不会触发警告。
2. Pylint：可尝试启用redefined-outer-name规则，但该规则默认仅检测外部作用域变量被内部遮蔽，对当前作用域内的函数自赋值（如f = my_decorator(f)）不会触发。强制开启后效果有限，工具仍会判定为合法重赋值。
3. Ruff：无专门针对该场景的配置，redefined-outer-name规则逻辑与Pylint类似，同作用域内的函数自赋值不会被判定为问题，除非类型变更。

替代工具与解决思路 #

1. 自定义AST检测脚本：编写Python脚本遍历代码的抽象语法树（AST），检测函数定义后是否存在对自身的重赋值操作，且赋值右侧为装饰器调用的情况，直接定位此类代码。
2. flake8自定义插件：基于flake8框架开发插件，封装上述AST检测逻辑，集成到现有代码检查流程中。
3. 代码规范约束：团队内部明确要求使用装饰器语法糖@my_decorator替代手动赋值f = my_decorator(f)，从根源避免此类场景。语法糖不仅可读性更强，也能让静态分析工具明确识别装饰器作用，不会误判为遮蔽。

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