Pylint

← 返回目录 > ← 返回总览

工具	说明
Ruff	Python 高速 linter，支持自动修复，可替代 Pylint 的格式和简单规则检查
Bandit	Python 安全漏洞检查工具

1. 简介

Pylint 是 Python 生态中历史最悠久、功能最完备的静态代码分析工具之一，由 pylint-dev 团队开发维护。它通过内部代码表示库 astroid 对 Python 源码进行深度语义分析，在不运行代码的情况下检测错误、强制编码规范、识别代码异味并提供重构建议。

主要检查语言：Python
主要检查能力：检测错误、强制编码规范、识别代码异味并提供重构建议；涵盖代码质量与规范检查
核心检查原理：基于 astroid AST 库进行语义推断分析
检查规则/选项：消息按 Fatal、Error、Warning、Convention、Refactor、Info 六大类组织，总数随版本动态变化（约数百条），全量消息总览
GitHub 仓库：https://github.com/pylint-dev/pylint（5,683 stars）
开源协议：GPL-2.0-or-later
最新稳定版本：v3.3.6
运行环境要求：Python 3.9+（v3.x 起）
误报率：中

2. 官方文档

资源	链接
官方文档（Read the Docs）	https://pylint.readthedocs.io/en/stable/
快速入门教程	https://pylint.readthedocs.io/en/stable/tutorial.html
用户指南	https://pylint.readthedocs.io/en/stable/user_guide/index.html
所有消息/规则列表	https://pylint.readthedocs.io/en/stable/user_guide/messages/messages_overview.html
配置选项完整参考	https://pylint.readthedocs.io/en/stable/user_guide/configuration/all-options.html
命令行选项	https://pylint.readthedocs.io/en/stable/user_guide/usage/run.html
消息控制指南	https://pylint.readthedocs.io/en/stable/user_guide/messages/message_control.html
插件开发指南	https://pylint.readthedocs.io/en/stable/development_guide/how_tos/plugins.html
pre-commit 集成文档	https://pylint.readthedocs.io/en/stable/user_guide/installation/pre-commit-integration.html
IDE 集成文档	https://pylint.readthedocs.io/en/stable/user_guide/installation/ide_integration/index.html
PyPI 页面	https://pypi.org/project/pylint/
变更日志	https://pylint.readthedocs.io/en/stable/whatsnew/index.html

3. 社区优秀实践

3.1 Pylint 自身项目

Pylint 自身仓库是 Pylint 最佳实践的参考来源，使用 repo: local + language: system 的 pre-commit 集成方式，配合 pylintrc 配置文件和 Ruff、Black、isort 等工具协同工作。

仓库：https://github.com/pylint-dev/pylint
pre-commit 配置：https://github.com/pylint-dev/pylint/blob/main/.pre-commit-config.yaml

关键配置特点：

使用 repo: local + language: system，依赖本地安装的 Pylint
通过 args: ["-rn", "-sn", "--rcfile=pylintrc", "--fail-on=I"] 控制输出
require_serial 未设置为 true（官方注释说明并行化对正确性的影响有限）
排除测试 fixtures 和文档目录

3.2 pytest 项目

pytest 是 Python 生态中最主流的测试框架，在 pyproject.toml 中配置了 Pylint，同时使用 Ruff 处理格式和简单规则，两者互补。

仓库：https://github.com/pytest-dev/pytest
pyproject.toml 中的 Pylint 配置：https://github.com/pytest-dev/pytest/blob/main/pyproject.toml

关键配置特点：

在 [tool.pylint.main] 中设置 max-line-length = 120
大量禁用与 Ruff 重叠的规则（如 PLR 系列的重构建议、PLC 系列的规范检查）
保留 Pylint 独有的深度分析能力（如 no-member、used-before-assignment 等）
禁用了 docstring 相关检查（missing-docstring、missing-param-doc 等）

3.3 Django 社区 -- pylint-django 插件

Django 框架大量使用元编程（如 ORM 的 Model.objects 管理器、Meta 内部类等），原生 Pylint 会产生大量误报。pylint-django 插件解决了这些问题。

