# 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)

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