fixup! Stop incorrectly RFC 2047 encoding non-ASCII email addresses

- Incorporate PR review feedback
- Improve docs

Author: medmunds

Doc/library/email.errors.rst

@@ -59,6 +59,15 @@ The following exception classes are defined in the :mod:`email.errors` module:
    headers.
 
 
+.. exception:: InvalidMailboxError()
+
+   Raised when serializing a message with an address header that contains
+   a mailbox incompatible with the policy in use.
+   (See :attr:`email.policy.EmailPolicy.utf8`.)
+
+   .. versionadded:: 3.14
+
+
 .. exception:: MessageDefect()
 
    This is the base class for all defects found when parsing email messages.

Doc/library/email.policy.rst

@@ -411,12 +411,17 @@ added matters.  To illustrate::
       formatted in this way may be passed to SMTP servers that support
       the ``SMTPUTF8`` extension (:rfc:`6531`).
 
-      .. versionchanged:: 3.13
-         If ``False``, the generator will raise a ``ValueError`` if any email
-         address contains non-ASCII characters. To send to a non-ASCII domain
-         with ``utf8=False``, encode the domain using the third-party
-         :pypi:`idna` module or :mod:`encodings.idna`. No RFC allows a non-ASCII
-         username ("localpart") in an email address with ``utf8=False``.
+      When ``False``, the generator will raise an
+      :exc:`~email.errors.InvalidMailboxError` if any address header includes
+      a mailbox ("addr-spec") with non-ASCII characters. To use a mailbox with
+      an internationalized domain name, first encode the domain using the
+      third-party :pypi:`idna` or :pypi:`uts46` module or with
+      :mod:`encodings.idna`. It is not possible to use a non-ASCII username
+      ("local-part") in a mailbox when ``utf8=False``.
+
+      .. versionchanged:: 3.14
+         Raises :exc:`~email.errors.InvalidMailboxError`. (Earlier versions
+         incorrectly applied :rfc:`2047` to non-ASCII addr-specs.)
 
    .. attribute:: refold_source
 

Lib/email/_header_value_parser.py

@@ -2843,7 +2843,7 @@ def _refold_parse_tree(parse_tree, *, policy):
                 # Non-ASCII addr-spec came from parsed message; leave unchanged.
                 want_encoding = False
             else:
-                raise ValueError(
+                raise errors.InvalidMailboxError(
                     "Non-ASCII address requires policy with utf8=True:"
                     " '{}'".format(part)
                 )

Lib/email/errors.py

@@ -33,6 +33,10 @@ class HeaderWriteError(MessageError):
     """Error while writing headers."""
 
 
+class InvalidMailboxError(MessageError, ValueError):
+    """A mailbox was not compatible with the policy in use."""
+
+
 # These are parsing defects which the parser was able to work around.
 class MessageDefect(ValueError):
     """Base class for a message defect."""

Lib/test/test_email/test_generator.py

@@ -304,11 +304,13 @@ def test_non_ascii_addr_spec_raises(self):
             with self.subTest(address=address):
                 msg = EmailMessage()
                 msg['To'] = address
-                expected_error = re.escape(
-                    "Non-ASCII address requires policy with utf8=True:"
-                    " '{}'".format(msg['To'].addresses[0].addr_spec)
+                addr_spec = msg['To'].addresses[0].addr_spec
+                expected_error = (
+                    fr"(?i)(?=.*non-ascii)(?=.*utf8.*True)(?=.*{re.escape(addr_spec)})"
                 )
-                with self.assertRaisesRegex(ValueError, expected_error):
+                with self.assertRaisesRegex(
+                    email.errors.InvalidMailboxError, expected_error
+                ):
                     g.flatten(msg)
 
 

Misc/NEWS.d/next/Library/2024-07-31-17-22-10.gh-issue-83938.TtUa-c.rst

@@ -1,3 +1,5 @@
-Stop incorrectly using RFC 2047 "encoded words" for email addresses with
-non-ASCII characters when email.generator is called using a policy with
-``utf8=False``.
+The :mod:`email` module no longer incorrectly encodes non-ASCII characters
+in email addresses using :rfc:`2047` encoding. Under a policy with ``utf8=True``
+this means the addresses will be correctly passed through. Under a policy with
+``utf8=False``, attempting to serialize a message with non-ASCII email addresses
+will now result in an :exc:`~email.errors.InvalidMailboxError`.

Misc/NEWS.d/next/Library/2024-07-31-17-23-06.gh-issue-122476.TtUa-c.rst

@@ -1,3 +1,5 @@
-Stop incorrectly using RFC 2047 "encoded words" for email addresses with
-non-ASCII characters when email.generator is called using a policy with
-``utf8=False``.
+The :mod:`email` module no longer incorrectly encodes non-ASCII characters
+in email addresses using :rfc:`2047` encoding. Under a policy with ``utf8=True``
+this means the addresses will be correctly passed through. Under a policy with
+``utf8=False``, attempting to serialize a message with non-ASCII email addresses
+will now result in an :exc:`~email.errors.InvalidMailboxError`.