pylint-django 仓库：https://github.com/pylint-dev/pylint-django
Django 主仓库：https://github.com/django/django

核心能力：

消除 Django 自动生成属性（如 Model.objects、View.request）的误报警告
解决 ForeignKey 属性导致的 "Instance of ForeignKey has no member" 错误
改进对 Model 和 Form 字段属性类型的推断
验证 Model.__str__ 方法的正确性

典型配置：

pip install pylint pylint-django

# pyproject.toml
[tool.pylint.main]
load-plugins = ["pylint_django"]

或通过命令行：

DJANGO_SETTINGS_MODULE=myproject.settings pylint --load-plugins=pylint_django myapp/

3.4 Odoo 社区 -- pylint-odoo 插件

Odoo 是全球最大的开源 ERP 系统之一，OCA（Odoo Community Association）维护了功能丰富的 pylint-odoo 插件，包含 50+ 条 Odoo 专用检查规则。

pylint-odoo 仓库：https://github.com/OCA/pylint-odoo
Odoo 主仓库：https://github.com/odoo/odoo

典型配置：

pip install pylint pylint-odoo

# 仅运行 pylint-odoo 的检查项
pylint --load-plugins=pylint_odoo --disable=all --enable=odoolint --valid-odoo-versions=18.0 addons_path/

4. 工具配置说明

以下是一个经过实践验证的 Pylint 推荐配置，适用于中大型 Python 项目。配置遵循渐进式启用策略，从错误检查开始，逐步扩展到警告和重构建议。

4.1 配置文件说明

Pylint 支持多种配置文件格式，按优先级从高到低（Pylint 使用第一个找到的配置文件）：

配置文件	格式	用途
`--rcfile` 命令行参数	任意	显式指定，最高优先级
`pylintrc`	INI	经典配置文件（当前工作目录）
`pylintrc.toml`	TOML	TOML 格式，需包含 `tool.pylint.` 节
`.pylintrc`	INI	隐藏文件格式
`.pylintrc.toml`	TOML	隐藏 TOML 格式
`pyproject.toml`（`[tool.pylint]` 节）	TOML	现代项目推荐方式
`setup.cfg`（`[pylint]` 节）	INI	传统 Python 项目常用
`tox.ini`（`[pylint]` 节）	INI	tox 配置文件
`pyproject.toml`（向上搜索到 `.git`/`.hg` 或根）	TOML	向上目录层级搜索
Python 包层级中的 `pylintrc`	INI	沿 `__init__.py` 向上搜索
`PYLINTRC` 环境变量	任意	通过环境变量指定路径
`~/.pylintrc` 或 `~/.config/pylintrc`	INI	用户主目录配置
`/etc/pylintrc`	INI	全局配置（Linux/macOS）

参考：配置文件搜索顺序

4.2 配置文件详解

Pylint 配置文件按节（section）组织，主要节包括 main（主控）、messages_control（规则启停）、format（格式）、basic（命名）、design（复杂度）、exceptions（异常）、refactoring（重构）、similarities（相似代码）。

配置项说明：

