Add email.utils docs, narrow the docstring.

Author: gpshead

Doc/library/email.utils.rst

@@ -87,7 +87,7 @@ of the new API.
    This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
    *fieldvalues* is a sequence of header field values as might be returned by
    :meth:`Message.get_all <email.message.Message.get_all>`.  Here's a simple
-   example that gets all the recipients of a message::
+   example that gets all the recipients of a message:
 
       from email.utils import getaddresses
 
@@ -97,6 +97,25 @@ of the new API.
       resent_ccs = msg.get_all('resent-cc', [])
       all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
 
+   When parsing fails for a single fieldvalue, a 2-tuple of ``('', '')``
+   is returned in its place.  Other errors in parsing the list of
+   addresses such as a fieldvalue seemingly parsing into multiple
+   addresses may result in a list containing a single empty 2-tuple
+   ``[('', '')]`` being returned rather than returning potentially
+   invalid output.
+
+   Example malformed input parsing:
+
+   .. doctest::
+
+      >>> from email.utils import getaddresses
+      >>> getaddresses(['[email protected] <[email protected]>', '[email protected]'])
+      [('', '')]
+
+   .. versionchanged:: 3.12
+      The 2-tuple of ``('', '')`` in the returned values when parsing
+      fails were added as to address a security issue.
+
 
 .. function:: parsedate(date)
 

Lib/email/utils.py

@@ -135,14 +135,10 @@ def getaddresses(fieldvalues):
     When parsing fails for a fieldvalue, a 2-tuple of ('', '') is returned in
     its place.
 
-    If the resulting list of parsed address is greater than number of
-    fieldvalues in the input list a parsing error has occurred, so a list
+    If the resulting list of parsed address is not the same as the number of
+    fieldvalues in the input list a parsing error has occurred.  A list
     containing a single empty 2-tuple [('', '')] is returned in its place.
     This is done to avoid invalid output.
-
-    Malformed input: getaddresses(['[email protected] <[email protected]>'])
-    Invalid output: [('', '[email protected]'), ('', '[email protected]')]
-    Safe output: [('', '')]
     """
     fieldvalues = [str(v) for v in fieldvalues]
     fieldvalues = _pre_parse_validation(fieldvalues)