From 073ed7d529252989763abe87e0808402b2f399ff Mon Sep 17 00:00:00 2001 From: hwdev Date: Wed, 11 Nov 2026 21:17:38 +0000 Subject: [PATCH] gh-85014: Fix the description of email.utils.encode_rfc2231() The docstring and the documentation said that the string "is returned as-is" when neither charset nor language is given. The function always percent-encodes the string, as RFC 2231 requires for characters such as the space. Without charset and language it only leaves out the charset'language' prefix. The behavior is correct and is not changed. --- Doc/library/email.utils.rst | 8 +++++--- Lib/email/utils.py | 7 ++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/Doc/library/email.utils.rst b/Doc/library/email.utils.rst index dc8b4d4976d5937..a04c1171bfdc8c9 100644 --- a/Doc/library/email.utils.rst +++ b/Doc/library/email.utils.rst @@ -203,9 +203,11 @@ of the new API. .. function:: encode_rfc2231(s, charset=None, language=None) Encode the string *s* according to :rfc:`2231`. Optional *charset* and - *language*, if given, are the character set name and language name to use. If - neither is given, *s* is returned as-is. If *charset* is given but *language* - is not, the string is encoded using the empty string for *language*. + *language*, if given, are the character set name and language name to use. + The string is always percent-encoded. If neither is given, the encoded + string is returned without the character set and language prefix. If + *charset* is given but *language* is not, the string is encoded using the + empty string for *language*. .. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii') diff --git a/Lib/email/utils.py b/Lib/email/utils.py index c8a6d0af37532c9..f8de86afc40c159 100644 --- a/Lib/email/utils.py +++ b/Lib/email/utils.py @@ -387,9 +387,10 @@ def decode_rfc2231(s): def encode_rfc2231(s, charset=None, language=None): """Encode string according to RFC 2231. - If neither charset nor language is given, then s is returned as-is. If - charset is given but not language, the string is encoded using the empty - string for language. + The string is always percent-encoded. If neither charset nor language is + given, then the encoded string is returned without the charset and + language prefix. If charset is given but not language, the string is + encoded using the empty string for language. """ s = urllib.parse.quote(s, safe='', encoding=charset or 'ascii') if charset is None and language is None: