textwrap 是 Python 标准库中的一个非常有用的模块，专门用于处理文本的自动换行和填充，它的主要目标是让长文本在指定宽度的容器（如终端窗口、GUI 控件等）中显示得更加美观和易读。

textwrap 模块的核心功能可以概括为两点：

1. 填充：在文本的每一行末尾添加足够的空格，使所有行的长度都等于指定的宽度。
2. 换行：将长文本在指定的宽度处分割成多行。

下面我们通过详细的讲解和示例来深入了解它。

核心函数

textwrap 模块提供了几个核心函数，其中最常用的是 wrap() 和 fill()。

textwrap.wrap(text, width=70, ...)

这个函数将输入的文本分割成一个行的列表。

• text: 要处理的字符串。
• width: 每行的最大字符数，默认为 70。
• 返回值: 一个字符串列表，列表中的每个元素都是一行文本。

示例：

import textwrap
long_text = (
    "这是一个非常长的句子，我们需要使用 textwrap 模块来对它进行自动换行处理，"
    "看看效果如何，它会在你指定的宽度处将文本分割成多行，非常适合在终端或命令行工具中使用。"
)
# 使用默认宽度 70
wrapped_lines = textwrap.wrap(long_text)
print("使用默认宽度 70:")
print(wrapped_lines)
# 输出:
# ['这是一个非常长的句子，我们需要使用 textwrap 模块来对它进行自动换行处理，',
#  '看看效果如何，它会在你指定的宽度处将文本分割成多行，非常适合在终端或命令行工具中使用。']
print("\n使用宽度 20:")
wrapped_lines_20 = textwrap.wrap(long_text, width=20)
print(wrapped_lines_20)
# 输出:
# ['这是一个非常长的句子，',
#  '我们需要使用 textwrap',
#  '模块来对它进行自动换行',
#  '处理，看看效果如何。',
#  '它会在你指定的宽度处',
#  '将文本分割成多行，',
#  '非常适合在终端或命令行',
#  '工具中使用。']

textwrap.fill(text, width=70, ...)

这个函数是 wrap() 的一个便捷封装，它内部调用了 wrap()，然后将返回的行列表用换行符 \n 连接成一个单一的字符串。

• text: 要处理的字符串。
• width: 每行的最大字符数，默认为 70。
• 返回值: 一个单一的、包含换行符的字符串。

示例：

import textwrap
long_text = (
    "这是一个非常长的句子，我们需要使用 textwrap 模块来对它进行自动换行处理，"
    "看看效果如何，它会在你指定的宽度处将文本分割成多行，非常适合在终端或命令行工具中使用。"
)
# 使用 fill 函数
filled_text = textwrap.fill(long_text, width=20)
print("使用 fill 函数，宽度为 20:")
print(filled_text)
# 输出:
# 这是一个非常长的句子，
# 我们需要使用 textwrap
# 模块来对它进行自动换行
# 处理，看看效果如何。
# 它会在你指定的宽度处
# 将文本分割成多行，
# 非常适合在终端或命令行
# 工具中使用。

wrap() vs fill() 的选择：

• 如果你需要逐行处理（写入文件时每行单独处理），使用 wrap()。
• 如果你只需要一个可以直接打印或显示的完整字符串,使用 fill() 更方便。

核心类 textwrap.TextWrapper

当你需要更精细地控制换行行为时,应该使用 TextWrapper 类，它允许你设置各种属性，然后将这个配置好的“包装器”对象重复使用。

常用属性：

示例：

让我们创建一个配置好的 TextWrapper 对象。

import textwrap
# 示例文本
paragraph = (
    "这是一个段落，它包含多个句子，textwrap 模块非常强大。"
    "我们可以通过 TextWrapper 类进行高度自定义的格式化。"
    "设置首行缩进和后续行缩进。"
)
# 创建一个 TextWrapper 实例
wrapper = textwrap.TextWrapper(
    width=30,
    initial_indent="    ",  # 第一行缩进4个空格
    subsequent_indent="    ", # 其他行也缩进4个空格
    break_long_words=False,   # 不允许在单词中间断开
    break_on_hyphens=True    # 允许在连字符处断开
)
# 使用 wrap 方法
formatted_lines = wrapper.wrap(paragraph)
print("使用 TextWrapper 格式化:")
print("\n".join(formatted_lines))
# 输出:
#     这是一个段落，它包含
#     多个句子，textwrap 模块
#     非常强大，我们可以通过
#     TextWrapper 类进行高度
#     自定义的格式化。
#     设置首行缩进和后续行
#     缩进。
# 使用 fill 方法
formatted_text = wrapper.fill(paragraph)
print("\n使用 TextWrapper 的 fill 方法:")
print(formatted_text)
# 输出与上面相同

