Python inspect.cleandoc 怎样整理多行帮助文本缩进

把多行帮助文字传给 inspect.cleandoc(text)，可以去掉因 Python 代码块排版带入的公共缩进，同时保留列表项之间的相对层级。它对首行采用独立规则，并清理首尾空行，适合把源码中排版整齐的说明文字用于展示。

官方地址：https://www.python.org/

函数文档：https://docs.python.org/3/library/inspect.html#inspect.cleandoc

这项标准库能力适合哪些帮助文本

这里介绍的是标准库已有能力，不能把它当成一次新版本发布。实际用途是：帮助文本写在函数、类或其他缩进代码中，展示时却不想携带那一层源码空格。无需安装第三方包，也不需要逐行调用 lstrip()。

输入是一段字符串，返回整理后的字符串，原字符串不被原地修改。它负责排版缩进，不负责自动换行、翻译文字或识别 Markdown 语义。如果帮助内容本来就依靠绝对空格数量表达格式，应先决定哪些空格允许删除。

快速试用：保留列表的相对缩进

下面的帮助文本在源码里保留统一的四空格外缩进，选项说明再多缩进四格。清理时消除的是公共外层，选项的相对缩进仍有意义。

import inspect

def build_help():
    # 字符串跟随函数缩进书写，列表项额外缩进表示层级。
    source = """
    用法：report
        --format  输出格式
        --limit   条目上限
    """
    # 一次整理整个文本，避免逐行去空格导致层级丢失。
    return inspect.cleandoc(source)

text = build_help()
print(text)
# repr 用于观察换行与空格，不把显示效果当成运行证据。
print(repr(text))

按该示例的文字布局，整理后的首行从“用法”开始，两个选项仍各有四个前导空格，尾部不保留三引号位置带入的空行。示例用于说明预期语义，本文不声称已在某台机器运行。

首行和空行为什么要单独理解

理解 cleandoc 时，可把文本区分成首行、后续非空行和空行。首行的前导空白单独移除；后续部分按照能够共同移除的缩进量整理，额外缩进继续保留。制表符会展开为空格，因此它不适合要求原样保留 Tab 字符的内容。

首尾空行会清理，正文段落中间的空行仍可承担分段作用。它不是“把所有空白删掉”，也不保证每一行都贴着左边缘：有一个后续非空行没有缩进，其他后续行就可能没有共同可移除的外层。

import inspect

# 首行紧跟引号，后续正文统一缩进，子项再多一层。
source = "    参数说明\n        常规选项\n            详细选项\n\n"
cleaned = inspect.cleandoc(source)
# 用分行后的字符串表示检查排版；每行内部空格仍应保留。
print([repr(line) for line in cleaned.splitlines()])

这个布局中，“参数说明”前的四个空格按首行规则去除；后两行共有八个前导空格，“详细选项”在去除公共部分后仍留四格。不要把首行原有的四格当作后续行的统一删除量。

与 strip、dedent 怎样选择

区别在“首行已经顶格、后面正文有缩进”时尤其明显。dedent 的共同缩进可能被首行限制为零；cleandoc 能分别对待首行和其余正文。两者对制表符的处理也不同，不能在混合 Tab 与空格的输入上直接认为等价。

import inspect
import textwrap

# 首行无缩进，正文有四个空格，适合观察两种整理规则。
source = "概要\n    正文说明"
print(repr(textwrap.dedent(source)))
print(repr(inspect.cleandoc(source)))
# 不逐行使用 strip，否则本来有意义的列表层级也会被删除。

这里的预期差异是：dedent 仍保留正文前的四格，而 cleandoc 会移除这层正文公共缩进。选择方法应依据文本布局约定，而不是根据函数名字推测功能强弱。

接入帮助入口时保留哪些约定

在命令行帮助、说明面板或通知模板的展示入口统一整理，比在每个字符串拼接点都清理更容易维护。保存一份原始文本，展示时再生成整理后的版本；如果业务要求文本末尾有换行，应明确补上，而非依赖源字符串结尾的空行。

import inspect

def render_help(raw_text):
    # 缺失帮助允许为空，但异常输入不静默转成文本。
    if raw_text is None:
        return ""
    if not isinstance(raw_text, str):
        raise TypeError("帮助文本必须是字符串或 None")
    cleaned = inspect.cleandoc(raw_text)
    # 此展示入口约定：非空内容以一个换行结束。
    return cleaned + "\n" if cleaned else ""

函数会自动读取对象的文档吗？ 不会，cleandoc 接收的是文本；需要从对象读取文档时可了解 inspect.getdoc，它会处理文档获取与清理，但那是另一项职责。

可以整理 YAML 或 Python 源码吗？ 不宜把帮助文本清理规则直接套到语义依赖缩进的文件上，特别是首行与其他行采用不同规则时。需要无损读取时应保留原文。

为什么中间还有空行？ 内部空行可能就是段落分隔；如果产品要求折叠它们，需要另外定义内容规则。对于普通帮助文字，保留段落和相对层级通常比逐行删空格更合适。

采用前只需明确三个约定：输入是否允许缺失、内部缩进是否有意义、展示端是否需要结尾换行。cleandoc 能解决源码缩进带来的排版偏移，但不替代这些业务约定。

延伸文档：https://docs.python.org/3/library/textwrap.html#textwrap.dedent