配置项	类型	说明
`[tool.pylint.main] py-version`	string	目标 Python 版本
`[tool.pylint.main] ignore`	string[]	忽略的目录列表（不进行任何检查）
`[tool.pylint.main] ignored-modules`	string[]	忽略的模块列表（不进行导入分析）
`[tool.pylint.main] load-plugins`	string[]	加载的插件列表（如 `pylint_django`）
`[tool.pylint.main] jobs`	int	并行检查进程数
`[tool.pylint.main] persistent`	bool	是否启用持久化缓存
`[tool.pylint.messages_control] disable`	string[]	禁用的规则 ID 或名称列表
`[tool.pylint.messages_control] enable`	string[]	启用的规则 ID 或名称列表
`[tool.pylint.format] max-line-length`	int	最大行长度
`[tool.pylint.basic] *-naming-style`	string	各类符号命名风格（`snake_case`/`PascalCase`/`UPPER_CASE`/`any`）
`[tool.pylint.basic] good-names`	string[]	不视为 `invalid-name` 的变量名列表
`[tool.pylint.design] max-args`	int	函数最大参数数
`[tool.pylint.design] max-attributes`	int	类最大属性数
`[tool.pylint.design] max-branches`	int	函数最大分支数
`[tool.pylint.design] max-locals`	int	函数最大局部变量数
`[tool.pylint.design] max-returns`	int	函数最大返回路径数
`[tool.pylint.design] max-statements`	int	函数最大语句数
`[tool.pylint.design] max-parents`	int	类最大父类数
`[tool.pylint.design] max-public-methods`	int	类最大公共方法数
`[tool.pylint.exceptions] overgeneral-exceptions`	string[]	允许捕获的宽泛异常类型
`[tool.pylint.refactoring] max-nested-blocks`	int	最大嵌套块深度
`[tool.pylint.similarities] min-similarity-lines`	int	相似代码检测的最小行数
`[tool.pylint.similarities] ignore-comments`	bool	相似检测忽略注释
`[tool.pylint.similarities] ignore-docstrings`	bool	相似检测忽略文档字符串
`[tool.pylint.similarities] ignore-imports`	bool	相似检测忽略导入语句

推荐配置示例（pyproject.toml）：

# ============================================================
# Pylint 推荐配置 - 适用于中大型 Python 项目
# ============================================================

[tool.pylint.main]
# 目标 Python 版本
py-version = "3.12"

# 忽略的目录（不进行任何检查）
ignore = [
    "venv",
    ".venv",
    "migrations",
    "__pycache__",
    ".git",
    "build",
    "dist",
]

# 忽略的模块（不进行导入分析）
ignored-modules = []

# 加载插件（根据项目框架选择）
load-plugins = [
    # "pylint_django",    # Django 项目取消注释
    # "pylint_odoo",      # Odoo 项目取消注释
]

# 并行检查进程数（加速大型项目分析）
jobs = 4

# 启用持久化缓存
persistent = true

[tool.pylint.messages_control]
# 禁用的规则（附说明）
disable = [
    # ---- 文档字符串相关（根据团队规范决定） ----
    "missing-module-docstring",      # C0114: 缺少模块文档字符串
    "missing-class-docstring",       # C0115: 缺少类文档字符串
    "missing-function-docstring",    # C0116: 缺少函数文档字符串

    # ---- 设计相关（适度放宽） ----
    "too-few-public-methods",         # R0903: 类的公共方法过少（常见于数据类/DTO）
    "too-many-instance-attributes",  # R0902: 实例属性过多

    # ---- 格式相关（交给 black/ruff 处理） ----
    "line-too-long",                  # C0301: 行过长（由格式化工具处理）
    "trailing-whitespace",            # C0303: 行尾空白（由格式化工具处理）
    "trailing-newlines",              # C0305: 文件末尾多余空行
    "missing-final-newline",          # C0304: 文件末尾缺少换行

    # ---- 导入相关（交给 isort/ruff 处理） ----
    "wrong-import-order",             # C0411: 导入顺序错误
    "ungrouped-imports",              # C0412: 导入分组错误
    "wrong-import-position",          # C0413: 导入位置错误

    # ---- 其他 ----
    "fixme",                          # W0511: TODO/FIXME 注释
    "broad-exception-caught",         # W0718: 捕获过于宽泛的 Exception
]

[tool.pylint.format]
# 最大行长度（与 black 保持一致）
max-line-length = 120

[tool.pylint.basic]
# 命名风格
function-naming-style = "snake_case"
variable-naming-style = "snake_case"
class-naming-style = "PascalCase"
const-naming-style = "UPPER_CASE"
method-naming-style = "snake_case"
module-naming-style = "snake_case"
argument-naming-style = "snake_case"
class-attribute-naming-style = "any"
attr-naming-style = "snake_case"

# 好的变量名列表（不视为 invalid-name）
good-names = ["i", "j", "k", "v", "e", "ex", "f", "fp", "_", "ok", "id"]