高级用法和常见场景

场景1：去除文本多余空白并格式化

从文件或网络获取的文本可能包含多余的换行和空格。TextWrapper 的 replace_whitespace 和 drop_whitespace 属性可以很好地处理这个问题。

import textwrap
# 模拟一个格式混乱的文本
messy_text = """  这是一个    有很多多余空白
    和换行的文本。
    我们需要将它清理并格式化。  """
# 创建一个包装器，清理空白并设置宽度
wrapper = textwrap.TextWrapper(
    width=40,
    replace_whitespace=True, # 将所有空白转为空格
    drop_whitespace=True     # 去掉行首行尾的空格
)
clean_and_formatted = wrapper.fill(messy_text)
print("清理并格式化后的文本:")
print(cleanish_and_formatted)
# 输出:
# 这是一个    有很多多余空白 和换行的文本。
# 我们需要将它清理并格式化。

场景2：生成列表或项目符号

通过结合 initial_indent 和 subsequent_indent，可以轻松生成带项目符号的列表。

import textwrap
items = [
    "第一项：学习 Python 的基础语法",
    "第二项：熟悉标准库，如 os, sys, re",
    "第三项：掌握常用的第三方库，如 requests, pandas",
    "第四项：实践项目，构建完整的应用程序"
]
# 为每个项目创建包装器
wrapper = textwrap.TextWrapper(
    width=50,
    initial_indent="* ",
    subsequent_indent="  "
)
# 对每个项目进行格式化并打印
for item in items:
    print(wrapper.fill(item))

输出:

* 第一项：学习 Python 的基础语法
  第二项：熟悉标准库，如 os, sys, re
* 第三项：掌握常用的第三方库，如 requests, pandas
  第四项：实践项目，构建完整的应用程序

(注意：这里为了演示，subsequent_indent 的效果可能和预期略有不同，因为它会从 initial_indent 的末尾开始计算缩进，更精确的控制可能需要更复杂的逻辑。)

场景3：处理不可断开的单词（URL、长代码）

对于像 URL 这样的长字符串，我们不希望它在中间被断开，这时可以将 break_long_words 设置为 False。

import textwrap
text_with_url = "请访问我们的官方网站了解更多信息：https://www.example.com/this-is-a-very-long-url-that-should-not-be-broken"
# 默认情况（允许断开单词）
print("默认行为（允许断开单词）:")
print(textwrap.fill(text_with_url, width=40))
print("\n" + "="*40 + "\n")
# 禁止断开长单词
wrapper = textwrap.TextWrapper(width=40, break_long_words=False)
print("禁止断开长单词:")
print(wrapper.fill(text_with_url))

输出:

默认行为（允许断开单词）:
请访问我们的官方网站了解更多信息：
https://www.example.com/this-is-a-very-
long-url-that-should-not-be-broken
========================================
禁止断开长单词:
请访问我们的官方网站了解更多信息：
https://www.example.com/this-is-a-very-long-url-that-should-not-be-broken

可以看到,当 break_long_words=False 时，如果一行放不下整个 URL，它会将整个 URL 移到下一行，而不是在中间断开。

textwrap 模块是 Python 中处理文本格式的利器，尤其适用于命令行工具、日志格式化、生成报告等场景。

• 简单需求：直接使用 textwrap.fill() 或 textwrap.wrap()。
• 复杂需求：创建 textwrap.TextWrapper 实例，通过设置其属性（如 width, indent, break_long_words 等）来实现高度定制化的文本格式化。

掌握 textwrap 模块，能让你的 Python 程序在处理和展示文本时变得更加专业和优雅。