diff options
| author | Natalia <124304+nessita@users.noreply.github.com> | 2026-05-25 17:46:43 -0300 |
|---|---|---|
| committer | nessita <124304+nessita@users.noreply.github.com> | 2026-05-26 15:06:36 -0300 |
| commit | 9bd58b76fccfbbbe82f6d82f1d6385c498f3971d (patch) | |
| tree | 1ae1ce08125be1b50038712bc41d3f1013d19979 /docs | |
| parent | 3be19dcd89da43b5f3a5dc90a4259c0f9410c093 (diff) | |
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".
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/mailers-migration.txt | 58 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 3 |
2 files changed, 36 insertions, 25 deletions
diff --git a/docs/howto/mailers-migration.txt b/docs/howto/mailers-migration.txt index 7e7df08215..65aecdfc86 100644 --- a/docs/howto/mailers-migration.txt +++ b/docs/howto/mailers-migration.txt @@ -4,15 +4,14 @@ Migrating email to mailers ========================== -Django 6.1 introduces the :setting:`MAILERS` setting, replacing +Django has introduced the :setting:`MAILERS` setting, replacing :setting:`EMAIL_BACKEND` and several other ``EMAIL_*`` settings. It also -introduces :data:`.mail.mailers` for obtaining configured email backend +introduced :data:`.mail.mailers` for obtaining configured email backend instances, replacing :func:`.mail.get_connection`. A new ``using`` argument replaces the earlier ``connection`` in Django functions that send email. -The older functionality and settings are still available, but are deprecated -and will be removed in Django 7.0. This guide provides details on migrating -existing projects to the new mailers functionality. +This guide provides details on migrating existing projects to the new mailers +functionality. All Django projects that send email should: @@ -36,8 +35,7 @@ All Django projects that send email should: Consider running with deprecation warnings enabled in production to catch those deprecations. Or carefully review your code (including third-party - packages) for use of any deprecated email features that will change in - Django 7.0. + packages) for use of any deprecated email features. Other updates are needed only for projects or reusable Django libraries that use these specific features: @@ -95,6 +93,11 @@ use:: .. _deprecated-email-settings: +.. deprecated:: 6.1 + + The :setting:`EMAIL_BACKEND` and related ``EMAIL_*`` settings are + deprecated. + The complete list of deprecated ``EMAIL_*`` settings and where they should be moved in a :setting:`MAILERS` configuration is: @@ -178,9 +181,10 @@ migration guide for recommended updates. Replacing ``get_connection()`` and ``connection`` arguments ----------------------------------------------------------- -:func:`.mail.get_connection` is deprecated in Django 6.1, as is the -``connection`` argument for passing backend instances directly to mail -functions. +.. deprecated:: 6.1 + + :func:`.mail.get_connection` and the ``connection`` argument for passing + backend instances directly to mail functions are deprecated. The replacement for ``get_connection()`` depends on how it is being called: @@ -247,9 +251,11 @@ The replacement for ``get_connection()`` depends on how it is being called: Replacing ``fail_silently`` --------------------------- -The ``fail_silently`` arguments to :func:`.send_mail`, :func:`.send_mass_mail`, -:func:`.mail_admins`, :func:`.mail_managers`, and :meth:`.EmailMessage.send` -are deprecated. +.. deprecated:: 6.1 + + The ``fail_silently`` argument to :func:`.send_mail`, + :func:`.send_mass_mail`, :func:`.mail_admins`, :func:`.mail_managers`, and + :meth:`.EmailMessage.send` are deprecated. Existing code using ``fail_silently`` seems to have several different 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 passed to backend init as keyword arguments. For reusable libraries that want to support compatibility with deprecated mail -functions and settings (similar to Django's built-in email backends), or that -still support Django versions earlier than 6.1: +functions and settings, or that support older Django versions: * A backend can detect it is being initialized without :setting:`MAILERS` by 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: Replacing ``auth_user`` and ``auth_password`` --------------------------------------------- -The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` and -:func:`.send_mass_mail` are deprecated. To replace them, define a custom -:setting:`MAILERS` configuration with ``"username"`` and ``"password"`` -:setting:`"OPTIONS" <MAILERS-OPTIONS>`, and refer to that configuration with -the ``using`` argument when sending mail. +.. deprecated:: 6.1 + + The ``auth_user`` and ``auth_password`` arguments to :func:`.send_mail` + and :func:`.send_mass_mail` are deprecated. + +To replace them, define a custom :setting:`MAILERS` configuration with +``"username"`` and ``"password"`` :setting:`"OPTIONS" <MAILERS-OPTIONS>`, and +refer to that configuration with the ``using`` argument when sending mail. For example, to upgrade:: @@ -389,9 +397,13 @@ And then refer to it when sending:: Updating AdminEmailHandler ``email_backend`` -------------------------------------------- -The ``email_backend`` argument to the logging :class:`.AdminEmailHandler` is -deprecated. Replace it with a custom :setting:`MAILERS` configuration and refer -to that configuration with the ``using`` argument. +.. deprecated:: 6.1 + + The ``email_backend`` argument to the logging :class:`.AdminEmailHandler` + is deprecated. + +Replace it with a custom :setting:`MAILERS` configuration and refer to that +configuration with the ``using`` argument. For example, if your settings include:: diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 026d1b01a9..38e27d2dc1 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2158,8 +2158,7 @@ configuration process will be skipped. .. versionadded:: 6.1 -Default: no default until Django 7.0, then ``{}``. (See deprecation note -below.) +Default: no default until the deprecation ends, then ``{}``. A dictionary containing the settings for all email backends to be used with Django. It is a nested dictionary that maps backend aliases to dictionaries |
