Skip to content

gh-85014: Fix description of email.utils.encode_rfc2231() - #162117

Open
hnwg wants to merge 1 commit into
python:mainfrom
hnwg:gh-85014-encode-rfc2231-doc
Open

hnwg wants to merge 1 commit into
python:mainfrom
hnwg:gh-85014-encode-rfc2231-doc

Conversation

@hnwg

@hnwg hnwg commented Nov 16, 2026 •

Copy link
Copy Markdown

The docstring and Doc/library/email.utils.rst state that if no charset or language is provided then the string "is returned as-is". But:

>>> from email.utils import encode_rfc2231
>>> encode_rfc2231('foo bar')
'foo%20bar'
>>> encode_rfc2231('foo bar', 'utf-8')
"utf-8''foo%20bar"

As noted by bitdancer in GH-20564, the docstring is incorrect and the code is correct. A blank must be percent-encoded in an RFC 2231 value. The code was updated in that PR, but it was closed. This PR only updates the two descriptions. The string is always percent-encoded. If no charset or language is provided then there will be no charset'language' prefix.

No functional changes, so no test or NEWS entry. In GH-161225 the core of the function is being changed for gh-161222. These lines aren't touched.

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.
@hnwg
hnwg requested a review from a team as a code owner November 16, 2026 15:42
@python-cla-bot

python-cla-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app

bedevere-app Bot commented Nov 16, 2026

Copy link
Copy Markdown

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant