[3.13] gh-133315: Document that compat32 should not be used with MIMEPart/EmailMessag...

gh-133315: Document that compat32 should not be used with MIMEPart/EmailMessage (GH-143307)
(cherry picked from commit ff7d1cec41f391270560b9f4726791d8476c6eba)

Co-authored-by: Andrii Hrimov <andrew.hrimov@gmail.com>

diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 71d6e321f387bcb6847b5bc9cee35a249ad45679..0aa8e632c2ca808cd61fbb828818857c659be718 100644 (file)
--- 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 6b997ee784f6e444c2df7dc3e408b454165c08dc..1ff3e2c3f8df6b4129fbb299fed41a250c84a7a5 100644 (file)
--- 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