Fixed #36163 -- Deprecated most positional arguments in django.core.mail.

In public mail APIs, changed less frequently used parameters from
keyword-or-positional to keyword-only, emitting a warning during the
required deprecation period.

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

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

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