[tool.pylint.design]
# 复杂度限制
max-args = 7              # 函数最大参数数（默认 5）
max-attributes = 7        # 类最大属性数（默认 7）
max-branches = 12          # 函数最大分支数（默认 12）
max-locals = 15           # 函数最大局部变量数（默认 15）
max-returns = 6            # 函数最大返回路径数（默认 6）
max-statements = 50       # 函数最大语句数（默认 50）
max-parents = 7            # 类最大父类数（默认 7）
max-public-methods = 20    # 类最大公共方法数（默认 20）

[tool.pylint.exceptions]
# 允许捕获的宽泛异常类型
overgeneral-exceptions = ["builtins.BaseException", "builtins.Exception"]

[tool.pylint.refactoring]
# 最大嵌套块深度
max-nested-blocks = 5

[tool.pylint.similarities]
# 相似代码检测的最小行数
min-similarity-lines = 4
# 忽略注释
ignore-comments = true
# 忽略文档字符串
ignore-docstrings = true
# 忽略导入语句
ignore-imports = true

4.3 渐进式启用策略

对于首次在项目中引入 Pylint 的团队，推荐采用渐进式启用策略：

第一阶段 -- 仅检查错误：

# 仅报告 Error 和 Fatal 级别问题
pylint --errors-only myproject/
# 或
pylint -E myproject/

第二阶段 -- 添加关键警告：

[tool.pylint.messages_control]
disable = ["all"]
enable = [
    "E",       # 所有错误
    "W0611",   # unused-import：未使用的导入
    "W0612",   # unused-variable：未使用的变量
    "W0621",   # redefined-outer-name：重定义外部变量名
    "W0622",   # redefined-builtin：重定义内置名称
    "W0702",   # bare-except：裸 except 子句
]

第三阶段 -- 逐步启用更多规则：

随着代码质量的提升，逐步取消 disable 中的规则，最终达到全面覆盖。

5. 主流集成方式

5.1 pre-commit 集成

Pylint 官方文档明确指出：由于 Pylint 的速度特性，它更适合在 CI 或 git pre-push hook 中使用，而非每次 commit 时运行（尤其对于大型仓库）。参考：pre-commit 集成文档

注意：Pylint 需要导入项目的模块和依赖才能正确进行类型推断，因此必须使用 language: system（依赖本地安装的 Pylint），不能使用 pre-commit.ci 云端执行。需要在 .pre-commit-config.yaml 中添加 ci: skip: [pylint]。

推荐方式：使用本地安装（官方文档推荐）

# .pre-commit-config.yaml
ci:
  skip: [pylint]

repos:
  - repo: local
    hooks:
      - id: pylint
        name: pylint
        entry: pylint
        language: system
        types: [python]
        require_serial: true # 确保所有文件一起分析，保证推断准确性
        args:
          - "-rn" # 仅显示消息
          - "-sn" # 不显示评分

require_serial: true 确保 Pylint 一次性分析所有文件，避免因文件拆分导致类型推断不准确。但如果正确性和确定性对你来说不如并行化重要，可以不设置（Pylint 自身仓库即未设置）。

使用 Pylint 官方仓库的 pre-commit hook：

pylint-dev/pylint 仓库包含 .pre-commit-hooks.yaml，可直接作为 pre-commit 仓库使用：

# .pre-commit-config.yaml
ci:
  skip: [pylint]

repos:
  - repo: https://github.com/pylint-dev/pylint
    rev: v4.0.5
    hooks:
      - id: pylint

此方式使用 language: python，pre-commit 会创建独立虚拟环境安装 Pylint。如果项目需要额外插件（如 pylint-django），需通过 additional_dependencies 声明。

安装与运行：

# 安装 pre-commit 框架
pip install pre-commit

# 安装钩子到 .git/hooks/
pre-commit install

# 手动对所有文件运行检查
pre-commit run --all-files

# 仅对暂存文件运行检查（默认行为）
pre-commit run

