docformatter：把 Python 文档字符串整得规规矩矩

docformatter 在 GitHub 上拿了 592 Star。这是一个专门处理 Python 文档字符串格式的小工具，核心目标就一个：让你的 docstring 符合 PEP 257 规范。

1、这玩意儿干嘛的

写 Python 的人都写过 docstring，但很少有人把引号位置、缩进、空行这些细节抠到完全合规。PEP 257 对文档字符串的格式有明确要求：统一使用三重双引号，单行字符串也要用三重引号包裹，多行文档字符串要在摘要行之后空一行，闭合引号要单独成行。

docformatter 自动处理这些规则。它还能和 black 配合使用，加上 --black 参数就能输出与 black 兼容的格式。同时也支持 Epytext 和 Sphinx 风格的字段列表格式化。

除了 PEP 257，它还处理了一些 PEP 8 的约定，比如不写依赖尾部空格的字符串字面量，因为这种空格在视觉上无法区分，而且部分编辑器会自动将其裁剪掉。

2、安装

通过 pip 安装：

$ pip install --upgrade docformatter

Python 版本低于 3.11 且想用 pyproject.toml 配置的话，装 tomli 版本：

$ pip install --upgrade docformatter[tomli]

Python 3.11 以上直接使用标准库的 tomllib，无需额外安装。

3、实际效果

跑一行命令：

$ docformatter --in-place example.py

处理前的代码可能是这样：

"""   Here are some examples.

    This module docstring should be dedented."""


def factorial(x):
    '''

    Return x factorial.

    This uses math.factorial.

    '''
    import math
    return math.factorial(x)

处理之后变成这样：

"""Here are some examples.

This module docstring should be dedented.
"""

def factorial(x):
    """Return x factorial.

    This uses math.factorial.
    """
    import math
    return math.factorial(x)

缩进、引号位置、多余空行全被修正，输出干净利落。

4、适合谁用

• 团队内推行代码规范，需要统一文档字符串格式的开发者
• 使用 black 做代码格式化，希望 docstring 也能保持一致风格的人
• 维护开源项目，需要批量清理遗留文档字符串的项目维护者
• 写了很多文档字符串但从未检查过 PEP 257 合规性的个人开发者

592 Star 不算多，但这是个工具属性很强的项目。它不解决什么复杂问题，就是把文档字符串的格式问题彻底搞定。如果你正在为团队里的文档字符串风格不统一发愁，这个工具值得一试。

92 Star 不算多，但这是个工具属性很强的项目。它不解决什么复杂问题，就是把文档字符串的格式问题彻底搞定。如果你正在为团队里的文档字符串风格不统一发愁，这个工具值得一试。