whatsnew: textwrap.shorten.

Also add the missing TextWrapper.shorten method doc.

2 files changed, 24 insertions, 0 deletions

diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index 1ba42a3..0188729 100644
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -282,3 +282,13 @@ 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 461a8b8..edc5704 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -1210,6 +1210,20 @@ especially if automated via a test suite.  (Contributed by Antoine Pitrou
 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`.)
+
+
 traceback
 ---------