Pylint no-self-use 检查详解：识别可转换为静态方法或模块级函数的方法

• 静态分析
• 代码质量
• Lint
• 开发工具

本文围绕 Pylint 消息no-self-use（R6301）展开，说明它的触发条件、正确修复方式、启用方法以及源码级判定原理。读完本文，你将掌握如何在代码库中开启这一检查、理解它为什么会误报或漏报，并能用@staticmethod、模块级函数或真正使用self三种方式消除告警。

消息概览：一条提醒"方法不该是方法"的告警

no-self-use是 Pylint 的一条重构类（Refactoring）消息，符号名为no-self-use，消息编号为 R6301，提示文本为Method could be a function。它的完整语义记录在 details.rst 中：

如果一个方法没有使用任何类属性，它可以写成@staticmethod，或者写成类外部的函数。

从源码结构看，这条检查由扩展插件pylint.extensions.no_self_use提供，对应 no_self_use.py 中的NoSelfUseChecker，其消息定义保留了历史编号映射：

"R6301": ( "Method could be a function", "no-self-use", "Used when a method doesn't use its bound instance, and so could " "be written as a function.", {"old_names": [("R0201", "old-no-self-use")]}, ),

这段定义说明：当前编号为 R6301，而旧版本中它的编号是 R0201（符号old-no-self-use）。在 Pylint 2.14 之前，no-self-use默认启用；从 2.14 起，它被移到可选扩展中，需要显式加载插件才会生效。相关历史记录见 2.14 变更说明 与 消息删除/迁移登记。

触发场景：一个不使用self的实例方法

官方消息示例 bad.py 给出了最简单的触发代码：

class Person: def greeting(self): # [no-self-use] print("Greetings pythonista!")

greeting虽然以self为第一个参数，但方法体内完全没有访问self上的任何属性或方法。它既不需要实例状态，也不需要多态分派，因此 Pylint 判定"方法可能是函数"，并给出no-self-use告警。

这一判定逻辑的核心实现在 no_self_use.py 的NoSelfUseChecker中：检查器通过visit_name追踪方法体内是否出现与第一个参数同名的名字引用；只要出现一次对self（或首参）的访问，_meth_could_be_func就会被置为False，从而认定该方法是"真正的方法"。用作者自己的话说，这类方法"不使用其绑定的实例，因此可以写成函数"。

三种正确修复方式

消息文档在 good 目录 中给出了三种消除告警的修复方案，全部值得在实战中按场景选用。

方案一：改为实例方法并使用self

如果方法语义上确实依赖实例状态，就在方法体中真正访问self：

class Person: name: str = "Amelia" def greeting(self): print(f"Greetings {self.name} the pythonista!")

见 good/use_self.py。这是最"名正言顺"的修复：方法名副其实地使用了绑定实例。

方案二：改为@staticmethod

如果方法不需要实例，但逻辑上属于类（比如与类有语义关联的工具函数），用静态方法修饰符：

class Person: @staticmethod def greeting(): print("Greetings pythonista!")

见 good/staticmethod.py。@staticmethod使方法不接收绑定实例，首参不再是self，检查器会将其首参记为None并跳过判定。

方案三：移出类，改为模块级函数

如果方法既不使用实例、也不需要类语义归属，最彻底的修复是把它直接写成模块级函数：

def greeting(): print("Greetings pythonista!")

见 good/function.py。这也是 details.rst 中明确给出的建议之一："或写成类外部的函数"。

启用方式：这是一条默认关闭的扩展检查

由于no-self-use自 Pylint 2.14 起属于可选扩展（见 扩展检查器文档），默认不会运行。启用方式有两种：

在 pylintrc 配置文件中启用（消息文档自带的 pylintrc 即为此用法）：

[MAIN] load-plugins=pylint.extensions.no_self_use

在命令行直接启用：

pylint --load-plugins=pylint.extensions.no_self_use your_module.py

使用 pyproject.toml 时同样可以通过[tool.pylint.main]段的load-plugins选项加载，规则一致。