增量检查：pre-commit 框架默认只检查暂存区的变更文件，无需额外配置即可实现文件级增量。上述 .pre-commit-config.yaml 配置（repo: local + language: system + require_serial: true）在 git commit 时自动只对暂存区文件运行 Pylint。

5.2 IDE 集成

VS Code

VS Code 通过独立的 Pylint 扩展实现集成。

安装 Pylint 扩展（由 Microsoft 发布）
在项目根目录创建 pyproject.toml 或 .pylintrc 配置文件，Pylint 扩展会自动发现并使用

参考：VS Code Python linting 文档

PyCharm

PyCharm 通过"外部工具"机制集成 Pylint。

在 PyCharm 中安装 pylint：设置 -> 项目 -> Python 解释器 -> 搜索 pylint -> 安装
配置外部工具：设置 -> 工具 -> 外部工具 -> 添加
- 程序：$PyInterpreterDirectory$/pylint（Linux/macOS）或 $PyInterpreterDirectory$\pylint（Windows）
- 参数：--msg-template="{path}:{line}:{column}:{C}:({symbol}){msg}" $ProjectFileDir$/src
- 工作目录： $ProjectFileDir$
通过 工具 -> 外部工具 -> pylint 运行检查

参考：PyCharm 外部工具配置

Vim/Neovim

使用 ALE 插件（Vim/Neovim 通用）：

" ~/.vimrc 或 init.vim
let g:ale_linters = {'python': ['pylint']}
let g:ale_python_pylint_executable = 'pylint'
let g:ale_python_pylint_options = '--rcfile=pyproject.toml'
let g:ale_python_pylint_use_global = 1

使用 coc.nvim（Neovim）：

" init.vim
Plug 'neoclide/coc.nvim', {'branch': 'release'}
" 安装后运行 :CocInstall coc-pylint

参考：Pylint IDE 集成文档

5.3 命令行使用方式

# 检查单个文件
pylint mymodule.py

# 检查整个项目目录
pylint myproject/

# 仅显示错误和致命错误（适合首次接入）
pylint --errors-only myproject/
# 或
pylint -E myproject/

# 指定配置文件
pylint --rcfile=pyproject.toml myproject/

# 禁用特定规则
pylint --disable=C0114,C0115,C0116 myproject/

# 启用特定规则（配合 --disable=all 使用）
pylint --disable=all --enable=E,W myproject/

# 设置最低通过分数
pylint --fail-under=8.0 myproject/

# JSON 格式输出（便于机器解析）
pylint --output-format=json2 myproject/ > report.json

# GitHub Actions 格式输出
pylint --output-format=github myproject/

# 并行检查（4 个进程）
pylint -j 4 myproject/

# 使用缓存加速
pylint --persistent=y myproject/

# 列出所有可用消息
pylint --list-msgs

# 查看特定消息的详细信息
pylint --help-msg=C0114

# 生成默认 TOML 配置文件
pylint --generate-toml-config > pylintrc.toml

# 加载插件
pylint --load-plugins=pylint_django myproject/

# 忽略特定目录
pylint --ignore=venv,migrations,tests myproject/

# 递归检查目录（包括非包目录）
pylint --recursive=y mydir/

增量检查：通过 Git diff 获取变更文件列表，仅对变更的 Python 文件运行 Pylint。

# 检查相对于最近一次提交变更的 Python 文件
pylint $(git diff --name-only HEAD -- '*.py')

# 检查暂存区中变更的文件
pylint $(git diff --cached --name-only -- '*.py')

# 检查两个分支之间变更的文件
pylint $(git diff --name-only origin/main...HEAD -- '*.py')

# 检查未暂存的变更文件
pylint $(git diff --name-only -- '*.py')

注意：Pylint 官方文档指出，仅对部分文件进行分析可能导致类型推断不准确。如果正确性和确定性很重要，建议对全量代码进行分析。

CI 脚本调用：

GitHub Actions

# .github/workflows/pylint.yml
name: Pylint
on: [push, pull_request]

