textwrap

2.3版本的新功能。

源代码： Lib / textwrap.py

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

textwrap.wrap(text[, width[, ...]])

包装文本中的单个段落（一个字符串），因此每行至多是宽度字符长。返回输出行的列表，没有最终的换行符。

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

有关wrap（）行为的更多详细信息，请参阅TextWrapper.wrap（）方法。

textwrap.fill(text[, width[, ...]])

包装文本中的单个段落，并返回包含包装段落的单个字符串。 fill（）是简写.

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

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

wrap()与fill()通过创建一个工作TextWrapper实例，并调用它的单个方法。这个实例没有被重用，所以对于包装/填充许多文本字符串的应用程序来说，创建自己的TextWrapper对象会更有效率。

文本最好包装在空格中，紧接连字符后的连字符后面; 只有这样，如果有必要，长词将被打破，除非TextWrapper.break_long_words被设置为假。

还提供了一个额外的实用函数dedent（），用于删除在文本左边有不需要的空白字符串的缩进。

textwrap.dedent(text)

从文本中的每一行删除任何常见的空白字符。

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

请注意，制表符和空格都被视为空白，但它们并不相同：行“hello”和“\ thello”被认为没有共同的前导空格。 （这种行为在Python 2.5中是新的;在搜索常用的前导空格之前，该模块的旧版本错误地扩展了制表符。）

例如：

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'

class textwrap.TextWrapper(...)

该TextWrapper构造函数接受多种可选关键字参数。每个参数对应一个实例属性，例如

wrapper = TextWrapper(initial_indent="* ")

与以下形式类似：

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

您可以多次重复使用同一个TextWrapper对象，并且可以通过直接分配给用例之间的实例属性来更改其任何选项。

TextWrapper是实例属性（和关键字参数构造函数），如下所示：

width

（默认值：70）包装线的最大长度。 只要输入文本中没有单个单词长度超过宽度，TextWrapper就会保证没有输出行比宽度字符长。

expand_tabs

（默认值：True）如果为true，则文本中的所有制表符将使用文本的expandtabs（）方法展开为空格。

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，则会删除每行的开头和结尾处的空白（包装之后但缩进之前）。但是，如果非空白符号跟随，则在段落开始处的空格不会被删除。如果被删除的空白占用了整行，整行将被删除。

2.6版本中的新功能：在早期版本中，空白总是被删除。

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，那么比宽度更长的单词将被打破，以确保没有行比宽度长。 如果它是错误的，那么很长的单词不会被打破，并且一些行可能会比宽度更长。 （长字将自行放在一行上，以最大限度地减少超出的宽度。）

break_on_hyphens

（默认值：True）如果为true，则最好在复合词中的空格和紧接连字符后面进行换行，因为这在英语中是习惯的。 如果为false，则只有空格才会被视为潜在的换行符，但如果您想要真正的不可拆分的单词，则需要将break_long_words设置为false。 以前版本的默认行为是始终允许打破带连字符的单词。

2.6版本中的新功能。

TextWrapper 还提供了两种公共方法，类似于模块级别的便利功能：

wrap(text)

包装文本中的单个段落（一个字符串），因此每行至多是宽度字符长。 所有包装选项都取自TextWrapper实例的实例属性。 返回输出行的列表，没有最终的换行符。 如果包装的输出没有内容，则返回的列表为空。

fill(text)

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