| |
| wrapper = TextWrapper() |
| wrapper.initial_indent = "* " |
| |
| You can re-use the same :class:`TextWrapper` object many times, and you can |
| change any of its options through direct assignment to instance attributes |
| between uses. |
| |
n | The :class:`TextWrapper` instance attributes (and keyword arguments to the |
n | The :class:`TextWrapper` instance attributes (and keyword arguments to the |
| constructor) are as follows: |
| constructor) are as follows: |
| |
| |
n | .. attribute:: TextWrapper.width |
n | .. attribute:: width |
| |
n | (default: ``70``) The maximum length of wrapped lines. As long as there are no |
n | (default: ``70``) The maximum length of wrapped lines. As long as there |
| individual words in the input text longer than :attr:`width`, |
| are no individual words in the input text longer than :attr:`width`, |
| :class:`TextWrapper` guarantees that no output line will be longer than |
| :class:`TextWrapper` guarantees that no output line will be longer than |
| :attr:`width` characters. |
| :attr:`width` characters. |
| |
| |
n | .. attribute:: TextWrapper.expand_tabs |
n | .. attribute:: expand_tabs |
| |
n | (default: ``True``) If true, then all tab characters in *text* will be expanded |
n | (default: ``True``) If true, then all tab characters in *text* will be |
| to spaces using the :meth:`expandtabs` method of *text*. |
| expanded to spaces using the :meth:`expandtabs` method of *text*. |
| |
| |
n | .. attribute:: TextWrapper.replace_whitespace |
n | .. attribute:: replace_whitespace |
| |
n | (default: ``True``) If true, each whitespace character (as defined by |
n | (default: ``True``) If true, each whitespace character (as defined by |
| ``string.whitespace``) remaining after tab expansion will be replaced by a |
| ``string.whitespace``) remaining after tab expansion will be replaced by a |
| single space. |
| single space. |
| |
n | .. note:: |
n | .. note:: |
| |
n | If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, each tab |
n | If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, |
| character will be replaced by a single space, which is *not* the same as tab |
| each tab character will be replaced by a single space, which is *not* |
| expansion. |
| the same as tab expansion. |
| |
| |
n | .. attribute:: drop_whitespace |
| |
| (default: ``True``) If true, whitespace that, after wrapping, happens to |
| end up at the beginning or end of a line is dropped (leading whitespace in |
| the first line is always preserved, though). |
| |
| .. versionadded:: 2.6 |
| Whitespace was always dropped in earlier versions. |
| |
| |
| .. attribute:: TextWrapper.initial_indent |
| .. attribute:: initial_indent |
| |
n | (default: ``''``) String that will be prepended to the first line of wrapped |
n | (default: ``''``) String that will be prepended to the first line of |
| output. Counts towards the length of the first line. |
| wrapped output. Counts towards the length of the first line. |
| |
| |
n | .. attribute:: TextWrapper.subsequent_indent |
n | .. attribute:: subsequent_indent |
| |
n | (default: ``''``) String that will be prepended to all lines of wrapped output |
n | (default: ``''``) String that will be prepended to all lines of wrapped |
| except the first. Counts towards the length of each line except the first. |
| output except the first. Counts towards the length of each line except |
| the first. |
| |
| |
n | .. attribute:: TextWrapper.fix_sentence_endings |
n | .. attribute:: fix_sentence_endings |
| |
n | (default: ``False``) If true, :class:`TextWrapper` attempts to detect sentence |
n | (default: ``False``) If true, :class:`TextWrapper` attempts to detect |
| endings and ensure that sentences are always separated by exactly two spaces. |
| sentence endings and ensure that sentences are always separated by exactly |
| This is generally desired for text in a monospaced font. However, the sentence |
| two spaces. This is generally desired for text in a monospaced font. |
| detection algorithm is imperfect: it assumes that a sentence ending consists of |
| However, the sentence detection algorithm is imperfect: it assumes that a |
| a lowercase letter followed by one of ``'.'``, ``'!'``, or ``'?'``, possibly |
| sentence ending consists of a lowercase letter followed by one of ``'.'``, |
| followed by one of ``'"'`` or ``'''``, followed by a space. One problem with |
| ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``, |
| this is algorithm is that it is unable to detect the difference between "Dr." in |
| followed by a space. One problem with this is algorithm is that it is |
| :: |
| unable to detect the difference between "Dr." in :: |
| |
n | [...] Dr. Frankenstein's monster [...] |
n | [...] Dr. Frankenstein's monster [...] |
| |
n | and "Spot." in :: |
n | and "Spot." in :: |
| |
n | [...] See Spot. See Spot run [...] |
n | [...] See Spot. See Spot run [...] |
| |
n | :attr:`fix_sentence_endings` is false by default. |
n | :attr:`fix_sentence_endings` is false by default. |
| |
n | Since the sentence detection algorithm relies on ``string.lowercase`` for the |
n | Since the sentence detection algorithm relies on ``string.lowercase`` for |
| definition of "lowercase letter," and a convention of using two spaces after a |
| the definition of "lowercase letter," and a convention of using two spaces |
| period to separate sentences on the same line, it is specific to English- |
| after a period to separate sentences on the same line, it is specific to |
| language texts. |
| English-language texts. |
| |
| |
n | .. attribute:: TextWrapper.break_long_words |
n | .. attribute:: break_long_words |
| |
n | (default: ``True``) If true, then words longer than :attr:`width` will be broken |
n | (default: ``True``) If true, then words longer than :attr:`width` will be |
| in order to ensure that no lines are longer than :attr:`width`. If it is false, |
| broken in order to ensure that no lines are longer than :attr:`width`. If |
| long words will not be broken, and some lines may be longer than :attr:`width`. |
| it is false, long words will not be broken, and some lines may be longer |
| (Long words will be put on a line by themselves, in order to minimize the amount |
| than :attr:`width`. (Long words will be put on a line by themselves, in |
| by which :attr:`width` is exceeded.) |
| order to minimize the amount by which :attr:`width` is exceeded.) |
| |
n | |
| .. attribute:: break_on_hyphens |
| |
| (default: ``True``) If true, wrapping will occur preferably on whitespaces |
| and right after hyphens in compound words, as it is customary in English. |
| If false, only whitespaces will be considered as potentially good places |
| for line breaks, but you need to set :attr:`break_long_words` to false if |
| you want truly insecable words. Default behaviour in previous versions |
| was to always allow breaking hyphenated words. |
| |
| .. versionadded:: 2.6 |
| |
| |
| :class:`TextWrapper` also provides two public methods, analogous to the module- |
| :class:`TextWrapper` also provides two public methods, analogous to the |
| level convenience functions: |
| module-level convenience functions: |
| |
n | .. method:: wrap(text) |
| |
n | .. method:: TextWrapper.wrap(text) |
| |
| Wraps the single paragraph in *text* (a string) so every line is at most |
| Wraps the single paragraph in *text* (a string) so every line is at most |
| :attr:`width` characters long. All wrapping options are taken from instance |
| :attr:`width` characters long. All wrapping options are taken from |
| attributes of the :class:`TextWrapper` instance. Returns a list of output lines, |
| instance attributes of the :class:`TextWrapper` instance. Returns a list |
| without final newlines. |
| of output lines, without final newlines. |
| |
| |
n | .. method:: TextWrapper.fill(text) |
n | .. method:: fill(text) |
| |
t | Wraps the single paragraph in *text*, and returns a single string containing the |
t | Wraps the single paragraph in *text*, and returns a single string |
| wrapped paragraph. |
| containing the wrapped paragraph. |
| |