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`.

186
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,72 +323,73 @@ 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 .. deprecated:: 6.0
Passing all except the first four parameters as positional arguments is Passing all except the first four parameters as positional arguments is
deprecated. deprecated.
For example:: For example::
from django.core.mail import EmailMessage from django.core.mail import EmailMessage
@ -402,72 +403,84 @@ For example::
headers={"Message-ID": "foo"}, headers={"Message-ID": "foo"},
) )
The class has the following methods: The class has the following methods:
* ``send(fail_silently=False)`` sends the message. If a connection was .. method:: send(fail_silently=False)
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 Sends the message. If a connection was specified when the email was
:class:`email.message.EmailMessage` object representing the message to be constructed, that connection will be used. Otherwise, an instance of
sent. 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 The keyword argument ``policy`` allows specifying the set of rules for
updating and serializing the representation of the message. It must be an updating and serializing the representation of the message. It must be
:mod:`email.policy.Policy <email.policy>` object. Defaults to 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.default`. In certain cases you may want to use
:data:`~email.policy.SMTP`, :data:`~email.policy.SMTPUTF8` or a custom :data:`~email.policy.SMTP`, :data:`~email.policy.SMTPUTF8` or a custom
policy. For example, :class:`django.core.mail.backends.smtp.EmailBackend` policy. For example,
uses the :data:`~email.policy.SMTP` policy to ensure ``\r\n`` line endings :class:`django.core.mail.backends.smtp.EmailBackend` uses the
as required by the SMTP protocol. :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` If you ever need to extend Django's :class:`EmailMessage` class,
class, you'll probably want to override this method to put the content you you'll probably want to override this method to put the content you
want into the Python EmailMessage object. want into the Python EmailMessage object.
.. versionchanged:: 6.0 .. versionchanged:: 6.0
The ``policy`` keyword argument was added and the return type was updated The ``policy`` keyword argument was added and the return type was
to an instance of :class:`~email.message.EmailMessage`. updated to an instance of :class:`~email.message.EmailMessage`.
* ``recipients()`` returns a list of all the recipients of the message, .. method:: recipients()
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. Returns a list of all the recipients of the message, whether they're
There are two ways to call ``attach()``: 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 * You can pass it three arguments: ``filename``, ``content`` and
``mimetype``. ``filename`` is the name of the file attachment as it will ``mimetype``. ``filename`` is the name of the file attachment as it
appear in the email, ``content`` is the data that will be contained inside will appear in the email, ``content`` is the data that will be
the attachment and ``mimetype`` is the optional MIME type for the contained inside the attachment and ``mimetype`` is the optional MIME
attachment. If you omit ``mimetype``, the MIME content type will be guessed type for the attachment. If you omit ``mimetype``, the MIME content
from the filename of the attachment. type will be guessed from the filename of the attachment.
For example:: For example::
message.attach("design.png", img_data, "image/png") message.attach("design.png", img_data, "image/png")
If you specify a ``mimetype`` of :mimetype:`message/rfc822`, ``content`` If you specify a ``mimetype`` of :mimetype:`message/rfc822`,
can be a :class:`django.core.mail.EmailMessage` or Python's ``content`` can be a :class:`django.core.mail.EmailMessage` or
:class:`email.message.EmailMessage` or :class:`email.message.Message`. Python's :class:`email.message.EmailMessage` or
:class:`email.message.Message`.
For a ``mimetype`` starting with :mimetype:`text/`, content is expected to For a ``mimetype`` starting with :mimetype:`text/`, content is
be a string. Binary data will be decoded using UTF-8, and if that fails, expected to be a string. Binary data will be decoded using UTF-8,
the MIME type will be changed to :mimetype:`application/octet-stream` and and if that fails, the MIME type will be changed to
the data will be attached unchanged. :mimetype:`application/octet-stream` and the data will be attached
unchanged.
* Or for attachments requiring additional headers or parameters, you can pass * Or for attachments requiring additional headers or parameters, you
``attach()`` a single Python :class:`~email.message.MIMEPart` object. can pass :meth:`!attach` a single Python
This will be attached directly to the resulting message. For example, :class:`~email.message.MIMEPart` object. This will be attached
to attach an inline image with a :mailheader:`Content-ID`:: directly to the resulting message. For example, to attach an inline
image with a :mailheader:`Content-ID`::
cid = email.utils.make_msgid() cid = email.utils.make_msgid()
inline_image = email.message.MIMEPart() inline_image = email.message.MIMEPart()
@ -481,27 +494,30 @@ The class has the following methods:
message.attach(inline_image) message.attach(inline_image)
message.attach_alternative(f'… <img src="cid:${cid}"> …', "text/html") message.attach_alternative(f'… <img src="cid:${cid}"> …', "text/html")
Python's :meth:`email.contentmanager.set_content` documentation describes Python's :meth:`email.contentmanager.set_content` documentation
the supported arguments for ``MIMEPart.set_content()``. describes the supported arguments for ``MIMEPart.set_content()``.
.. versionchanged:: 6.0 .. versionchanged:: 6.0
Support for :class:`~email.message.MIMEPart` attachments was added. Support for :class:`~email.message.MIMEPart` attachments was
added.
.. deprecated:: 6.0 .. deprecated:: 6.0
Support for :class:`email.mime.base.MIMEBase` attachments is Support for :class:`email.mime.base.MIMEBase` attachments is
deprecated. Use :class:`~email.message.MIMEPart` instead. deprecated. Use :class:`~email.message.MIMEPart` instead.
* ``attach_file()`` creates a new attachment using a file from your .. method:: attach_file(path, mimetype=None)
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 Creates a new attachment using a file from your filesystem. Call it
will be guessed from the filename. You can use it like this:: 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") message.attach_file("/images/weather_map.png")
For MIME types starting with :mimetype:`text/`, binary data is handled as in For MIME types starting with :mimetype:`text/`, binary data is handled
``attach()``. as in :meth:`attach`.
.. class:: EmailAttachment .. class:: EmailAttachment