diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 3 | ||||
| -rw-r--r-- | docs/releases/6.0.txt | 20 | ||||
| -rw-r--r-- | docs/topics/email.txt | 66 |
3 files changed, 75 insertions, 14 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index fb37d43849..98b8eade75 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -38,6 +38,9 @@ details on these changes. argument of ``django.core.paginator.Paginator`` and ``django.core.paginator.AsyncPaginator`` will no longer be allowed. +* The :mod:`django.core.mail` APIs will no longer accept certain parameters as + positional arguments. These must be passed as keyword arguments instead. + .. _deprecation-removed-in-6.1: 6.1 diff --git a/docs/releases/6.0.txt b/docs/releases/6.0.txt index a7306ba755..3f4ce44a75 100644 --- a/docs/releases/6.0.txt +++ b/docs/releases/6.0.txt @@ -405,6 +405,26 @@ Miscellaneous Features deprecated in 6.0 ========================== +Positional arguments in ``django.core.mail`` APIs +------------------------------------------------- + +.. currentmodule:: django.core.mail + +:mod:`django.core.mail` APIs now require keyword arguments for less commonly +used parameters. Using positional arguments for these now emits a deprecation +warning and will raise a :exc:`TypeError` when the deprecation period ends. + +* All *optional* parameters (``fail_silently`` and later) must be passed as + keyword arguments to :func:`get_connection`, :func:`mail_admins`, + :func:`mail_managers`, :func:`send_mail`, and :func:`send_mass_mail`. + +* All parameters must be passed as keyword arguments when creating an + :class:`EmailMessage` or :class:`EmailMultiAlternatives` instance, except for + the first four (``subject``, ``body``, ``from_email``, and ``to``), which may + still be passed either as positional or keyword arguments. + +.. currentmodule:: None + Miscellaneous ------------- diff --git a/docs/topics/email.txt b/docs/topics/email.txt index 77419d4eab..ec87f0337b 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -76,7 +76,7 @@ a secure connection is used. ``send_mail()`` =============== -.. function:: send_mail(subject, message, from_email, recipient_list, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None) +.. function:: send_mail(subject, message, from_email, recipient_list, *, fail_silently=False, auth_user=None, auth_password=None, connection=None, html_message=None) In most cases, you can send email using ``django.core.mail.send_mail()``. @@ -90,6 +90,10 @@ are required. * ``recipient_list``: A list of strings, each an email address. Each member of ``recipient_list`` will see the other recipients in the "To:" field of the email message. + +The following parameters are optional, and must be given as keyword arguments +if used. + * ``fail_silently``: A boolean. When it's ``False``, ``send_mail()`` will raise an :exc:`smtplib.SMTPException` if an error occurs. See the :mod:`smtplib` docs for a list of possible exceptions, all of which are subclasses of @@ -112,10 +116,15 @@ are required. The return value will be the number of successfully delivered messages (which can be ``0`` or ``1`` since it can only send one message). +.. deprecated:: 6.0 + + Passing ``fail_silently`` and later parameters as positional arguments is + deprecated. + ``send_mass_mail()`` ==================== -.. function:: send_mass_mail(datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None) +.. function:: send_mass_mail(datatuple, *, fail_silently=False, auth_user=None, auth_password=None, connection=None) ``django.core.mail.send_mass_mail()`` is intended to handle mass emailing. @@ -123,8 +132,9 @@ can be ``0`` or ``1`` since it can only send one message). (subject, message, from_email, recipient_list) -``fail_silently``, ``auth_user`` and ``auth_password`` have the same functions -as in :meth:`~django.core.mail.send_mail()`. +``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the +same functions as in :meth:`~django.core.mail.send_mail()`. They must be given +as keyword arguments if used. Each separate element of ``datatuple`` results in a separate email message. As in :meth:`~django.core.mail.send_mail()`, recipients in the same @@ -151,6 +161,11 @@ mail server would be opened:: The return value will be the number of successfully delivered messages. +.. deprecated:: 6.0 + + Passing ``fail_silently`` and later parameters as positional arguments is + deprecated. + ``send_mass_mail()`` vs. ``send_mail()`` ---------------------------------------- @@ -164,7 +179,7 @@ a single connection for all of its messages. This makes ``mail_admins()`` ================= -.. function:: mail_admins(subject, message, fail_silently=False, connection=None, html_message=None) +.. function:: mail_admins(subject, message, *, fail_silently=False, connection=None, html_message=None) ``django.core.mail.mail_admins()`` is a shortcut for sending an email to the site admins, as defined in the :setting:`ADMINS` setting. @@ -182,15 +197,25 @@ If ``html_message`` is provided, the resulting email will be a :mimetype:`text/plain` content type and ``html_message`` as the :mimetype:`text/html` content type. +.. deprecated:: 6.0 + + Passing ``fail_silently`` and later parameters as positional arguments is + deprecated. + ``mail_managers()`` =================== -.. function:: mail_managers(subject, message, fail_silently=False, connection=None, html_message=None) +.. function:: mail_managers(subject, message, *, fail_silently=False, connection=None, html_message=None) ``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it sends an email to the site managers, as defined in the :setting:`MANAGERS` setting. +.. deprecated:: 6.0 + + Passing ``fail_silently`` and later parameters as positional arguments is + deprecated. + Examples ======== @@ -294,9 +319,11 @@ email backend API :ref:`provides an alternative .. class:: EmailMessage The :class:`~django.core.mail.EmailMessage` class is initialized with the -following parameters (in the given order, if positional arguments are used). -All parameters are optional and can be set at any time prior to calling the -``send()`` method. +following parameters. All parameters are optional and can be set at any time +prior to calling the ``send()`` method. + +The first four parameters can be passed as positional or keyword arguments, +but must be in the given order if positional arguments are used: * ``subject``: The subject line of the email. @@ -308,6 +335,8 @@ All parameters are optional and can be set at any time prior to calling the * ``to``: A list or tuple of recipient addresses. +The following parameters must be given as keyword arguments if used: + * ``bcc``: A list or tuple of addresses used in the "Bcc" header when sending the email. @@ -338,6 +367,11 @@ All parameters are optional and can be set at any time prior to calling the * ``reply_to``: A list or tuple of recipient addresses used in the "Reply-To" header when sending the email. +.. deprecated:: 6.0 + + Passing all except the first four parameters as positional arguments is + deprecated. + For example:: from django.core.mail import EmailMessage @@ -347,7 +381,7 @@ For example:: "Body goes here", "from@example.com", ["to1@example.com", "to2@example.com"], - ["bcc@example.com"], + bcc=["bcc@example.com"], reply_to=["another@example.com"], headers={"Message-ID": "foo"}, ) @@ -582,15 +616,15 @@ instance of the email backend that you can use. .. currentmodule:: django.core.mail -.. function:: get_connection(backend=None, fail_silently=False, **kwargs) +.. function:: get_connection(backend=None, *, fail_silently=False, **kwargs) By default, a call to ``get_connection()`` will return an instance of the email backend specified in :setting:`EMAIL_BACKEND`. If you specify the ``backend`` argument, an instance of that backend will be instantiated. -The ``fail_silently`` argument controls how the backend should handle errors. -If ``fail_silently`` is True, exceptions during the email sending process -will be silently ignored. +The keyword-only ``fail_silently`` argument controls how the backend should +handle errors. If ``fail_silently`` is True, exceptions during the email +sending process will be silently ignored. All other keyword arguments are passed directly to the constructor of the email backend. @@ -600,6 +634,10 @@ SMTP backend (which is the default), these backends are only useful during testing and development. If you have special email sending requirements, you can :ref:`write your own email backend <topic-custom-email-backend>`. +.. deprecated:: 6.0 + + Passing ``fail_silently`` as positional argument is deprecated. + .. _topic-email-smtp-backend: SMTP backend |