企业官网建设流程全解析

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

Pylint 2.6 是 2020 年 8 月发布的一个承前启后的版本：它新增了super-with-arguments、raise-missing-from两个面向 Python 3 现代写法的检查器，同时果断移除了bad-continuation、bad-whitespace、mixed-indentation等与格式化工具重叠的检查，并首次完整支持 isort 5。本文以官方变更日志 doc/whatsnew/2/2.6/full.rst 为主线，结合当前仓库源码，逐项解读这些变更的实现细节、迁移方法与最佳实践，帮助你理解 Pylint 在"代码规范 vs 代码风格"上的定位调整，以及升级到 2.6+ 后需要做的配置迁移。

版本概览：2.6.0 与 2.6.1

该版本周期包含两个发布：

2.6.1 的变更在 doc/whatsnew/2/2.6/full.rst 中排在最前，属于一次依赖兼容性收口：当时 astroid 2.5 引入了破坏性变化，pylint 选择先锁版本、再在后续版本中适配。

新增检查器一：super-with-arguments（R1725）

super-with-arguments用于标记 Python 2 风格的super()调用。在 Python 2 中必须写成super(CurrentClass, self).method()，而 Python 3 中这些参数是默认值，可以完全省略为super().method()。

其消息定义位于 pylint/checkers/refactoring/refactoring_checker.py 中的 R1725：

"Consider using Python 3 style super() without arguments"

触发条件是：当super()的第一个参数是当前所在类、第二个参数是self时发出警告。其核心检测逻辑_check_super_with_arguments（refactoring_checker.py）通过 AST 模式匹配实现：

case nodes.Call( func=nodes.Name(name="super"), args=[nodes.Name(name=name), nodes.Name(name="self")], ) if (frame_class := node_frame_class(node)) is not None and name == frame_class.name: pass case _: return self.add_message("super-with-arguments", node=node)

从源码可以看出两点设计意图：

• 只匹配显式super(ClassName, self)形式，且ClassName必须等于调用点所在的类名，避免对super(OtherClass, self)（合法且有意义的跨类委托）误报；
• super(cls, self)这类在无__class__闭包场景下的显式写法不会被警告。这一点在功能测试 tests/functional/s/super/super_with_arguments.py 中有明确注释：普通函数里super(cls, self)是唯一可用的形式（否则会抛RuntimeError: super(): __class__ cell not found），因此被刻意排除。

配置示例

该检查器属于重构类（refactoring），默认启用。测试文件 tests/functional/s/super/super_with_arguments.rc 展示了如何单独验证该消息：

[Messages Control] disable=all enable=super-with-arguments

对应代码行为：

class Bar(Foo): def __init__(self): super(Bar, self).__init__() # [super-with-arguments] class Baz(Foo): def __init__(self): super().__init__() # 正确写法，不警告

升级到 Python 3 的项目中，可以借助该检查器批量定位遗留的 Python 2 风格super()调用，再统一改写为super()零参数形式。

新增检查器二：raise-missing-from（W0707）

raise-missing-from用于提示：在except块中抛出新异常时，应当使用raise ... from ...显式链接原始异常，从而保留完整的 traceback 链。其消息定义位于 pylint/checkers/exceptions.py 中的 W0707：

"Python's exception chaining shows the traceback of the current exception, but also of the original exception. When you raise a new exception after another exception was caught it's likely that the second exception is a friendly re-wrapping of the first exception. In such casesraise fromprovides a better link between the two tracebacks in the final error."

触发与豁免规则

检测逻辑在_check_raise_missing_from（exceptions.py），规则可归纳为：

1. 纯raise（无异常表达式）直接放行——它是在重抛捕获到的同一异常，不需要 cause；
2. 必须位于except包裹的作用域内（通过utils.find_except_wrapper_node_in_scope定位），否则不检查；
3. 在except内抛出新异常（raise SomeException或raise SomeException(...)）时触发；
4. 如果except没有as exception:绑定名，则任何raise SomeException都视为新异常，直接触发；
5. 已使用raise ... from ...的形式不触发（见测试文件后半部分raise KeyError from foo均无警告）。

功能测试 tests/functional/r/raise_missing_from.py 覆盖了嵌套try/except、except (...)元组、else/finally等大量边界场景。

实战示例

try: 1 / 0 except ZeroDivisionError as e: raise KeyError # [raise-missing-from]

正确写法：

try: 1 / 0 except ZeroDivisionError as e: raise KeyError from e # 保留两层 traceback

在捕获后重新包装异常（例如把底层库异常转换为业务异常）的代码中，这条检查非常实用，能帮助保持可诊断的错误链路。