jobs:
  pylint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pylint

      - name: Run Pylint
        run: |
          pylint --rcfile=pyproject.toml --fail-under=8.0 myproject/

--fail-under=8.0 表示代码评分低于 8.0 时 CI 失败。

GitLab CI

# .gitlab-ci.yml
lint:
  image: python:3.12
  before_script:
    - pip install pylint
  script:
    - pylint --rcfile=pyproject.toml --fail-under=8.0 myproject/
  allow_failure: false

增量检查：在 CI/CD 中可通过 Git diff 获取 PR/MR 变更文件列表，仅对变更的 Python 文件运行 Pylint。

GitHub Actions -- 按 PR 变更文件触发增量检查：

# .github/workflows/pylint.yml
name: Pylint (Incremental)
on: [pull_request]

jobs:
  pylint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Pylint
        run: pip install pylint

      - name: Run Pylint on changed files
        run: |
          CHANGED_FILES=$(git diff --name-only origin/$GITHUB_BASE_REF...HEAD -- '*.py')
          if [ -n "$CHANGED_FILES" ]; then
            echo "Checking: $CHANGED_FILES"
            pylint --rcfile=pyproject.toml $CHANGED_FILES
          else
            echo "No Python files changed."
          fi

GitLab CI -- 按 MR 变更文件触发增量检查：

# .gitlab-ci.yml
lint:incremental:
  image: python:3.12
  before_script:
    - pip install pylint
  script:
    - |
      CHANGED_FILES=$(git diff --name-only origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD -- '*.py')
      if [ -n "$CHANGED_FILES" ]; then
        pylint --rcfile=pyproject.toml $CHANGED_FILES
      else
        echo "No Python files changed."
      fi
  only:
    - merge_requests

5.4 pip/uv 安装与 pyproject.toml 配置（生态主流）

Pylint 作为 Python 工具，业界主流集成方式为通过 pip/uv 安装，在 pyproject.toml 中配置规则。

# 基础安装
pip install pylint

# 使用 uv 安装
uv add pylint --dev

# 安装拼写检查支持
pip install pylint[spelling]

pyproject.toml 最小配置示例：

[tool.pylint.main]
py-version = "3.12"
ignore = ["venv", "migrations", "__pycache__"]
load-plugins = []

[tool.pylint.messages_control]
disable = [
    "missing-module-docstring",
    "missing-class-docstring",
    "missing-function-docstring",
]

[tool.pylint.format]
max-line-length = 120

[tool.pylint.basic]
function-naming-style = "snake_case"
class-naming-style = "PascalCase"
variable-naming-style = "snake_case"

6. 告警抑制（屏蔽）方法

6.1 通过工具配置文件屏蔽

在 pyproject.toml 或 .pylintrc 中全局禁用特定规则。

参考：消息控制文档

pyproject.toml 方式：

[tool.pylint.messages_control]
disable = [
    "missing-module-docstring",     # C0114: 缺少模块文档字符串
    "missing-class-docstring",      # C0115: 缺少类文档字符串
    "missing-function-docstring",   # C0116: 缺少函数文档字符串
    "too-few-public-methods",       # R0903: 类公共方法过少
]

参考：配置选项参考

6.2 通过工具命令行参数屏蔽

参考：命令行选项

# 禁用特定规则
pylint --disable=missing-module-docstring,too-few-public-methods myproject/

# 启用特定规则（配合 --disable=all 使用）
pylint --disable=all --enable=E,W0611,W0612 myproject/

# 忽略特定目录
pylint --ignore=venv,migrations,tests myproject/

# 按正则表达式忽略文件
pylint --ignore-patterns="test_.*\.py$" myproject/

6.3 通过代码行级注释屏蔽

参考：Block disables 文档

单行屏蔽（行尾注释）

x = 10  # pylint: disable=unused-variable

下一行屏蔽（Pylint 3.0+）

# pylint: disable-next=unused-variable
x = 10

模块级注释屏蔽（文件顶部）

# pylint: disable=missing-module-docstring,missing-function-docstring