如果某个方法确实需要保留"不使用 self 的实例方法"形态，也可以针对性禁用：

class Person: def greeting(self): # pylint: disable=no-self-use print("Greetings pythonista!")

兼容旧写法时，也可以使用历史编号# pylint: disable=R0201（测试用例 no_self_use.py 中即同时演示了符号名与旧编号两种禁用方式）。

底层判定原理：NoSelfUseChecker是如何工作的

从 no_self_use.py 的源码可以完整还原这条检查的执行流程：

1. 进入方法时：visit_functiondef（以及等价的visit_asyncfunctiondef，说明异步方法同样被检查）先把当前状态压栈，然后调用_check_first_arg_for_type记录方法第一个参数的名字——优先取仅限位置参数posonlyargs，否则取普通参数；如果是@staticmethod，则首参记为None。
2. 遍历方法体时：visit_name会在遇到与首参同名的名字引用时，把_meth_could_be_func置为False，表示"方法使用了实例"。
3. 离开方法时：leave_functiondef弹出首参并综合判断。只有当_meth_could_be_func仍为True、节点类型是普通method、且不命中任何豁免条件时，才会以INFERENCE置信度发出no-self-use。

值得注意的实现细节是：判定过程中，检查器还会借助 utils.py 中的一系列辅助函数排除复杂场景（详见下一节），并且_has_bare_super_call会遍历方法体内的所有Call节点，一旦发现零参数形式的super()调用就中止判定——因为调用super()本身即依赖绑定实例的 MRO 语义。

不会触发的情况：源码明确豁免的场景

leave_functiondef的判定条件揭示了大量豁免分支，理解它们能有效避免误改代码。以下场景都不会触发no-self-use：

• @staticmethod/@classmethod方法：首参不视为绑定实例；
• 特殊方法（dunder 方法）：方法名在PYMETHODS集合中（来自 utils.py 的SPECIAL_METHODS_PARAMS，涵盖__len__、__copy__、__getstate__、__cmp__等），例如__len__即使不访问self也不能改为普通函数，因为它是协议接口的一部分；
• 抽象方法：node.is_abstract()为真时不报；
• 覆盖父类方法：overrides_a_method检测到祖先类（非object）中已有同名FunctionDef时不报，因为子类实现需要保持多态签名；
• @property装饰的方法：decorated_with_property命中时不报，属性不能写成函数；
• 包含裸super()调用的方法：_has_bare_super_call命中时不报；
• Protocol 类中的方法：is_protocol_class命中时不报；
• @overload存根：is_overload_stub命中时不报。

这些豁免规则全部有对应的功能测试用例佐证。在 tests/functional/ext/no_self_use/no_self_use.py 及其期望输出 no_self_use.txt 中，可以看到：

• Toto.function_method与async_function_method（异步方法不使用 self）被标记；
• 抽象类Base.check、子类覆盖Sub.check、重写父类方法的Sub1.method均不报；
• @property的Prop.count、Protocol 类Foo2.a、@overload的Foo3.a、@staticmethod/@classmethod方法均不报；
• 只有两个位置参数的C.a（def a(self, /)）也会被标记，说明仅限位置参数场景同样被覆盖；
• MyTest.test_one._MySubClass.my_sub_method这一嵌套局部类的回归用例也会被检测到，对应历史上的 issue #3705。

实践建议

在真实项目中启用no-self-use后，最常遇到的"假阳性"恰恰来自上述豁免边界：例如覆盖第三方基类接口的方法、需要维持类 API 稳定性的方法，都会被 Pylint 正确放过。因此，当这条告警出现时，通常意味着代码确实存在简化空间，按"真正使用self→@staticmethod→ 模块级函数"的顺序依次评估即可；而遇到边界场景时，优先考虑使用符号名no-self-use做局部禁用，并保留必要的注释说明原因，避免破坏接口设计。

• 静态分析
• 代码质量
• Lint
• 开发工具