1
0
mirror of https://github.com/django/django.git synced 2025-09-15 13:39:11 +00:00

Fixed #36597 -- Corrected directives for functions from email module in docs.

Thanks Mike Edmunds for the report.
This commit is contained in:
Mridul Dhall 2025-09-10 14:31:31 +01:00 committed by Mariusz Felisiak
parent 8956ee3ce3
commit e183d6c26c
7 changed files with 23 additions and 23 deletions

View File

@ -294,7 +294,7 @@ Methods
Sends an email to the user. If ``from_email`` is ``None``, Django uses Sends an email to the user. If ``from_email`` is ``None``, Django uses
the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the
underlying :meth:`~django.core.mail.send_mail` call. underlying :func:`~django.core.mail.send_mail` call.
Manager methods Manager methods
--------------- ---------------

View File

@ -1052,12 +1052,12 @@ together:
.. django-admin-option:: --managers .. django-admin-option:: --managers
Mails the email addresses specified in :setting:`MANAGERS` using Mails the email addresses specified in :setting:`MANAGERS` using
:meth:`~django.core.mail.mail_managers`. :func:`~django.core.mail.mail_managers`.
.. django-admin-option:: --admins .. django-admin-option:: --admins
Mails the email addresses specified in :setting:`ADMINS` using Mails the email addresses specified in :setting:`ADMINS` using
:meth:`~django.core.mail.mail_admins`. :func:`~django.core.mail.mail_admins`.
``shell`` ``shell``
--------- ---------

View File

@ -2656,7 +2656,7 @@ protocol.
.. admonition:: Why are my emails sent from a different address? .. admonition:: Why are my emails sent from a different address?
This address is used only for error messages. It is *not* the address that This address is used only for error messages. It is *not* the address that
regular email messages sent with :meth:`~django.core.mail.send_mail` regular email messages sent with :func:`~django.core.mail.send_mail`
come from; for that, see :setting:`DEFAULT_FROM_EMAIL`. come from; for that, see :setting:`DEFAULT_FROM_EMAIL`.
.. setting:: SHORT_DATE_FORMAT .. setting:: SHORT_DATE_FORMAT

View File

