4.8 textwrap -- Text wrapping and filling

# 4.8 `textwrap` -- Text wrapping and filling

New in version 2.3.

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.

`wrap`( | text[, width[, ...]])

  Wraps the single paragraph in text (a string) so every line is at most width characters long. Returns a list of output lines, without final newlines.

  Optional keyword arguments correspond to the instance attributes of `TextWrapper`, documented below. width defaults to `70`.

`fill`( | text[, width[, ...]])

  Wraps the single paragraph in text, and returns a single string containing the wrapped paragraph. `fill()` is shorthand for

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

  In particular, `fill()` accepts exactly the same keyword arguments as `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.

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

`dedent`( | text)

  Remove any whitespace that can be uniformly removed from the left of every line in text.

  This is typically used to make triple-quoted strings line up with the left edge of screen/whatever, while still presenting it in the source code in indented form.

  For example:

      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 `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="* ")

  is the same as

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

  You can re-use the same `TextWrapper` object many times, and you can change any of its options through direct assignment to instance attributes between uses.

The `TextWrapper` instance attributes (and keyword arguments to the constructor) are as follows:

`width`
  (default: `70`) The maximum length of wrapped lines. As long as there are no individual words in the input text longer than `width`, `TextWrapper` guarantees that no output line will be longer than `width` characters.

`expand_tabs`
  (default: `True`) If true, then all tab characters in text will be expanded to spaces using the `expand_tabs()` method of text.

`replace_whitespace`
  (default: `True`) If true, each whitespace character (as defined by `string.whitespace`) remaining after tab expansion will be replaced by a single space. Note: If `expand_tabs` is false and `replace_whitespace` is true, each tab character will be replaced by a single space, which is not the same as tab expansion.

`initial_indent`
  (default: `''`) String that will be prepended to the first line of wrapped output. Counts towards the length of the first line.

`subsequent_indent`
  (default: `''`) String that will be prepended to all lines of wrapped output except the first. Counts towards the length of each line except the first.

`fix_sentence_endings`
  (default: `False`) If true, `TextWrapper` attempts to detect sentence endings and ensure that sentences are always separated by exactly two spaces. This is generally desired for text in a monospaced font. However, the sentence detection algorithm is imperfect: it assumes that a sentence ending consists of a lowercase letter followed by one of "`.`", "`!`", or "`?`", possibly followed by one of "`"`" or "`'`", followed by a space. One problem with this is algorithm is that it is unable to detect the difference between ``Dr.'' in

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

  and ``Spot.'' in

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

  `fix_sentence_endings` is false by default.

  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`
  (default: `True`) If true, then words longer than `width` will be broken in order to ensure that no lines are longer than `width`. If it is false, long words will not be broken, and some lines may be longer than `width`. (Long words will be put on a line by themselves, in order to minimize the amount by which `width` is exceeded.)

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

`wrap`( | text)

  Wraps the single paragraph in text (a string) so every line is at most `width` characters long. All wrapping options are taken from instance attributes of the `TextWrapper` instance. Returns a list of output lines, without final newlines.

`fill`( | text)

  Wraps the single paragraph in text, and returns a single string containing the wrapped paragraph.