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)

将单个段落包含在文本中,并返回包含包装段落的单个字符串。fill()是下面语句的简写形式

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

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

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

折叠并截断给定的文本以适合给定的宽度

首先,文本中的空格将折叠(所有空格都由单个空格替换)。如果结果符合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的实例属性,如下所述。Note that the whitespace is collapsed before the text is passed to the TextWrapper fill() function, so changing the value of tabsize, expand_tabs, drop_whitespace, and replace_whitespace will have no effect.

新版本3.4.

textwrap.dedent(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)

前缀添加到文本中选定行的开头。

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

默认情况下,前缀添加到不包含空格(包括任何行结尾)的所有行。

例如:

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

可选的谓词参数可用于控制哪些行缩进。例如,很容易将前缀添加到即使为空和纯空格的行:

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

版本3.3中的新功能。

wrap()fill()shorten()通过创建TextWrapper类来实现功能。创建的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

(default: True) If true, then all tab characters in text will be expanded to spaces using the expandtabs() method of text.

tabsize

(默认:8)如果expand_tabs为真,则文本中的所有制表符将扩展为零个或多个空格,列和给定的制表符大小。

版本3.3中的新功能。

replace_whitespace

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

注意

如果expand_tabs为false,且replace_whitespace为真,则每个制表符字符将被替换为单个空格,即而不是制表符展开。

注意

如果replace_whitespace为false,则换行符可能会出现在行的中间并导致奇怪的输出。出于这个原因,文本应该被分割成段(使用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)如果为true,则长度大于width的字符将被破坏,以确保没有行长度大于width如果为假,长字不会被破坏,并且一些行可能长于width(长字自行放在一条线上,以尽量减少超过width的量。)

break_on_hyphens

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

max_lines

(默认:None)如果不是None,则输出将包含最多max_lines行,并显示占位符在输出结束时。

新版本3.4.

placeholder

(默认值:' [...]')将在输出文本末尾出现的字符串

新版本3.4.

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

wrap(text)

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

fill(text)

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