From 871119eb2f189f9f94f4c95ed5372e76038a7d54 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Thu, 27 Feb 2014 18:01:43 -0500 Subject: [PATCH] whatsnew: fix textwrap/shorten entry, and improve the related docs. I had incorrectly added back the shorten method when I initially made the whatsnew entry, but the shorten function docs were not correct according to the code. I also improved the wording in general. --- Doc/library/textwrap.rst | 39 ++++++++++++++++++--------------------- Doc/whatsnew/3.4.rst | 18 +++++++++--------- 2 files changed, 27 insertions(+), 30 deletions(-) diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index 01887292bdc..edf1fd6ece4 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -40,13 +40,14 @@ functions should be good enough; otherwise, you should use an instance of :func:`wrap`. -.. function:: shorten(text, width=70, *, placeholder=" [...]") +.. function:: shorten(text, width, **kwargs) - Collapse and truncate the given text to fit in the given width. + Collapse and truncate the given *text* to fit in the given *width*. - The text first has its whitespace collapsed. If it then fits in - the *width*, it is returned unchanged. Otherwise, as many words - as possible are joined and then the *placeholder* is appended:: + First the whitespace in *text* is collapsed (all whitespace is replaced by + single spaces). If the result fits in the *width*, it is returned. + Otherwise, enough words are dropped from the end so that the remaining words + plus the :attr:`placeholder` fit within :attr:`width`:: >>> textwrap.shorten("Hello world!", width=12) 'Hello world!' @@ -55,6 +56,12 @@ functions should be good enough; otherwise, you should use an instance of >>> textwrap.shorten("Hello world", width=10, placeholder="...") 'Hello...' + Optional keyword arguments correspond to the instance attributes of + :class:`TextWrapper`, documented below. Note that the whitespace is + collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill` + function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`, + :attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect. + .. versionadded:: 3.4 @@ -110,8 +117,8 @@ functions should be good enough; otherwise, you should use an instance of :func:`wrap`, :func:`fill` and :func:`shorten` work by creating a :class:`TextWrapper` instance and calling a single method on it. That instance is not reused, so for applications that process many text -strings, it may be more efficient to create your own -:class:`TextWrapper` object. +strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to +create your own :class:`TextWrapper` object. Text is preferably wrapped on whitespaces and right after the hyphens in hyphenated words; only then will long words be broken if necessary, unless @@ -252,16 +259,16 @@ hyphenated words; only then will long words be broken if necessary, unless .. attribute:: max_lines - (default: ``None``) If not ``None``, then the text be will truncated to - *max_lines* lines. + (default: ``None``) If not ``None``, then the output will contain at most + *max_lines* lines, with *placeholder* appearing at the end of the output. .. versionadded:: 3.4 .. attribute:: placeholder - (default: ``' [...]'``) String that will be appended to the last line of - text if it will be truncated. + (default: ``' [...]'``) String that will appear at the end of the output + text if it has been truncated. .. versionadded:: 3.4 @@ -282,13 +289,3 @@ hyphenated words; only then will long words be broken if necessary, unless Wraps the single paragraph in *text*, and returns a single string containing the wrapped paragraph. - - - .. method:: shorten(text, width=70, *, placeholder=" [...]") - - Collapse and truncate the given text to fit in the given width. - The text first has its whitespace collapsed. If it then fits in - the *width*, it is returned unchanged. Otherwise, as many words - as possible are joined and then the *placeholder* is appended. - - .. versionadded:: 3.4 diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst index 997afc49d31..16799ff70c8 100644 --- a/Doc/whatsnew/3.4.rst +++ b/Doc/whatsnew/3.4.rst @@ -1250,15 +1250,15 @@ in :issue:`13390`.) textwrap -------- -:mod:`textwrap` has a new function :func:`~textwrap.shorten`, implemented via a -new :class:`~textwrap.TextWrapper` method -:meth:`~textwrap.TextWrapper.shorten`, that provides a convenient way to create -a string that displays just the leading porting of an input string. It -collapses any whitespace, truncates the result to a specified width, and a -specified placeholder is added (by default, ``[...]``, stored in the new -:attr:`~textwrap.TextWrapper.placeholder` attribute of the -:class:`~textwrap.TextWrapper` object)). (Contributed by Antoine Pitrou in -:issue:`18585`.) +The :class:`~textwrap.TextWrapper` class has two new attributes/constructor +arguments: :attr:`~textwrap.TextWrapper.max_lines`, which limits the number of +lines in the output, and :attr:`~textwrap.TextWrapper.placeholder`, which is a +string that will appear at the end of the output if it has been truncated +because of *max_lines*. Building on these capabilities, a new convenience +function :func:`~textwrap.shorten` collapses all of the whitespace in the input +to single spaces and produces a single line of a given *width* that ends with +the *placeholder* (by default, ``[...]``). (Contributed by Antoine Pitrou and +Serhiy Storchaka in :issue:`18585` and :issue:`18725`.) threading