Repolode
提交项目
PyCQA

PyCQA/docformatter

一款自动将 Python 文档字符串格式化为 PEP 257 规范的命令行工具。

在 GitHub 查看官网
Star
600
Fork
98
未关闭 Issue
22
最近提交
4天前

这是什么？

docformatter 是一款 Python 命令行工具，用于重写文档字符串，使其符合 PEP 257 的部分规范。它会统一引号风格，多行文档字符串的结束引号单独成行，在摘要与详细描述之间插入空行，并清理多余的缩进和行尾空白。

工具既可以对单个文件原地修改，也可以批量处理整个项目。使用 --black 选项时，输出结果与 black 兼容；对 Epytext 和 Sphinx 风格的字段列表也能正确格式化。配置可以写在 pyproject.toml 中，Python 3.11 及以上版本使用标准库的 tomllib 读取。

适合希望在整个代码库中保持一致文档字符串风格、又不想逐个手动修改的 Python 开发者，尤其适合放入 lint 或 pre-commit 流程中运行。

核心功能

  • 01将文档字符串按照 PEP 257 的引号和排版规则重新格式化。
  • 02通过 --black 选项输出与 black 兼容的格式。
  • 03支持格式化 Epytext 和 Sphinx 风格的字段列表。
  • 04使用 --in-place 直接修改文件。
  • 05可从 pyproject.toml 读取配置。

适用场景

  • 统一 Python 项目中的文档字符串格式。
  • 在 pre-commit 钩子或 CI 检查中自动保证文档字符串风格一致。
  • 清理历史代码中引号和缩进不统一的文档字符串。

快速上手

  1. 1

    用 pip 从 PyPI 安装 docformatter

    pip install --upgrade docformatter
  2. 2

    就地格式化文件中的文档字符串

    docformatter --in-place example.py

收录于专题

代码检查与格式化工具

标签

#python#docstring#formatter#pep-257#code-style#linting#autoformat

常见问题

docformatter 是什么？
一款自动将 Python 文档字符串格式化为 PEP 257 规范的命令行工具。 docformatter 是一款 Python 命令行工具，用于重写文档字符串，使其符合 PEP 257 的部分规范。它会统一引号风格，多行文档字符串的结束引号单独成行，在摘要与详细描述之间插入空行，并清理多余的缩进和行尾空白。
docformatter 可以免费使用吗？用的什么许可证？
docformatter 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。
docformatter 还在维护吗？
活跃维护中。docformatter 最近一次提交是在 2026年11月3日。
docformatter 适合用来做什么？
统一 Python 项目中的文档字符串格式。 在 pre-commit 钩子或 CI 检查中自动保证文档字符串风格一致。 清理历史代码中引号和缩进不统一的文档字符串。
docformatter 怎么安装和运行？
用 pip 从 PyPI 安装 docformatter: pip install --upgrade docformatter 就地格式化文件中的文档字符串: docformatter --in-place example.py
在哪里获取 docformatter？
源代码和安装说明在 GitHub 上：https://github.com/PyCQA/docformatter

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目