Python textwrap模块格式化长文本的缩进与换行

在Python开发中，处理从文件、数据库或API获取的杂乱长文本是常见需求。手动拼接字符串来控制换行和缩进既繁琐又容易出错。Python内置的 textwrap 模块专门用于解决这一问题，它能够自动将长文本拆分为指定宽度的段落，并灵活控制缩进。

以下步骤将演示如何利用该模块高效格式化文本。

1. 基础换行：fill 与 wrap

最基础的需求是将一段超长文本拆分成固定宽度的多行文本。

1. 导入 textwrap 模块。
2. 准备 一段没有换行的长字符串。
3. 调用 textwrap.fill() 函数，并传入文本和 width 参数（每行字符数）。

import textwrap

long_text = "Python是一种广泛使用的高级编程语言，由Guido van Rossum于1991年首次发布。它设计之初就强调代码的可读性，其语法允许程序员用比C++或Java更少的代码行表达概念。"

# 将文本格式化为每行最多20个字符
formatted_text = textwrap.fill(long_text, width=20)

print(formatted_text)

执行上述代码后，长字符串被强制在20个字符处断开。fill() 函数直接返回处理好的单个字符串，其中包含换行符。

如果你需要获取一个列表，其中每个元素代表一行，请使用 textwrap.wrap()。

lines_list = textwrap.wrap(long_text, width=20)
print(lines_list) 
# 输出: ['Python是一种广泛使用的', '高级编程语言，由', 'Guido van Rossum于', ...]

2. 精准控制缩进

在生成代码注释、帮助文档或邮件正文时，通常需要首行缩进或后续行缩进（如列表项）。

textwrap 提供了两个关键参数：

• initial_indent：首行的前缀字符串。
• subsequent_indent：后续所有行的前缀字符串。

1. 定义 需要展示的原始文本。
2. 设置 initial_indent 为 "\t" 或四个空格。
3. 设置 subsequent_indent 为特定的标记（如 "* "）。
4. 执行 fill() 函数。

sample_text = "这段文字演示了如何区分首行缩进和后续行缩进。这在制作列表或引用块时非常有用，可以让排版更加整洁。"

# 首行不缩进，后续行缩进4个空格
result = textwrap.fill(
    sample_text, 
    width=30, 
    initial_indent="",
    subsequent_indent="    "
)

print(result)

输出效果如下，后续行会自动对齐：

这段文字演示了如何区分
    首行缩进和后续行缩进。
    这在制作列表或引用
    块时非常有用，可以让
    排版更加整洁。

3. 处理多行字符串的空白：dedent

在Python代码中直接定义多行字符串时，往往会因为代码缩进导致字符串内部包含多余的空格。dedent 方法可以移除这些每一行开头的通用空白。

1. 定义 一个包含缩进的多行字符串（通常在函数或类内部）。
2. 使用 textwrap.dedent() 处理该字符串。
3. 观察 移除公共前导空格后的结果。

def get_help_text():
    # 这里的字符串本身带有代码层面的缩进
    raw_text = """
        这是一个帮助文档。
        它通常写在代码内部，
        但是包含了不需要的缩进。
    """
    return textwrap.dedent(raw_text)

clean_text = get_help_text()
print(clean_text)

dedent 会检测所有行中公共的前导空白并将其删除，使得文本的左边缘对齐。

4. 文本截断：shorten

当文本过长且只能显示固定长度（例如UI预览或摘要）时，可以使用 shorten。

1. 设定 目标宽度 width。
2. 调用 textwrap.shorten()。
3. 注意 该函数会自动在末尾添加 ... 以表示被截断。

long_desc = "Python的动态类型系统和内存管理功能，结合其全面的标准库，使其适用于各种应用领域。"

# 截断为15个字符宽度（包含...）
short_desc = textwrap.shorten(long_desc, width=15)

print(short_desc)
# 输出: Python的动...

5. 高级用法：TextWrapper 对象

如果需要对多个文本应用相同的格式化规则（例如宽度、缩进、是否保留换行符等），重复编写参数既低效又易错。此时应使用 TextWrapper 类。

1. 实例化 textwrap.TextWrapper 对象。
2. 配置 对象的属性（width, initial_indent, drop_whitespace 等）。
3. 调用 对象的 fill() 或 wrap() 方法处理不同文本。

常用的配置参数说明如下表：

代码示例：

# 初始化配置器
wrapper = textwrap.TextWrapper()
wrapper.width = 40
wrapper.initial_indent = "-> "
wrapper.subsequent_indent = "   "

text1 = "这是第一段文本，它将被统一格式化。"
text2 = "这是第二段文本，它将使用相同的缩进规则进行排版。"

# 复用配置器
print(wrapper.fill(text1))
print("---")
print(wrapper.fill(text2))

6. 处理逻辑流程

为了更直观地理解何时使用哪个功能，可以参考以下处理流程：

通过合理组合 dedent、fill 和 TextWrapper，可以应对几乎所有的纯文本格式化场景，无需依赖正则表达式或复杂的字符串切片操作。