Everything You Can Do with Python's textwrap Module

Python has many options for formatting strings and text, including f-strings, format() function, templates and more. There's however one module that few people know about and it's called textwrap.

This module is specifically built to help you with line-wrapping, indentation, trimming and more, and in this article we will look at all the things you can use it for.

Shorten

Let's start with very simple, yet very useful function from the textwrap module, called shorten:


from textwrap import shorten

shorten("This is a long text or sentence.", width=10)
# 'This [...]'
shorten("This is a long text or sentence.", width=15)
# 'This is a [...]'
shorten("This is a long text or sentence.", width=15, placeholder=" <...>")
# 'This is a <...>'

As the name suggests, shorten allows us to trim text to certain length (width) if the specified string is too long. By default, the placeholder for the trimmed text is [...], but that can be overridden with the placeholder argument.

Wrap

A more interesting function from this module is wrap. The obvious use-case for it is to split long text into lines of same length, but there are more things we can do with it:


from textwrap import wrap
s = '1234567890'
wrap(s, 3)
# ['123', '456', '789', '0']

In this example we split a string into equal chunks which can be useful for batch processing, rather than just formatting.

Using this function however, has some caveats:


s = '12\n3  45678\t9\n0'
wrap(s, 3)
# ['12', '3  ', '456', '78', '9 0']
# the first ("12") element "includes" newline
# the 4th element ("78") "includes" tab
wrap(s, 3, drop_whitespace=False, tabsize=1)
# ['12 ', '3  ', '456', '78 ', '9 0']

You should be careful with whitespaces, when using wrap - above you can see the behaviour with newline, tab and space characters. You can see that the first element (12) "includes" newline, and 4th element (78) "includes" tab, those are however, dropped by default, therefore these elements only have 2 characters instead of 3.

We can specify the drop_whitespace keyword argument to preserve them and maintain the proper length of chunks.

It might be obvious, but wrap is also great for reformatting whole files to certain line width:


with open("some-text.md", "r", encoding="utf-8") as f:
    formatted = wrap(f.read(), width=80)  # List of lines
    formatted = fill(f.read(), width=80)  # Single string that includes line breaks
    # ... write it back

We can also use the fill function which is a shorthand for "\n".join(wrap(text, ...)). The difference between the 2 is that wrap will give us a list of lines that we would need to concatenate ourselves, and fill gives us a single string that's already joined using newlines.

TextWrapper

textwrap module also includes a more powerful version wrap function, which is a TextWrapper class:


import textwrap

w = textwrap.TextWrapper(width=120, placeholder=" <...>")
for s in list_of_strings:
    w.wrap(s)
    # ...

This class and its wrap method are great if we need to call wrap with the same parameters multiple times as shown above.

And while we're looking that the TextWrapper, let's also try out some more keyword arguments:


user = "John"
prefix = user + ": "
width = 50
wrapper = TextWrapper(initial_indent=prefix, width=width, subsequent_indent=" " * len(prefix))
messages = ["...", "...", "..."]
for m in messages:
    print(wrapper.fill(m))

# John: Lorem Ipsum is simply dummy text of the
#       printing and typesetting industry. Lorem
# John: Ipsum has been the industry's standard dummy
#       text ever since the 1500s, when an
# John: unknown printer took a galley of type and
#       scrambled it to make a type specimen

Here we can see the use of initial_indent and subsequent_indent for indenting the first line of paragraph and subsequent ones, respectively. There are couple more options, which you can find in docs.

Furthermore, because TextWrapper is a class, we can also extend it and completely override some of its methods:


from textwrap import TextWrapper

class DocumentWrapper(TextWrapper):

    def wrap(self, text):
        split_text = text.split('\n')
        lines = [line for par in split_text for line in TextWrapper.wrap(self, par)]
        return lines


text = """First line,

Another, much looooooonger line of text and/or sentence"""
d = DocumentWrapper(width=50)
print(d.fill(text))

# First line,
# Another, much looooooonger line of text and/or
# sentence

This is a nice example of changing the wrap method to preserve existing line breaks and to print them properly.

For a more complete example for handling multiple paragraphs with TextWrapper, check out this article.

Indentation

Finally, textwrap also includes two functions for indentation, first one being dedent:


# Ugly formatting:
multiline_string = """
First line
Second line
Third line
"""

from textwrap import dedent

multiline_string = """
                   First line
                   Second line
                   Third line
                   """

print(dedent(multiline_string))

# First line
# Second line
# Third line

# Notice the leading blank line...
# You can use:
multiline_string = """\
                   First line
                   Second line
                   Third line
                   """

# or
from inspect import cleandoc
cleandoc(multiline_string)
# 'First line\nSecond line\nThird line'

By default, multiline strings in Python honor any indentation used in the string, therefore we need to use the ugly formatting shown in the first variable in the snippet above. But we can use the dedent function to improve formatting - we simply indent the variable value however we like and then call dedent on it before using it.

Alternatively, we could also use inspect.cleandoc, which also strips the leading newline. This function however encodes the whitespaces as special characters (\n and \t), so you might need to reformat it again.

Naturally, when there is dedent, then there needs to be also indent function:


from textwrap import indent

indented = indent(text, "    ", lambda x: not text.splitlines()[0] in x)

We simply supply the text and the string that each line will be indented with (here just 4 spaces, we could - for example - use >>> to make it look like REPL). Additionally, we can supply a predicate that will decide whether the line should be indented or not. In the example above, the lambda function makes it so that first line of string (paragraph) is not indented.

Closing Thoughts

textwrap is a simple module with just a few functions/methods, but it once again shows that Python really comes with "batteries included" for things that don't necessarily need to be standard library, but they can save you so much time when you happen to need them.

If you happen to do a lot of text processing, then I also recommend checking out the whole docs section dedicated to working with text. There are many more modules and little functions that you didn't know you needed. 😉

推荐订阅源