被移除的检查器与选项：让格式化工具各司其职

2.6 最引人注目的变化是主动删除了三个风格类检查和一个选项，明确把"格式"职责交还给代码格式化工具。

bad-continuation与bad-whitespace：交给 black 等工具

变更日志明确指出："bad-continuation and bad-whitespace have been removed, black or another formatter can help you with this better than Pylint"。这两个检查分别负责缩进续行风格与空格规范，但它们的规则难以穷尽，且与 black、autopep8 等格式化器存在大量重叠。Pylint 团队的决定是：lint 工具管逻辑正确性，格式化工具管排版。关联关闭的 issue 多达十余个（#246、#289、#638、#747、#1148、#1179、#1943、#2041、#2301、#2304、#2944、#3565），说明这两项长期是误报与配置争议的重灾区。

mixed-indentation：Python 3 内置语法错误已覆盖

mixed-indentation检测同一文件混用空格与 Tab 缩进。由于 Python 3 解释器本身就会对混用缩进抛出TabError，该检查在 3.x 时代已失去价值，故一并移除（关闭 #2984、#3573）。

no-space-check选项：不再允许"把空行当作 trailing-whitespace"

no-space-check是trailing-whitespace检查器的配置项，历史上可以通过"巧妙"配置把空行也计入尾随空白检查。2.6 将其删除，意味着空行不再被当作trailing-whitespace处理（关闭 #1368），行为变得简单可预期。

升级影响与配置迁移

如果你现有的pylintrc/pyproject.toml中写有：

disable=bad-continuation,bad-whitespace,mixed-indentation

或

no-space-check=empty-line

升级到 2.6+ 后这些条目已无意义：前三个消息名已不存在，no-space-check选项会触发未知选项警告。建议清理这些配置，将代码风格统一交由 black 等格式化工具管理（Pylint 官方文档 doc/user_guide/installation/pre-commit-integration.rst 也介绍了与格式化/提交钩子协同的用法）。

isort 4/5 双支持与known-standard-library迁移

2.6 同时支持 isort 4 与 isort 5（关闭 #3722），这是该版本最需要用户注意的配置语义变化。

底层实现：选项映射关系

在 pylint/checkers/imports.py 中，_isort_config构建 isort 配置时有一条关键映射：

