pydocstyle：Python 文档字符串风格检查器

pydocstyle 在 GitHub 上拿到了 1,120 Star。

这是一个静态分析工具，专门检查 Python 文档字符串是否符合 PEP 257 规范。

1、 这玩意儿是干嘛的

写 Python 的人都知道文档字符串的重要性，但记住 PEP 257 的全部细则并不容易。函数有没有写 docstring？引号用的是单引还是三个双引？函数体和 docstring 之间是不是多空了行？类里的文档字符串格式对不对？

pydocstyle 就是来解决这些细碎问题的。它把 PEP 257 的规则编成了具体的检查项，扫描代码后逐条报出违规位置。每个问题都有固定的规则编号：D101 表示公共模块缺少文档字符串，D300 表示没使用三个双引号，D201 表示函数和文档字符串之间出现了多余空行。

这种编号体系的好处是直接。你在代码里看到报错，查一下编号就知道违反了哪条规则。团队也可以基于这些编号做配置，统一忽略或强制某些检查项。对于大型项目来说，这种颗粒度的控制很必要。

2、 怎么用

安装一条命令搞定：

pip install pydocstyle

命令行直接跑：

$ pydocstyle test.py
test.py:18 in private nested class `meta`:
        D101: Docstring missing
test.py:27 in public function `get_user`:
    D300: Use """triple double quotes""" (found '''-quotes)
test:75 in public function `init_database`:
    D201: No blank lines allowed before function docstring (found 1)

输出里会告诉你文件名、行号、所在的位置，以及具体的违规项。每条规则都有文档说明，报错信息也足够清晰，修起来不费劲。你也可以把 pydocstyle 集成到 CI 流程里，在代码提交前自动跑一遍检查。

3、 项目现状

pydocstyle 已经不再维护了。官方在 README 顶部挂了弃用通知，明确建议用户迁移到 Ruff。

Ruff 是用 Rust 写的 Python 代码检查工具，覆盖了 pydocstyle 的全部规则，还集成了 flake8、isort、pyupgrade 等功能。从 pydocstyle 切过去，规则编号和报错格式基本保持一致，迁移成本很低。

4、 为什么还值得了解

虽然项目本身退役了，但它留下的规则编号体系被 Ruff 完整继承。很多 Python 项目里你看到的 D1xx、D2xx、D3xx、D4xx 规则，源头都是 pydocstyle。

对于还在维护老代码、或者想理解 Python 文档字符串规范的开发者来说，翻翻这个项目的规则定义仍有价值。它把 PEP 257 里那些抽象的文本描述，变成了可执行、可量化的检查项。这种将规范落地为工具的思路，也影响了后来很多类似的静态分析项目。

本描述，变成了可执行、可量化的检查项。这种将规范落地为工具的思路，也影响了后来很多类似的静态分析项目。