`textwrap` — 文本换行和填充¶

textwrap 模块提供了一些方便的函数，以及 TextWrapper 类，该类执行所有工作。如果您只是要换行或填充一两个文本字符串，那么使用这些便利函数就足够了；否则，为了效率，您应该使用 TextWrapper 的实例。

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')¶

将 text （一个字符串）中的单个段落换行，使每行的长度最多为 width 个字符。返回一个输出行列表，不带最后的换行符。

可选的关键字参数与下面文档中 TextWrapper 的实例属性相对应。

有关 wrap() 如何工作的更多详细信息，请参阅 TextWrapper.wrap() 方法。

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')¶

将 text 中的单个段落换行，并返回一个包含换行段落的单个字符串。 fill() 是以下内容的简写

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

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

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')¶

折叠并截断给定的 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_whitespace 和 replace_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 中的所有制表符将使用 text 的 expandtabs() 方法扩展为空格。

tabsize¶: （默认值：8）如果 expand_tabs 为 true，则 text 中的所有制表符将根据当前列和给定的制表符大小扩展为零个或多个空格。

在 3.3 版本中新增。

replace_whitespace¶: （默认值：True）如果为 true，则在制表符扩展之后但在换行之前，wrap() 方法会将每个空白字符替换为单个空格。替换的空白字符如下：制表符、换行符、垂直制表符、换页符和回车符 ('\t\n\v\f\r')。

注意

如果 expand_tabs 为 false 并且 replace_whitespace 为 true，则每个制表符将替换为单个空格，这与制表符扩展不相同。

注意

如果 replace_whitespace 为 false，则换行符可能会出现在行的中间并导致奇怪的输出。因此，文本应拆分为段落（使用 str.splitlines() 或类似方法），这些段落将单独换行。

drop_whitespace¶: （默认值：True）如果为 true，则每行开头和结尾的空格（换行之后但在缩进之前）将被删除。但是，如果段落的开头后跟非空格，则段落开头的空格不会被删除。如果要删除的空格占据了整行，则将删除整行。

initial_indent¶: （默认值：''）将添加到换行输出的第一行的字符串。计入第一行的长度。空字符串不缩进。

subsequent_indent¶: （默认值：''）将添加到除第一行之外的所有换行输出行的字符串。计入除第一行之外的每一行的长度。

fix_sentence_endings¶

（默认值：False）如果为 true，则 TextWrapper 会尝试检测句子结尾，并确保句子之间始终恰好分隔两个空格。这通常是单空格字体中所需的文本。但是，句子检测算法并不完善：它假设句子结尾由小写字母后跟 '.'、'!' 或 '?' 之一组成，可能后跟 '"' 或 "'" 之一，然后是一个空格。此算法的一个问题是它无法检测到以下内容中 “Dr.” 与

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

和以下内容中的 “Spot.” 之间的区别：

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

fix_sentence_endings 默认为 false。

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

break_long_words¶: （默认值：True）如果为 true，则长度大于 width 的单词将被打断，以确保没有行的长度大于 width。如果为 false，则长单词将不会被打断，并且某些行的长度可能大于 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 中的单个段落换行，并返回包含换行段落的单个字符串。

`textwrap` — 文本换行和填充¶

目录

上一主题

下一主题

本页

textwrap — 文本换行和填充¶

`textwrap` — 文本换行和填充¶