return isort.Config( # There is no typo here. EXTRA_standard_library is # what most users want. The option has been named # KNOWN_standard_library for ages in pylint, and we # don't want to break compatibility. extra_standard_library=self.linter.config.known_standard_library, known_first_party=self.linter.config.known_first_party, known_third_party=self.linter.config.known_third_party, )

源码注释说得非常直白："这里没有拼写错误。extra_standard_library才是大多数用户想要的，而known_standard_library这个名字在 pylint 里用了很多年，我们不想破坏兼容性。"

也就是说：

• isort 4中known-standard-library的含义 = 模块应被识别为标准库；
• isort 5中known-standard-library的含义 = 强制覆盖判定结果（通常是强制当作标准库），而新增的extra-standard-library才对应"额外补充进标准库清单"；
• Pylint 的known-standard-library选项在内部映射为 isort 5 的extra_standard_library，从而维持了绝大多数 pylint 用户原有的行为预期。

known-standard-library选项本身定义在 imports.py，类型为 CSV，默认值为DEFAULT_STANDARD_LIBRARY。

如果你真的想要 isort 5 的"强制覆盖"语义

变更日志给出的方案是：在 pylint 中禁用wrong-import-order检查，用带独立 isort 配置文件的 isort 单独做导入排序。因为 pylint 的导入顺序检查（wrong-import-order、ungrouped-imports、wrong-import-position，参见 imports.py）完全依赖 isort 的分类结果，一旦你需要的分类规则与 pylint 内部映射不一致，就该让 isort 亲自负责排序。

迁移检查清单

关键修复盘点：误报、崩溃与边界行为

2.6 还修复了多个影响实际使用的问题，逐一说明其背景与现状。

undefined-variable作用域相关 bug

修复了若干作用域相关的误报/漏报（关闭 #1082、#3434、#3461），涉及变量在嵌套作用域、闭包与分支条件下的解析。该检查器位于 pylint/checkers/variables.py，是 pylint 中逻辑最复杂的检查器之一，这类修复通常针对"变量实际已定义却被误报 undefined"或"跨作用域引用未被识别"的场景。

missing-kwoa不再对 overload 函数误报

missing-kwoa（缺少仅限关键字参数）在调用typing.overload修饰的函数时不再发出（关闭 #3655）。实现上，pylint/checkers/typecheck.py 会先通过is_overload_stub(called)判断被调用者是否为 overload 桩（utils.is_overload_stub定义于 pylint/checkers/utils.py），若是，则在匹配位置参数、关键字参数时跳过部分告警分支（见 typecheck.py 及后续 L1767、L1801、L1814 等处），因为 overload 的每个重载签名可以不同，逐一校验会误报。

superfluous-parens对海象运算符（walrus）的误报

修复了superfluous-parens在:=海象运算符场景下的误报（关闭 #3383）。检测逻辑位于 pylint/checkers/format.py：词法扫描时记录海象运算符所在括号深度（walrus_operator_depth），当闭合括号满足contains_walrus_operator and walrus_operator_depth - 1 == depth时直接跳过，因为海象运算符周围的括号往往承载语义（如if (x := f())的括号是必需或重要的）。测试中同样覆盖了if (not)条件与推导式内的场景。

fail-under支持浮点数

fail-under选项此前无法正确解析浮点阈值。2.6 将其类型修正为float（见 pylint/lint/base_options.py，默认值 10），现在可以这样使用：

pylint --fail-under 8.5 mypackage/

其退出码逻辑在 pylint/lint/run.py 与 pylint/lint/pylinter.py 中实现：当评估分数低于阈值时以错误码退出，适合接入 CI 门禁。

ignore-docstrings忽略整模块行的问题

ignore-docstrings用于相似代码（duplicate-code）检测时剔除 docstring 行。此前存在 bug：一旦模块中某处出现 docstring，可能导致模块内所有行都被错误忽略。相关处理逻辑在 pylint/checkers/symilar.py（逐行剔除 docstring）与选项定义（symilar.py，默认True）。修复后 docstring 只在真正处于字符串字面量范围内的行被剥离。

并行模式下的两个崩溃

2.6 修复了并行（-j）模式下的两个崩溃：

• 模块 filepath 未设置时的崩溃（关闭 #3564）：并行 worker 在返回结果时依赖file_item.filepath（见 pylint/lint/parallel.py），当某模块没有文件路径（如从 stdin 分析）时会触发。修复后此类输入不再导致 worker 崩溃；
• infer_call_result未防御InferenceError（关闭 #3690）：类型推断过程中的InferenceError未捕获会导致整个分析崩溃，修复后该异常被安全吞掉并跳过该调用点的分析。

pre-commit 配置与重复代码检测

修复了官方.pre-commit-config.yaml中可能导致重复代码行（duplicate-code）漏检的配置问题。这也提醒使用者：如果依赖 pre-commit 钩子运行 pylint，2.6 之后应使用仓库当前推荐的配置写法（参见 doc/user_guide/installation/pre-commit-integration.rst），确保min-similarity-lines等相似代码检测参数按预期生效。

FAQ：与其他流行 linter 去重

2.6 在 doc/faq.rst 中新增了 FAQ，说明为了与其他流行 linter（如 pycodestyle、flake8、black 等）避免重复告警，应禁用哪些消息。这与本次移除风格类检查的决策一脉相承：Pylint 聚焦于逻辑错误、代码气味与可维护性，纯排版风格问题交给专用工具。合并使用多个 lint/format 工具时，建议对照该 FAQ 配置各自的disable清单，避免同一行代码被多个工具重复报错。

升级到 2.6+ 的完整行动清单

综合以上变更，从旧版本升级到 2.6+ 时建议按以下步骤操作：

1. 清理配置：删除配置中的bad-continuation、bad-whitespace、mixed-indentation与no-space-check，它们已不存在；
2. 接入格式化工具：将代码格式职责交给 black（或你选用的 formatter），可在 pre-commit 中与 pylint 钩子串联；
3. 检查 isort 版本：若使用 isort 5，确认known-standard-library的语义映射（对应 isort 5 的extra-standard-library），必要时改为"pylint 关闭wrong-import-order+ 独立 isort 配置"；
4. 顺手修复新告警：super-with-arguments（改写为super()）与raise-missing-from（改写为raise ... from ...）默认开启，升级后运行一次即可批量定位；
5. 验证 CI 门禁：fail-under现在支持浮点数阈值（如8.5），可按需收紧质量门禁。

这些变更在后续版本中持续演进，但你可以在当前仓库源码中直接查看它们的实现与测试：新检查器与修复逻辑见 pylint/checkers/refactoring/refactoring_checker.py、pylint/checkers/exceptions.py、pylint/checkers/imports.py 与 pylint/checkers/format.py，对应的功能测试位于 tests/functional/s/super/ 与 tests/functional/r/raise_missing_from.py，可作为理解每条消息边界行为的权威参考。

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