7.7. textwrap — 文本自动换行与填充

2.3 新版功能.

源代码: Lib/textwrap.py

---

The textwrap module provides two convenience functions, wrap() and fill(), as well as TextWrapper, the class that does all the work, and a utility function dedent(). If you’re just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of TextWrapper for efficiency.

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

对 text (字符串) 中的单独段落自动换行以使每行长度最多为 width 个字符。 返回由输出行组成的列表，行尾不带换行符。

可选的关键字参数对应于 TextWrapper 的实例属性，具体文档见下。 width 默认为 70。

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

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

对 text 中的单独段落自动换行，并返回一个包含被自动换行段落的单独字符串。 fill() 是以下语句的快捷方式

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

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

Both wrap() and fill() work by creating a TextWrapper instance and calling a single method on it. That instance is not reused, so for applications that wrap/fill many text strings, it will be more efficient for you to create your own TextWrapper object.

文本最好在空白符位置自动换行，包括带连字符单词的连字符之后；长单词仅在必要时会被拆分，除非 TextWrapper.break_long_words 被设为假值。

An additional utility function, dedent(), is provided to remove indentation from strings that have unwanted whitespace to the left of the text.

textwrap.dedent(text)

移除 text 中每一行的任何相同前缀空白符。

这可以用来清除三重引号字符串行左侧空格，而仍然在源码中显示为缩进格式。

Note that tabs and spaces are both treated as whitespace, but they are not equal: the lines "  hello" and "\thello" are considered to have no common leading whitespace. (This behaviour is new in Python 2.5; older versions of this module incorrectly expanded tabs before searching for common leading whitespace.)

只包含空白符的行会在输入时被忽略并在输出时被标准化为单个换行符。

例如

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

The TextWrapper constructor accepts a number of optional keyword arguments. Each argument corresponds to one instance attribute, so for example

wrapper = TextWrapper(initial_indent="* ")

就相当于

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

你可以多次重用相同的 TextWrapper 对象，并且你也可以在使用期间通过直接向实例属性赋值来修改它的任何选项。

TextWrapper 的实例属性（以及构造器的关键字参数）如下所示：

width

(默认: 70) 自动换行的最大行长度。 只要输入文本中没有长于 width 的单个单词，TextWrapper 就能保证没有长于 width 个字符的输出行。

expand_tabs

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

replace_whitespace

(default: True) 如果为真值，在制表符扩展之后、自动换行之前，wrap() 方法将把每个空白字符都替换为单个空格。 会被替换的空白字符如下：制表，换行，垂直制表，进纸和回车 ('\t\n\v\f\r')。

注解

如果 expand_tabs 为假值且 replace_whitespace 为真值，每个制表符将被替换为单个空格，这与制表符扩展是 不 一样的。

注解

如果 replace_whitespace 为假值，在一行的中间有可能出现换行符并导致怪异的输出。 因此，文本应当（使用 str.splitlines() 或类似方法）拆分为段落并分别进行自动换行。

drop_whitespace

(默认: True) 如果为真值，每一行开头和末尾的空白字符（在包装之后、缩进之前）会被丢弃。 但是段落开头的空白字符如果后面不带任何非空白字符则不会被丢弃。 如果被丢弃的空白字符占据了一个整行，则该整行将被丢弃。

2.6 新版功能: Whitespace was always dropped in earlier versions.

initial_indent

(默认: '') 将被添加到被自动换行输出内容的第一行的字符串。 其长度会被计入第一行的长度。 空字符串不会被缩进。

subsequent_indent

(default: '') 将被添加到被自动换行输出内容除第一行外的所有行的字符串。 其长度会被计入除行一行外的所有行的长度。

fix_sentence_endings

(默认: False) 如果为真值，TextWrapper 将尝试检测句子结尾并确保句子间总是以恰好两个空格符分隔。 对于使用等宽字体的文本来说通常都需要这样。 但是，句子检测算法并不完美：它假定句子结尾是一个小写字母加字符 '.', '!' 或 '?' 中的一个，并可能带有字符 '"' 或 "'"，最后以一个空格结束。 此算法的问题之一是它无法区分以下文本中的 “Dr.”

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

和以下文本中的 “Spot.”

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

fix_sentence_endings 默认为假值。

Since the sentence detection algorithm relies on string.lowercase for the definition of “lowercase letter,” and a convention of using two spaces after a period to separate sentences on the same line, it is specific to English-language texts.

break_long_words

(默认: True) 如果为真值，则长度超过 width 的单词将被分开以保证行的长度不会超过 width。 如果为假值，超长单词不会被分开，因而某些行的长度可能会超过 width。 （超长单词将被单独作为一行，以尽量减少超出 width 的情况。）

break_on_hyphens

(默认: True) 如果为真值，将根据英语的惯例首选在空白符和复合词的连字符之后自动换行。 如果为假值，则只有空白符会被视为合适的潜在断行位置，但如果你确实不希望出现分开的单词则你必须将 break_long_words 设为假值。 之前版本的默认行为总是允许分开带有连字符的单词。

2.6 新版功能.

TextWrapper also provides two public methods, analogous to the module-level convenience functions:

wrap(text)

对 text (字符串) 中的单独段落自动换行以使每行长度最多为 width 个字符。 所有自动换行选项均获取自 TextWrapper 实例的实例属性。 返回由输出行组成的列表，行尾不带换行符。 如果自动换行输出结果没有任何内容，则返回空列表。

fill(text)

对 text 中的单独段落自动换行并返回包含被自动换行段落的单独字符串。