Skip to main content

6.4. textwrap —文本包装和填充

源代码: Lib/textwrap.py


textwrap 模块提供了一些方便的功能,以及 TextWrapper,完成所有工作的类。如果你只是包装或填充一个或两个文本字符串,方便的功能应该是足够好;否则,您应该使用 TextWrapper 的实例来提高效率。

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

将单个段落包含在 text (字符串)中,因此每行最多 width 个字符长。返回输出行的列表,没有最后的换行符。

可选的关键字参数对应于 TextWrapper 的实例属性,如下所述。 width 默认为 70

有关 wrap() 行为的更多详细信息,请参阅 TextWrapper.wrap() 方法。

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

将单个段落包装在 text 中,并返回包含包装段落的单个字符串。 fill() 是缩写

"\n".join(wrap(text, ...))

特别是,fill() 接受与 wrap() 完全相同的关键字参数。

textwrap.shorten(text, width, **kwargs)

折叠和截断给定的 text 以适合给定的 width

首先,text 中的空格被折叠(所有空格都由单个空格替换)。如果结果符合 width,则返回。否则,从末端丢弃足够的单词,使得剩余的单词加上 placeholder 适合 width:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

可选的关键字参数对应于 TextWrapper 的实例属性,如下所述。请注意,在将文本传递给 TextWrapper fill() 函数之前,空格已折叠,因此更改 tabsizeexpand_tabsdrop_whitespacereplace_whitespace 的值将不起作用。

3.4 新版功能.

textwrap.dedent(text)

text 中的每一行删除任何共同的前导空白。

这可以用于使三引号字符串与显示器的左边缘对齐,同时仍以缩进形式在源代码中呈现它们。

请注意,制表符和空格都被视为空格,但它们不相等:线 "  hello""\thello" 被认为没有共同的前导空格。

例如:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'
textwrap.indent(text, prefix, predicate=None)

prefix 添加到 text 中选定行的开头。

线通过调用 text.splitlines(True) 分隔。

默认情况下,prefix 添加到不仅由空格组成的所有行(包括任何行尾)。

例如:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

可选的 predicate 参数可用于控制哪些行缩进。例如,很容易将 prefix 添加到甚至空和空白行:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

3.3 新版功能.

wrap()fill()shorten() 通过创建一个 TextWrapper 实例并调用其上的单个方法来工作。该实例不被重用,因此对于使用 wrap() 和/或 fill() 处理许多文本字符串的应用程序,创建自己的 TextWrapper 对象可能更有效。

文本最好包裹在空格上,紧跟在连字符后面;只有这样,如果有必要,长字会被破坏,除非 TextWrapper.break_long_words 设置为false。

class textwrap.TextWrapper(**kwargs)

TextWrapper 构造函数接受一些可选的关键字参数。每个关键字参数对应一个实例属性,例如

wrapper = TextWrapper(initial_indent="* ")

是相同的

wrapper = TextWrapper()
wrapper.initial_indent = "* "

您可以多次重复使用相同的 TextWrapper 对象,您可以通过在使用之间直接分配实例属性来更改其任何选项。

TextWrapper 实例属性(和构造函数的关键字参数)如下:

width

(默认值:70)包装行的最大长度。只要输入文本中没有比 width 长的单个词,TextWrapper 就保证没有输出行长于 width 字符。

expand_tabs

(默认值:True)如果为true,则 text 中的所有制表符将使用 textexpandtabs() 方法扩展为空格。

tabsize

(默认值:8)如果 expand_tabs 为真,则 text 中的所有制表符字符将扩展为零或更多空格,具体取决于当前列和给定的制表符大小。

3.3 新版功能.

replace_whitespace

(默认:True)如果为true,在选项卡扩展之后但在换行之前,wrap() 方法将用单个空格替换每个空格字符。替换的空格字符如下:制表符,换行符,垂直制表符,换行符和回车符('\t\n\v\f\r')。

注解

如果 expand_tabs 为假,replace_whitespace 为真,则每个制表符将由单个空格替换,即与制表符展开相同的 not

注解

如果 replace_whitespace 为假,则换行符可能出现在行的中间并导致奇怪的输出。因此,文本应该分割成单独包装的段落(使用 str.splitlines() 或类似)。

drop_whitespace

(默认值:True)如果为true,则删除每行的开始和结尾处的空格(在换行之后但在缩进之前)。但是,如果非空格跟在它后面,则在段落开头的空格不会被删除。如果删除的空白占据整个行,则整行被删除。

initial_indent

(默认值:'')将被添加到包装输出的第一行的字符串。计数到第一行的长度。空字符串不缩进。

subsequent_indent

(默认:'')将添加到除第一个之外的包装输出的所有行的字符串。计算每行除第一行之外的长度。

fix_sentence_endings

(默认:False)如果为true,TextWrapper 会尝试检测句子结尾,并确保句子总是以两个空格分隔。这通常对于等宽字体中的文本是期望的。然而,句子检测算法是不完美的:它假设句子结尾由小写字母后跟 '.''!''?' 之一,可能后跟 '"'"'" 之一,后跟一个空格。这个的一个问题是算法是不能检测“博士”之间的差异在

[...] Dr. Frankenstein's monster [...]

和“Spot”。在

[...] See Spot. See Spot run [...]

缺省情况下,fix_sentence_endings 为false。

由于语句检测算法依赖于 string.lowercase 来定义“小写字母”,以及在句点之后使用两个空格来分隔同一行上的句子的惯例,所以它特定于英语文本。

break_long_words

(默认值:True)如果为真,则长于 width 的字将被断开,以确保没有行长于 width。如果为假,长字不会被破坏,并且一些行可能比 width 长。 (长单词将自己放在一条线上,以便最大限度地减少超过 width 的量。)

break_on_hyphens

(默认值:True)如果为true,则包装将优先在空格上出现,紧跟在复合词中的连字符后面,这是英语中习惯的。如果为false,只有空格被认为是换行符的潜在好地方,但如果你想要真正不可靠的单词,你需要将 break_long_words 设置为false。以前版本中的默认行为是始终允许断开连字符词。

max_lines

(默认:None)如果不是 None,则输出将包含至多 max_lines 行,其中 placeholder 出现在输出的末尾。

3.4 新版功能.

placeholder

(默认:' [...]')如果已被截断,将出现在输出文本末尾的字符串。

3.4 新版功能.

TextWrapper 还提供了一些公共方法,类似于模块级的方便功能:

wrap(text)

将单个段落包含在 text (字符串)中,因此每行最多 width 个字符长。所有包装选项都取自 TextWrapper 实例的实例属性。返回输出行的列表,没有最后的换行符。如果包装的输出没有内容,则返回的列表为空。

fill(text)

将单个段落包装在 text 中,并返回包含包装段落的单个字符串。