def my_function():
    pass

函数/类级屏蔽

# pylint: disable=too-many-locals,too-many-branches
def complex_function(data):
    """一个复杂的函数。"""
    # ... 复杂逻辑 ...
    pass

局部禁用后重新启用

class MyClass:
    # pylint: disable=too-few-public-methods
    def __init__(self):
        self.value = 42
    # pylint: enable=too-few-public-methods

禁用所有规则后选择性启用

# pylint: disable=all
# pylint: enable=unused-variable,undefined-variable

import os  # 不会触发 unused-import 警告

6.4 通过文件/目录排除屏蔽

参考：Main Checker 选项

[tool.pylint.main]
# 按文件/目录名忽略（不进行任何检查）
ignore = ["venv", "migrations", "__pycache__"]

# 按正则表达式匹配路径忽略
ignore-paths = ["^tests/", "^migrations/"]

# 忽略特定模块的导入检查
ignored-modules = ["my_optional_library"]

6.5 通过 pre-commit 框架屏蔽

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: pylint
        name: pylint
        entry: pylint
        language: system
        types: [python]
        require_serial: true
        files: ^src/ # 仅检查 src/ 目录下的文件
        exclude: ^src/tests/ # 排除 src/tests/ 目录
        args: ["-rn", "-sn"]

6.6 告警抑制最佳实践

优先使用配置文件：对于项目级别的规则调整，优先在 pyproject.toml 中配置 disable，避免代码注释污染。
行级注释需说明原因：如果屏蔽原因在规则名称中不够清晰，应添加注释说明。
定期审查屏蔽列表：启用 useless-suppression 警告可以检测已失效的 # pylint: disable 注释。
优先使用 # pylint: disable=rule-name 语法，而非旧语法 # pylint: disable-msg=rule-name。

附录：常用规则速查表

规则代码	符号名	类别	说明
C0114	missing-module-docstring	C	缺少模块文档字符串
C0115	missing-class-docstring	C	缺少类文档字符串
C0116	missing-function-docstring	C	缺少函数/方法文档字符串
C0103	invalid-name	C	命名不符合规范
C0301	line-too-long	C	行过长
C0304	missing-final-newline	C	文件末尾缺少换行
C0305	trailing-newlines	C	文件末尾多余空行
C0411	wrong-import-order	C	导入顺序错误
C0412	ungrouped-imports	C	导入分组错误
C0413	wrong-import-position	C	导入位置不在文件顶部
E0401	import-error	E	导入错误（模块不存在）
E0601	used-before-assignment	E	变量使用前未赋值
E0602	undefined-variable	E	使用了未定义的变量
E1101	no-member	E	对象没有该成员
E1102	not-callable	E	对象不可调用
R0901	too-many-ancestors	R	类的继承层级过深
R0902	too-many-instance-attributes	R	实例属性过多
R0903	too-few-public-methods	R	类的公共方法过少
R0911	too-many-return-statements	R	返回语句过多
R0912	too-many-branches	R	分支过多
R0913	too-many-arguments	R	函数参数过多
R0914	too-many-locals	R	局部变量过多
R0915	too-many-statements	R	语句过多
R1701	consider-merging-isinstance	R	建议合并 isinstance 调用
R1702	too-many-nested-blocks	R	嵌套块过多
R1705	no-else-return	R	if-return-else 结构建议简化
W0511	fixme	W	TODO/FIXME 注释
W0602	global-variable-not-assigned	W	定义了全局变量但未赋值
W0603	global-statement	W	使用了 global 语句
W0611	unused-import	W	导入了未使用的模块
W0612	unused-variable	W	定义了未使用的变量
W0613	unused-argument	W	函数参数未使用
W0621	redefined-outer-name	W	重定义了外部变量名
W0622	redefined-builtin	W	重定义了内置名称
W0702	bare-except	W	裸 except 子句
W0718	broad-exception-caught	W	捕获过于宽泛的 Exception
W1309	f-string-without-interpolation	W	f-string 中没有插值表达式