https://github.com/python/cpython/commit/ff7d1cec41f391270560b9f4726791d8476c6eba
commit: ff7d1cec41f391270560b9f4726791d8476c6eba
branch: main
author: Andrii Hrimov <[email protected]>
committer: bitdancer <[email protected]>
date: 2026-01-06T15:18:37-05:00
summary:
gh-133315: Document that compat32 should not be used with MIMEPart/EmailMessage
(#143307)
files:
M Doc/library/email.message.rst
M Doc/library/email.policy.rst
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 71d6e321f387bc..0aa8e632c2ca80 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -57,7 +57,7 @@ message objects.
:class:`~email.policy.default` policy, which follows the rules of the email
RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
the Python standard ``\n`` line endings). For more information see the
- :mod:`~email.policy` documentation.
+ :mod:`~email.policy` documentation. [2]_
.. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None)
@@ -749,3 +749,9 @@ message objects.
.. [1] Originally added in 3.4 as a :term:`provisional module <provisional
package>`. Docs for legacy message class moved to
:ref:`compat32_message`.
+
+.. [2] The :class:`EmailMessage` class requires a policy that provides a
+ ``content_manager`` attribute for content management methods like
+ ``set_content()`` and ``get_content()`` to work. The legacy
+ :const:`~email.policy.compat32` policy does not support these methods
+ and should not be used with :class:`EmailMessage`.
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index 6b997ee784f6e4..1ff3e2c3f8df6b 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -662,6 +662,13 @@ The header objects and their attributes are described in
An instance of :class:`Compat32`, providing backward compatibility with the
behavior of the email package in Python 3.2.
+ .. note::
+
+ The :const:`compat32` policy should not be used as a policy for
+ :class:`~email.message.EmailMessage` objects, and should only be used
+ to serialize messages that were created using the :const:`compat32`
+ policy.
+
.. rubric:: Footnotes
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
