Python标准库之文本包装textwrap

Textwrap简介

textwrap是Python标准库中的一个模块，专门用于处理和格式化文本。它提供了多种方法，可以轻松地将文本格式化为指定宽度的段落、调整缩进、处理长字符串的换行等操作。textwrap模块非常适合用于生成命令行输出、处理用户输入或格式化报告。

产生背景

• 控制台输出需求: 在许多命令行应用程序中，需要将文本输出到固定宽度的控制台窗口或终端上。为了确保文本的可读性和整齐排列，开发者需要手动调整文本的宽度。
• 文档生成: 在自动生成文档或报告时，需要将文本格式化为符合某种标准的段落宽度，以便于阅读和打印。
• 提高开发效率: Python作为一种通用的编程语言，旨在通过提供各种实用工具来提高开发效率。textwrap模块正是为了简化文本格式化的常见任务而设计的。

使用场景

• 命令行应用程序: 在开发命令行工具时，textwrap可以用于格式化帮助信息、错误消息和其他文本输出，使其在不同的终端窗口中都能正确显示。
• 自动文档生成: 在生成自动化报告或文档时，可以使用textwrap将文本格式化为指定的段落宽度，以确保一致的布局。
• 电子邮件和消息格式化: 在发送电子邮件或消息时，可以使用textwrap来确保文本在不同的邮件客户端或消息应用中具有一致的格式。
• 日志文件格式化: 在记录日志信息时，确保日志条目具有一致的格式有助于提高可读性和可维护性。

textwrap核心功能

textwrap.fill()

fill()函数将一个字符串拆分为多个行，使每行的宽度不超过指定的width，并返回一个新的字符串，其中包含带有换行符的格式化文本。

参数：

• text：要格式化的字符串。
• width：每行的最大字符数，默认值为70。
• expand_tabs：是否将制表符转换为空格，默认值为True。
• replace_whitespace：是否替换所有的空白字符（如换行符、制表符）为单个空格，默认值为True。
• initial_indent：每段的第一行的缩进字符串，默认为空。
• subsequent_indent：每段的后续行的缩进字符串，默认为空。
• fix_sentence_endings：是否在句子结尾自动添加两个空格，默认值为False。
• break_long_words：是否在超长单词处进行换行，默认值为True。
• drop_whitespace：是否在每行的开头和结尾删除空白字符，默认值为True。
• max_lines：允许的最大行数，如果超过该行数则截断文本，默认为None。
• placeholder：当文本被截断时使用的占位符，默认值为’…’。

用法示例：

import textwrap

text = "This is a long paragraph that we want to wrap into lines of a specific width using the textwrap module."

# 使用fill函数将文本格式化为每行宽度为40的段落
formatted_text = textwrap.fill(text, width=40)
print(formatted_text)

# 输出:
# This is a long paragraph that we want
# to wrap into lines of a specific width
# using the textwrap module.

textwrap.wrap()

wrap()函数与fill()类似，但它返回的是一个字符串列表，每个元素对应一行文本。你可以根据需要对每行文本进行进一步处理。参数与fill()函数相同用法示例：

import textwrap

text = "This is a long paragraph that we want to wrap into lines of a specific width using the textwrap module."

# 使用wrap函数将文本格式化为每行宽度为40的字符串列表
wrapped_lines = textwrap.wrap(text, width=40)
for line in wrapped_lines:
    print(line)

# 输出:
# This is a long paragraph that we want
# to wrap into lines of a specific width
# using the textwrap module.

textwrap.dedent()

dedent()函数用于移除多行文本中每一行的公共前导空白字符（包括制表符和空格）。这在处理多行字符串时非常有用，尤其是当字符串包含多行代码或文本，需要保持一致的缩进时。

参数：

• text：要处理的字符串。

用法示例：

import textwrap

text = """\
    This is an example of text with
    inconsistent indentation levels.
    We want to dedent it."""

# 使用dedent函数移除前导空白字符
dedented_text = textwrap.dedent(text)
print(dedented_text)

# 输出:
# This is an example of text with
# inconsistent indentation levels.
# We want to dedent it.

textwrap.indent()

indent()函数用于给文本的每一行添加指定的前缀（如空格、制表符等）。它可以用于增加缩进，特别适合用于生成层级文本结构或在多行字符串中添加前导符号。

参数：

• text：要处理的字符串。
• prefix：要添加到每行的前缀字符串。
• predicate：可选参数，一个函数，用于判断哪些行需要添加前缀。如果未提供，则所有行都添加前缀。

用法示例：

import textwrap

text = "This is an example of text that will be indented."

# 使用indent函数在每行前添加'>>'
indented_text = textwrap.indent(text, prefix=">>")
print(indented_text)

# 输出:
# >>This is an example of text that will be indented.

textwrap.shorten()

shorten()函数用于将一段文本缩短到指定的宽度，并在截断处添加占位符（通常是…）。这个函数非常适合在显示有限字符数的场景（如UI界面、日志输出等）下使用。

参数：

• text：要处理的字符串。
• width：文本的最大宽度。
• placeholder：当文本被截断时使用的占位符，默认值为’…’。

用法示例：

import textwrap

text = "This is a long sentence that might need to be shortened."

# 使用shorten函数将文本缩短为不超过30个字符
shortened_text = textwrap.shorten(text, width=30)
print(shortened_text)

# 输出:
# This is a long sentence...

TextWrapper类

TextWrapper类是textwrap模块的核心类，它允许你创建自定义的文本格式化器，并提供了更细粒度的控制。fill()和wrap()函数实际上是通过该类实现的。

TextWrapper类的常用参数：

• width：每行的最大字符数，默认值为70。
• initial_indent：每段的第一行的缩进字符串，默认为空。
• subsequent_indent：每段的后续行的缩进字符串，默认为空。
• expand_tabs：是否将制表符转换为空格，默认值为True。
• replace_whitespace：是否替换所有的空白字符（如换行符、制表符）为单个空格，默认值为True。
• fix_sentence_endings：是否在句子结尾自动添加两个空格，默认值为False。
• break_long_words：是否在超长单词处进行换行，默认值为True。
• drop_whitespace：是否在每行的开头和结尾删除空白字符，默认值为True。

用法示例：

import textwrap

text = "This is a long paragraph that we want to wrap into lines of a specific width using the textwrap module."

# 创建一个自定义的TextWrapper对象
wrapper = textwrap.TextWrapper(width=40, initial_indent='', subsequent_indent='')

# 使用wrap方法将文本格式化
wrapped_text = wrapper.wrap(text)
for line in wrapped_text:
    print(line)

# 输出:
# This is a long paragraph that we want
# to wrap into lines of a specific
# width using the textwrap module.

参考链接：

• textwrap—文本自动换行与填充—Python 3.13.0文档
• Text Wrapping in Python with the Standard textwrap Module – αlphαrithms (alpharithms.com)