6.4. textwrap — 文本换行和填充 — Python 文档

来自菜鸟教程
Python/docs/3.6/library/textwrap
跳转至:导航、​搜索

6.4. 文本换行 — 文字环绕和填充

源代码: :source:`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() 函数之前被折叠,所以改变 tabsize, expand_tabs 的值]、drop_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)如果为真,则 text 中的所有制表符将使用 textexpandtabs() 方法扩展为空格。

tabsize

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

3.3 版中的新功能。

replace_whitespace

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

笔记

如果 expand_tabs 为假且 replace_whitespace 为真,则每个制表符将替换为单个空格,与制表符扩展相同

笔记

如果 replace_whitespace 为 false,换行符可能会出现在一行的中间并导致奇怪的输出。 出于这个原因,文本应该被分成单独包装的段落(使用 str.splitlines() 或类似的)。

drop_whitespace

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

initial_indent

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

subsequent_indent

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

fix_sentence_endings

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

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

和“现货”。 在

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

fix_sentence_endings 默认为 false。

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

break_long_words

(默认:True)如果为真,那么长于 width 的单词将被断开,以确保没有行长于 width。 如果为false,长字不会断,有些行可能比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)

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

fill(text)

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