如何用linter强制Python函数docstring包含参数及返回值说明

YAPF是代码格式化工具，仅负责调整代码排版格式，本身不具备docstring内容规范的校验能力，你找不到相关配置属于正常情况。可以通过以下linter工具组合实现需求：

1. 工具选型 #

• pydocstyle：专门用于Python docstring规范校验的工具，原生支持Google风格规范
• flake8-docstrings：flake8的插件，把pydocstyle的能力集成到flake8检查流程中
• darglint：专门校验docstring中参数、返回值说明和函数实际签名一致性的工具

2. 部署配置 #

首先安装所需依赖：

pip install pydocstyle flake8 flake8-docstrings darglint

在项目根目录创建.flake8配置文件，写入以下内容：

[flake8]
max-line-length = 120
extend-ignore = E203, W503
# 指定docstring遵循Google风格
docstring-convention = google
# darglint规则配置
darglint-style = google
# 启用强制校验规则
darglint-enable = ARG001, ARG002, RET001, RET002

上述启用的规则说明：

• ARG001：函数存在的参数未在docstring的Args段中说明，触发报错
• ARG002：docstring的Args段列出了函数实际没有的参数，触发报错
• RET001：函数有非None的返回值，但docstring未写Returns段，触发报错
• RET002：函数返回值为None，但docstring多余写了Returns段，触发报错

3. 使用方式 #

本地执行以下命令即可扫描项目中所有不符合规范的docstring：

flake8 你的项目目录名

你也可以把该命令集成到项目的CI流程中，不符合规范的代码无法合并到主分支；如果使用pre-commit工具，还可以把检查配置到提交钩子中，代码提交前就完成本地校验，提前拦截不合规内容。

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