Skip to content

Commit 9bd58b7

Browse files
committed
Refs #35514 -- Removed specific Django versions from outside deprecated blocks.
This follows the contributing guidelines that state: [...] Avoid referring to a specific version of Django outside a ``deprecated`` block. Even inside a block, it's often redundant to do so as these annotations render as "Deprecated since version A.B".
1 parent 3be19dc commit 9bd58b7

2 files changed

Lines changed: 36 additions & 25 deletions

File tree

docs/howto/mailers-migration.txt

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,14 @@
44
Migrating email to mailers
55
==========================
66

7-
Django 6.1 introduces the :setting:`MAILERS` setting, replacing
7+
Django has introduced the :setting:`MAILERS` setting, replacing
88
:setting:`EMAIL_BACKEND` and several other ``EMAIL_*`` settings. It also
9-
introduces :data:`.mail.mailers` for obtaining configured email backend
9+
introduced :data:`.mail.mailers` for obtaining configured email backend
1010
instances, replacing :func:`.mail.get_connection`. A new ``using`` argument
1111
replaces the earlier ``connection`` in Django functions that send email.
1212

13-
The older functionality and settings are still available, but are deprecated
14-
and will be removed in Django 7.0. This guide provides details on migrating
15-
existing projects to the new mailers functionality.
13+
This guide provides details on migrating existing projects to the new mailers
14+
functionality.
1615

1716
All Django projects that send email should:
1817

@@ -36,8 +35,7 @@ All Django projects that send email should:
3635

3736
Consider running with deprecation warnings enabled in production to catch
3837
those deprecations. Or carefully review your code (including third-party
39-
packages) for use of any deprecated email features that will change in
40-
Django 7.0.
38+
packages) for use of any deprecated email features.
4139

4240
Other updates are needed only for projects or reusable Django libraries that
4341
use these specific features:
@@ -95,6 +93,11 @@ use::
9593

9694
.. _deprecated-email-settings:
9795

96+
.. deprecated:: 6.1
97+
98+
The :setting:`EMAIL_BACKEND` and related ``EMAIL_*`` settings are
99+
deprecated.
100+
98101
The complete list of deprecated ``EMAIL_*`` settings and where they should be
99102
moved in a :setting:`MAILERS` configuration is:
100103

@@ -178,9 +181,10 @@ migration guide for recommended updates.
178181
Replacing ``get_connection()`` and ``connection`` arguments
179182
-----------------------------------------------------------
180183

181-
:func:`.mail.get_connection` is deprecated in Django 6.1, as is the
182-
``connection`` argument for passing backend instances directly to mail
183-
functions.
184+
.. deprecated:: 6.1
185+
186+
:func:`.mail.get_connection` and the ``connection`` argument for passing
187+
backend instances directly to mail functions are deprecated.
184188

185189
The replacement for ``get_connection()`` depends on how it is being called:
186190

@@ -247,9 +251,11 @@ The replacement for ``get_connection()`` depends on how it is being called:
247251
Replacing ``fail_silently``
248252
---------------------------
249253

250-
The ``fail_silently`` arguments to :func:`.send_mail`, :func:`.send_mass_mail`,
251-
:func:`.mail_admins`, :func:`.mail_managers`, and :meth:`.EmailMessage.send`
252-
are deprecated.
254+
.. deprecated:: 6.1
255+
256+
The ``fail_silently`` argument to :func:`.send_mail`,
257+
:func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and
258+
:meth:`.EmailMessage.send` are deprecated.
253259

254260
Existing code using ``fail_silently`` seems to have several different
255261
expectations for its behavior, many of which don't match the actual (and email
@@ -327,8 +333,7 @@ This is useful for error messages (e.g., ``raise InvalidMailer(f"Bad host
327333
passed to backend init as keyword arguments.
328334

329335
For reusable libraries that want to support compatibility with deprecated mail
330-
functions and settings (similar to Django's built-in email backends), or that
331-
still support Django versions earlier than 6.1:
336+
functions and settings, or that support older Django versions:
332337

333338
* A backend can detect it is being initialized without :setting:`MAILERS` by
334339
checking if ``self.alias is None``. (Django's built-in backends check this to
@@ -349,11 +354,14 @@ still support Django versions earlier than 6.1:
349354
Replacing ``auth_user`` and ``auth_password``
350355
---------------------------------------------
351356

352-
The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` and
353-
:func:`.send_mass_mail` are deprecated. To replace them, define a custom
354-
:setting:`MAILERS` configuration with ``"username"`` and ``"password"``
355-
:setting:`"OPTIONS" <MAILERS-OPTIONS>`, and refer to that configuration with
356-
the ``using`` argument when sending mail.
357+
.. deprecated:: 6.1
358+
359+
The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail`
360+
and :func:`.send_mass_mail` are deprecated.
361+
362+
To replace them, define a custom :setting:`MAILERS` configuration with
363+
``"username"`` and ``"password"`` :setting:`"OPTIONS" <MAILERS-OPTIONS>`, and
364+
refer to that configuration with the ``using`` argument when sending mail.
357365

358366
For example, to upgrade::
359367

@@ -389,9 +397,13 @@ And then refer to it when sending::
389397
Updating AdminEmailHandler ``email_backend``
390398
--------------------------------------------
391399

392-
The ``email_backend`` argument to the logging :class:`.AdminEmailHandler` is
393-
deprecated. Replace it with a custom :setting:`MAILERS` configuration and refer
394-
to that configuration with the ``using`` argument.
400+
.. deprecated:: 6.1
401+
402+
The ``email_backend`` argument to the logging :class:`.AdminEmailHandler`
403+
is deprecated.
404+
405+
Replace it with a custom :setting:`MAILERS` configuration and refer to that
406+
configuration with the ``using`` argument.
395407

396408
For example, if your settings include::
397409

docs/ref/settings.txt

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2158,8 +2158,7 @@ configuration process will be skipped.
21582158

21592159
.. versionadded:: 6.1
21602160

2161-
Default: no default until Django 7.0, then ``{}``. (See deprecation note
2162-
below.)
2161+
Default: no default until the deprecation ends, then ``{}``.
21632162

21642163
A dictionary containing the settings for all email backends to be used with
21652164
Django. It is a nested dictionary that maps backend aliases to dictionaries

0 commit comments

Comments
 (0)