mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-09-10 11:09:12 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #36524 -- Enabled docs cross references to EmailMessage methods.

Browse Source 
Updated docs for class django.core.mail.EmailMessage to use Sphinx
`method::` directives, allowing cross references to those methods
elsewhere in the docs.

Updated references to those methods in the email docs and 6.0 release
notes to link directly to the specific methods.
This commit is contained in:
Mike Edmunds 2025-09-03 13:49:09 -07:00 committed by Jacob Walls
parent 7319341a88
commit 0231f71d31
2 changed files with 183 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/releases/6.0.txt
View File

@ -86,8 +86,8 @@ Python's older legacy (``Compat32``) API, which relied on lower-level MIME
classes (from :mod:`email.mime`) and required more manual handling of classes (from :mod:`email.mime`) and required more manual handling of
message structure and encoding. message structure and encoding.
Notably, the return type of the :class:`EmailMessage.message() Notably, the return type of the :meth:`EmailMessage.message()
<django.core.mail.EmailMessage>` method is now an instance of Python's <django.core.mail.EmailMessage.message>` method is now an instance of Python's
:class:`email.message.EmailMessage`. This supports the same API as the :class:`email.message.EmailMessage`. This supports the same API as the
previous ``SafeMIMEText`` and ``SafeMIMEMultipart`` return types, but is not an previous ``SafeMIMEText`` and ``SafeMIMEMultipart`` return types, but is not an
instance of those now-deprecated classes. instance of those now-deprecated classes.
@ -228,13 +228,14 @@ Decorators
Email Email
~~~~~ ~~~~~
* The new ``policy`` argument for :class:`EmailMessage.message() * The new ``policy`` argument for :meth:`EmailMessage.message()
<django.core.mail.EmailMessage>` allows specifying the email policy, the set <django.core.mail.EmailMessage.message>` allows specifying the email policy,
of rules for updating and serializing the representation of the message. the set of rules for updating and serializing the representation of the
Defaults to :data:`email.policy.default`. message. Defaults to :data:`email.policy.default`.
* :class:`EmailMessage.attach() <django.core.mail.EmailMessage>` now accepts a * :meth:`EmailMessage.attach() <django.core.mail.EmailMessage.attach>` now
:class:`~email.message.MIMEPart` object from Python's modern email API. accepts a :class:`~email.message.MIMEPart` object from Python's modern email
API.
Error Reporting Error Reporting
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -597,7 +598,8 @@ Miscellaneous
* Using a percent sign in a column alias or annotation is deprecated. * Using a percent sign in a column alias or annotation is deprecated.
* Support for passing Python's legacy email :class:`~email.mime.base.MIMEBase` * Support for passing Python's legacy email :class:`~email.mime.base.MIMEBase`
object to :class:`EmailMessage.attach() <django.core.mail.EmailMessage>` (or object to
:meth:`EmailMessage.attach() <django.core.mail.EmailMessage.attach>` (or
including one in the message's ``attachments`` list) is deprecated. For including one in the message's ``attachments`` list) is deprecated. For
complex attachments requiring additional headers or parameters, switch to the complex attachments requiring additional headers or parameters, switch to the
modern email API's :class:`~email.message.MIMEPart`. modern email API's :class:`~email.message.MIMEPart`.

328
docs/topics/email.txt
View File

@ -313,7 +313,7 @@ recipients, file attachments, or multi-part email, you'll need to create
message itself. The :ref:`email backend <topic-email-backends>` is then message itself. The :ref:`email backend <topic-email-backends>` is then
responsible for sending the email. responsible for sending the email.
For convenience, :class:`~django.core.mail.EmailMessage` provides a ``send()`` For convenience, :class:`EmailMessage` provides a :meth:`~EmailMessage.send`
method for sending a single email. If you need to send multiple messages, the method for sending a single email. If you need to send multiple messages, the
email backend API :ref:`provides an alternative email backend API :ref:`provides an alternative
<topics-sending-multiple-emails>`. <topics-sending-multiple-emails>`.
@ -323,185 +323,201 @@ email backend API :ref:`provides an alternative
.. class:: EmailMessage .. class:: EmailMessage
The :class:`~django.core.mail.EmailMessage` class is initialized with the The :class:`!EmailMessage` class is initialized with the following
following parameters. All parameters are optional and can be set at any time parameters. All parameters are optional and can be set at any time prior
prior to calling the ``send()`` method. to calling the :meth:`send` method.
The first four parameters can be passed as positional or keyword arguments, The first four parameters can be passed as positional or keyword arguments,
but must be in the given order if positional arguments are used: but must be in the given order if positional arguments are used:
* ``subject``: The subject line of the email. * ``subject``: The subject line of the email.
* ``body``: The body text. This should be a plain text message. * ``body``: The body text. This should be a plain text message.
* ``from_email``: The sender's address. Both ``fred@example.com`` and * ``from_email``: The sender's address. Both ``fred@example.com`` and
``"Fred" <fred@example.com>`` forms are legal. If omitted, the ``"Fred" <fred@example.com>`` forms are legal. If omitted, the
:setting:`DEFAULT_FROM_EMAIL` setting is used. :setting:`DEFAULT_FROM_EMAIL` setting is used.
* ``to``: A list or tuple of recipient addresses. * ``to``: A list or tuple of recipient addresses.
The following parameters must be given as keyword arguments if used: The following parameters must be given as keyword arguments if used:
* ``cc``: A list or tuple of recipient addresses used in the "Cc" header * ``cc``: A list or tuple of recipient addresses used in the "Cc" header
when sending the email. when sending the email.
* ``bcc``: A list or tuple of addresses used in the "Bcc" header when * ``bcc``: A list or tuple of addresses used in the "Bcc" header when
sending the email. sending the email.
* ``reply_to``: A list or tuple of recipient addresses used in the "Reply-To" * ``reply_to``: A list or tuple of recipient addresses used in the
header when sending the email. "Reply-To" header when sending the email.
* ``attachments``: A list of attachments to put on the message. Each can * ``attachments``: A list of attachments to put on the message. Each can
be an instance of :class:`~email.message.MIMEPart` or be an instance of :class:`~email.message.MIMEPart` or
:class:`~django.core.mail.EmailAttachment`, or a tuple with attributes :class:`EmailAttachment`, or a tuple with attributes
``(filename, content, mimetype)``. ``(filename, content, mimetype)``.
.. versionchanged:: 5.2 .. versionchanged:: 5.2
Support for :class:`~django.core.mail.EmailAttachment` items of Support for :class:`EmailAttachment` items of ``attachments`` was
``attachments`` was added. added.
.. versionchanged:: 6.0 .. versionchanged:: 6.0
Support for :class:`~email.message.MIMEPart` objects in the ``attachments`` Support for :class:`~email.message.MIMEPart` objects in the
list was added. ``attachments`` list was added.
.. deprecated:: 6.0 .. deprecated:: 6.0
Support for Python's legacy :class:`~email.mime.base.MIMEBase` objects in Support for Python's legacy :class:`~email.mime.base.MIMEBase`
``attachments`` is deprecated. Use :class:`~email.message.MIMEPart` objects in ``attachments`` is deprecated. Use
instead. :class:`~email.message.MIMEPart` instead.
* ``headers``: A dictionary of extra headers to put on the message. The * ``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 keys are the header name, values are the header values. It's up to the
caller to ensure header names and values are in the correct format for caller to ensure header names and values are in the correct format for
an email message. The corresponding attribute is ``extra_headers``. an email message. The corresponding attribute is ``extra_headers``.
* ``connection``: An :ref:`email backend <topic-email-backends>` instance. Use * ``connection``: An :ref:`email backend <topic-email-backends>` instance.
this parameter if you are sending the ``EmailMessage`` via ``send()`` and you Use this parameter if you are sending the :class:`!EmailMessage` via
want to use the same connection for multiple messages. If omitted, a new :meth:`send` and you want to use the same connection for multiple
connection is created when ``send()`` is called. This parameter is ignored messages. If omitted, a new connection is created when :meth:`send` is
when using :ref:`send_messages() <topics-sending-multiple-emails>`. called. This parameter is ignored when using
:ref:`send_messages() <topics-sending-multiple-emails>`.
.. deprecated:: 6.0
Passing all except the first four parameters as positional arguments is
deprecated.
For example::
from django.core.mail import EmailMessage
email = EmailMessage(
subject="Hello",
body="Body goes here",
from_email="from@example.com",
to=["to1@example.com", "to2@example.com"],
bcc=["bcc@example.com"],
reply_to=["another@example.com"],
headers={"Message-ID": "foo"},
)
The class has the following methods:
* ``send(fail_silently=False)`` sends the message. If a connection was
specified when the email was constructed, that connection will be used.
Otherwise, an instance of the default backend will be instantiated and
used. If the keyword argument ``fail_silently`` is ``True``, exceptions
raised while sending the message will be quashed. An empty list of
recipients will not raise an exception. It will return ``1`` if the message
was sent successfully, otherwise ``0``.
* ``message(policy=email.policy.default)`` constructs and returns a Python
:class:`email.message.EmailMessage` object representing the message to be
sent.
The keyword argument ``policy`` allows specifying the set of rules for
updating and serializing the representation of the message. It must be an
:mod:`email.policy.Policy <email.policy>` object. Defaults to
:data:`email.policy.default`. In certain cases you may want to use
:data:`~email.policy.SMTP`, :data:`~email.policy.SMTPUTF8` or a custom
policy. For example, :class:`django.core.mail.backends.smtp.EmailBackend`
uses the :data:`~email.policy.SMTP` policy to ensure ``\r\n`` line endings
as required by the SMTP protocol.
If you ever need to extend Django's :class:`~django.core.mail.EmailMessage`
class, you'll probably want to override this method to put the content you
want into the Python EmailMessage object.
.. versionchanged:: 6.0
The ``policy`` keyword argument was added and the return type was updated
to an instance of :class:`~email.message.EmailMessage`.
* ``recipients()`` returns a list of all the recipients of the message,
whether they're recorded in the ``to``, ``cc`` or ``bcc`` attributes. This
is another method you might need to override when subclassing, because the
SMTP server needs to be told the full list of recipients when the message
is sent. If you add another way to specify recipients in your class, they
need to be returned from this method as well.
* ``attach()`` creates a new attachment and adds it to the message.
There are two ways to call ``attach()``:
* You can pass it three arguments: ``filename``, ``content`` and
``mimetype``. ``filename`` is the name of the file attachment as it will
appear in the email, ``content`` is the data that will be contained inside
the attachment and ``mimetype`` is the optional MIME type for the
attachment. If you omit ``mimetype``, the MIME content type will be guessed
from the filename of the attachment.
For example::
message.attach("design.png", img_data, "image/png")
If you specify a ``mimetype`` of :mimetype:`message/rfc822`, ``content``
can be a :class:`django.core.mail.EmailMessage` or Python's
:class:`email.message.EmailMessage` or :class:`email.message.Message`.
For a ``mimetype`` starting with :mimetype:`text/`, content is expected to
be a string. Binary data will be decoded using UTF-8, and if that fails,
the MIME type will be changed to :mimetype:`application/octet-stream` and
the data will be attached unchanged.
* Or for attachments requiring additional headers or parameters, you can pass
``attach()`` a single Python :class:`~email.message.MIMEPart` object.
This will be attached directly to the resulting message. For example,
to attach an inline image with a :mailheader:`Content-ID`::
cid = email.utils.make_msgid()
inline_image = email.message.MIMEPart()
inline_image.set_content(
image_data_bytes,
maintype="image",
subtype="png",
disposition="inline",
cid=f"<{cid}>",
)
message.attach(inline_image)
message.attach_alternative(f'… <img src="cid:${cid}"> …', "text/html")
Python's :meth:`email.contentmanager.set_content` documentation describes
the supported arguments for ``MIMEPart.set_content()``.
.. versionchanged:: 6.0
Support for :class:`~email.message.MIMEPart` attachments was added.
.. deprecated:: 6.0 .. deprecated:: 6.0
Support for :class:`email.mime.base.MIMEBase` attachments is Passing all except the first four parameters as positional arguments is
deprecated. Use :class:`~email.message.MIMEPart` instead. deprecated.
* ``attach_file()`` creates a new attachment using a file from your For example::
filesystem. Call it with the path of the file to attach and, optionally,
the MIME type to use for the attachment. If the MIME type is omitted, it
will be guessed from the filename. You can use it like this::
message.attach_file("/images/weather_map.png") from django.core.mail import EmailMessage
For MIME types starting with :mimetype:`text/`, binary data is handled as in email = EmailMessage(
``attach()``. subject="Hello",
body="Body goes here",
from_email="from@example.com",
to=["to1@example.com", "to2@example.com"],
bcc=["bcc@example.com"],
reply_to=["another@example.com"],
headers={"Message-ID": "foo"},
)
The class has the following methods:
.. method:: send(fail_silently=False)
Sends the message. If a connection was specified when the email was
constructed, that connection will be used. Otherwise, an instance of
the default backend will be instantiated and used. If the keyword
argument ``fail_silently`` is ``True``, exceptions raised while sending
the message will be quashed. An empty list of recipients will not raise
an exception. It will return ``1`` if the message was sent
successfully, otherwise ``0``.
.. method:: message(policy=email.policy.default)
Constructs and returns a Python :class:`email.message.EmailMessage`
object representing the message to be sent.
The keyword argument ``policy`` allows specifying the set of rules for
updating and serializing the representation of the message. It must be
an :mod:`email.policy.Policy <email.policy>` object. Defaults to
:data:`email.policy.default`. In certain cases you may want to use
:data:`~email.policy.SMTP`, :data:`~email.policy.SMTPUTF8` or a custom
policy. For example,
:class:`django.core.mail.backends.smtp.EmailBackend` uses the
:data:`~email.policy.SMTP` policy to ensure ``\r\n`` line endings as
required by the SMTP protocol.
If you ever need to extend Django's :class:`EmailMessage` class,
you'll probably want to override this method to put the content you
want into the Python EmailMessage object.
.. versionchanged:: 6.0
The ``policy`` keyword argument was added and the return type was
updated to an instance of :class:`~email.message.EmailMessage`.
.. method:: recipients()
Returns a list of all the recipients of the message, whether they're
recorded in the ``to``, ``cc`` or ``bcc`` attributes. This is another
method you might need to override when subclassing, because the SMTP
server needs to be told the full list of recipients when the message
is sent. If you add another way to specify recipients in your class,
they need to be returned from this method as well.
.. method:: attach(filename, content, mimetype)
attach(mimepart)
Creates a new attachment and adds it to the message. There are two ways
to call :meth:`!attach`:
* You can pass it three arguments: ``filename``, ``content`` and
``mimetype``. ``filename`` is the name of the file attachment as it
will appear in the email, ``content`` is the data that will be
contained inside the attachment and ``mimetype`` is the optional MIME
type for the attachment. If you omit ``mimetype``, the MIME content
type will be guessed from the filename of the attachment.
For example::
message.attach("design.png", img_data, "image/png")
If you specify a ``mimetype`` of :mimetype:`message/rfc822`,
``content`` can be a :class:`django.core.mail.EmailMessage` or
Python's :class:`email.message.EmailMessage` or
:class:`email.message.Message`.
For a ``mimetype`` starting with :mimetype:`text/`, content is
expected to be a string. Binary data will be decoded using UTF-8,
and if that fails, the MIME type will be changed to
:mimetype:`application/octet-stream` and the data will be attached
unchanged.
* Or for attachments requiring additional headers or parameters, you
can pass :meth:`!attach` a single Python
:class:`~email.message.MIMEPart` object. This will be attached
directly to the resulting message. For example, to attach an inline
image with a :mailheader:`Content-ID`::
cid = email.utils.make_msgid()
inline_image = email.message.MIMEPart()
inline_image.set_content(
image_data_bytes,
maintype="image",
subtype="png",
disposition="inline",
cid=f"<{cid}>",
)
message.attach(inline_image)
message.attach_alternative(f'… <img src="cid:${cid}"> …', "text/html")
Python's :meth:`email.contentmanager.set_content` documentation
describes the supported arguments for ``MIMEPart.set_content()``.
.. versionchanged:: 6.0
Support for :class:`~email.message.MIMEPart` attachments was
added.
.. deprecated:: 6.0
Support for :class:`email.mime.base.MIMEBase` attachments is
deprecated. Use :class:`~email.message.MIMEPart` instead.
.. method:: attach_file(path, mimetype=None)
Creates a new attachment using a file from your filesystem. Call it
with the path of the file to attach and, optionally, the MIME type to
use for the attachment. If the MIME type is omitted, it will be guessed
from the filename. You can use it like this::
message.attach_file("/images/weather_map.png")
For MIME types starting with :mimetype:`text/`, binary data is handled
as in :meth:`attach`.
.. class:: EmailAttachment .. class:: EmailAttachment