@ -878,7 +878,7 @@ of an SMTPConnection::
messages = get_notification_email() messages = get_notification_email()
connection.send_messages(messages) connection.send_messages(messages)
...should now call :meth:`~django.core.mail.get_connection` to ...should now call :func:`~django.core.mail.get_connection` to
instantiate a generic email connection:: instantiate a generic email connection::
from django.core.mail import get_connection from django.core.mail import get_connection
@ -900,7 +900,7 @@ SMTP connection::
If your call to construct an instance of ``SMTPConnection`` required If your call to construct an instance of ``SMTPConnection`` required
additional arguments, those arguments can be passed to the additional arguments, those arguments can be passed to the
:meth:`~django.core.mail.get_connection` call:: :func:`~django.core.mail.get_connection` call::
connection = get_connection( connection = get_connection(
"django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234 "django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234

View File

@ -292,8 +292,8 @@ requests. These include:
* Support for HttpOnly_ cookies. * Support for HttpOnly_ cookies.
* :meth:`~django.core.mail.mail_admins` and * :func:`~django.core.mail.mail_admins` and
:meth:`~django.core.mail.mail_managers` now support easily attaching :func:`~django.core.mail.mail_managers` now support easily attaching
HTML content to messages. HTML content to messages.
* :class:`~django.core.mail.EmailMessage` now supports CC's. * :class:`~django.core.mail.EmailMessage` now supports CC's.

View File

@ -422,7 +422,7 @@ Minor features
* Any ``**kwargs`` passed to * Any ``**kwargs`` passed to
:meth:`~django.contrib.auth.models.User.email_user` are passed to the :meth:`~django.contrib.auth.models.User.email_user` are passed to the
underlying :meth:`~django.core.mail.send_mail` call. underlying :func:`~django.core.mail.send_mail` call.
* The :func:`~django.contrib.auth.decorators.permission_required` decorator can * The :func:`~django.contrib.auth.decorators.permission_required` decorator can
take a list of permissions as well as a single permission. take a list of permissions as well as a single permission.

View File

@ -133,11 +133,11 @@ can be ``0`` or ``1`` since it can only send one message).
(subject, message, from_email, recipient_list) (subject, message, from_email, recipient_list)
``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the ``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the
same functions as in :meth:`~django.core.mail.send_mail`. They must be given same functions as in :func:`~django.core.mail.send_mail`. They must be given
as keyword arguments if used. as keyword arguments if used.
Each separate element of ``datatuple`` results in a separate email message. Each separate element of ``datatuple`` results in a separate email message.
As in :meth:`~django.core.mail.send_mail`, recipients in the same As in :func:`~django.core.mail.send_mail`, recipients in the same
``recipient_list`` will all see the other addresses in the email messages' ``recipient_list`` will all see the other addresses in the email messages'
"To:" field. "To:" field.
@ -169,12 +169,12 @@ The return value will be the number of successfully delivered messages.
``send_mass_mail()`` vs. ``send_mail()`` ``send_mass_mail()`` vs. ``send_mail()``
---------------------------------------- ----------------------------------------
The main difference between :meth:`~django.core.mail.send_mass_mail` and The main difference between :func:`~django.core.mail.send_mass_mail` and
:meth:`~django.core.mail.send_mail` is that :func:`~django.core.mail.send_mail` is that
:meth:`~django.core.mail.send_mail` opens a connection to the mail server :func:`~django.core.mail.send_mail` opens a connection to the mail server
each time it's executed, while :meth:`~django.core.mail.send_mass_mail` uses each time it's executed, while :func:`~django.core.mail.send_mass_mail` uses
a single connection for all of its messages. This makes a single connection for all of its messages. This makes
:meth:`~django.core.mail.send_mass_mail` slightly more efficient. :func:`~django.core.mail.send_mass_mail` slightly more efficient.
``mail_admins()`` ``mail_admins()``
================= =================
@ -248,7 +248,7 @@ scripts generate.
The Django email functions outlined above all protect against header injection The Django email functions outlined above all protect against header injection
by forbidding newlines in header values. If any ``subject``, ``from_email`` or by forbidding newlines in header values. If any ``subject``, ``from_email`` or
``recipient_list`` contains a newline (in either Unix, Windows or Mac style), ``recipient_list`` contains a newline (in either Unix, Windows or Mac style),
the email function (e.g. :meth:`~django.core.mail.send_mail`) will raise the email function (e.g. :func:`~django.core.mail.send_mail`) will raise
:exc:`ValueError` and, hence, will not send the email. It's your responsibility :exc:`ValueError` and, hence, will not send the email. It's your responsibility
to validate all data before passing it to the email functions. to validate all data before passing it to the email functions.
@ -291,18 +291,18 @@ from the request's POST data, sends that to admin@example.com and redirects to
The ``EmailMessage`` class The ``EmailMessage`` class
========================== ==========================
Django's :meth:`~django.core.mail.send_mail` and Django's :func:`~django.core.mail.send_mail` and
:meth:`~django.core.mail.send_mass_mail` functions are actually thin :func:`~django.core.mail.send_mass_mail` functions are actually thin
wrappers that make use of the :class:`~django.core.mail.EmailMessage` class. wrappers that make use of the :class:`~django.core.mail.EmailMessage` class.
Not all features of the :class:`~django.core.mail.EmailMessage` class are Not all features of the :class:`~django.core.mail.EmailMessage` class are
available through the :meth:`~django.core.mail.send_mail` and related available through the :func:`~django.core.mail.send_mail` and related
wrapper functions. If you wish to use advanced features, such as BCC'ed wrapper functions. If you wish to use advanced features, such as BCC'ed
recipients, file attachments, or multi-part email, you'll need to create recipients, file attachments, or multi-part email, you'll need to create
:class:`~django.core.mail.EmailMessage` instances directly. :class:`~django.core.mail.EmailMessage` instances directly.
.. note:: .. note::
This is a design feature. :meth:`~django.core.mail.send_mail` and This is a design feature. :func:`~django.core.mail.send_mail` and
related functions were originally the only interface Django provided. related functions were originally the only interface Django provided.
However, the list of parameters they accepted was slowly growing over However, the list of parameters they accepted was slowly growing over
time. It made sense to move to a more object-oriented design for email time. It made sense to move to a more object-oriented design for email
@ -675,7 +675,7 @@ It can also be used as a context manager, which will automatically call
Obtaining an instance of an email backend Obtaining an instance of an email backend
----------------------------------------- -----------------------------------------
The :meth:`get_connection` function in ``django.core.mail`` returns an The :func:`get_connection` function in ``django.core.mail`` returns an
instance of the email backend that you can use. instance of the email backend that you can use.
.. function:: get_connection(backend=None, *, fail_silently=False, **kwargs) .. function:: get_connection(backend=None, *, fail_silently=False, **kwargs)
@ -756,7 +756,7 @@ The file backend writes emails to a file. A new file is created for each new
session that is opened on this backend. The directory to which the files are session that is opened on this backend. The directory to which the files are
written is either taken from the :setting:`EMAIL_FILE_PATH` setting or from written is either taken from the :setting:`EMAIL_FILE_PATH` setting or from
the ``file_path`` keyword when creating a connection with the ``file_path`` keyword when creating a connection with
:meth:`~django.core.mail.get_connection`. :func:`~django.core.mail.get_connection`.
To specify this backend, put the following in your settings:: To specify this backend, put the following in your settings::