From aba0e541caaa086f183197eaaca0ac20a730bbe4 Mon Sep 17 00:00:00 2001
From: Jake Howard <git@theorangeone.net>
Date: Sun, 9 Jun 2024 09:09:07 +0100
Subject: Fixed #35537 -- Changed EmailMessage.attachments and
 EmailMultiAlternatives.alternatives to use namedtuples.

This makes it more descriptive to pull out the named fields.
---
 docs/releases/5.2.txt | 10 +++++++++-
 docs/topics/email.txt | 35 +++++++++++++++++++++++++++++------
 2 files changed, 38 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/releases/5.2.txt b/docs/releases/5.2.txt
index e0f190076a..61101ce1fd 100644
--- a/docs/releases/5.2.txt
+++ b/docs/releases/5.2.txt
@@ -133,7 +133,15 @@ Decorators
 Email
 ~~~~~
 
-* ...
+* Tuple items of :class:`EmailMessage.attachments
+  <django.core.mail.EmailMessage>` and
+  :class:`EmailMultiAlternatives.attachments
+  <django.core.mail.EmailMultiAlternatives>` are now named tuples, as opposed
+  to regular tuples.
+
+* :attr:`EmailMultiAlternatives.alternatives
+  <django.core.mail.EmailMultiAlternatives.alternatives>` is now a list of
+  named tuples, as opposed to regular tuples.
 
 Error Reporting
 ~~~~~~~~~~~~~~~
diff --git a/docs/topics/email.txt b/docs/topics/email.txt
index 9b7b404ec1..1a283bdbb4 100644
--- a/docs/topics/email.txt
+++ b/docs/topics/email.txt
@@ -282,8 +282,13 @@ All parameters are optional and can be set at any time prior to calling the
   new connection is created when ``send()`` is called.
 
 * ``attachments``: A list of attachments to put on the message. These can
-  be either :class:`~email.mime.base.MIMEBase` instances, or ``(filename,
-  content, mimetype)`` triples.
+  be either :class:`~email.mime.base.MIMEBase` instances, or a named tuple
+  with attributes ``(filename, content, mimetype)``.
+
+  .. versionchanged:: 5.2
+
+    In older versions, tuple items of ``attachments`` were regular tuples,
+    as opposed to named tuples.
 
 * ``headers``: A dictionary of extra headers to put on the message. The
   keys are the header name, values are the header values. It's up to the
@@ -392,10 +397,10 @@ Django's email library, you can do this using the
 
 .. class:: EmailMultiAlternatives
 
-    A subclass of :class:`~django.core.mail.EmailMessage` that has an
-    additional ``attach_alternative()`` method for including extra versions of
-    the message body in the email. All the other methods (including the class
-    initialization) are inherited directly from
+    A subclass of :class:`~django.core.mail.EmailMessage` that allows
+    additional versions of the message body in the email via the
+    ``attach_alternative()`` method. This directly inherits all methods
+    (including the class initialization) from
     :class:`~django.core.mail.EmailMessage`.
 
     .. method:: attach_alternative(content, mimetype)
@@ -415,6 +420,24 @@ Django's email library, you can do this using the
             msg.attach_alternative(html_content, "text/html")
             msg.send()
 
+    .. attribute:: alternatives
+
+        A list of named tuples with attributes ``(content, mimetype)``. This is
+        particularly useful in tests::
+
+            self.assertEqual(len(msg.alternatives), 1)
+            self.assertEqual(msg.alternatives[0].content, html_content)
+            self.assertEqual(msg.alternatives[0].mimetype, "text/html")
+
+        Alternatives should only be added using the
+        :meth:`~django.core.mail.EmailMultiAlternatives.attach_alternative`
+        method.
+
+        .. versionchanged:: 5.2
+
+            In older versions, ``alternatives`` was a list of regular tuples, as opposed
+            to named tuples.
+
 Updating the default content type
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
cgit v1.3