#36907: Docs for email `fail_silently` are incorrect and inconsistent
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 6.0 | Severity: Normal
Keywords: email docs | Triage Stage:
fail_silently | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Several django.core.mail APIs support a `fail_silently` boolean argument.
This is documented three places in the email topic (quoting from
https://docs.djangoproject.com/en/6.0/topics/email/):
1. [https://docs.djangoproject.com/en/6.0/topics/email/#send-
mail:~:text=fail_silently%3A%20A%20boolean.%20When%20it%E2%80%99s%20False%2C%20send_mail()%20will%20raise%20an%20smtplib.SMTPException%20if%20an%20error%20occurs.%20See%20the%20smtplib%20docs%20for%20a%20list%20of%20possible%20exceptions%2C%20all%20of%20which%20are%20subclasses%20of%20SMTPException.
send_mail()]: "`fail_silently`: A boolean. When it’s `False`,
`send_mail()` will raise an `smtplib.SMTPException` if an error occurs.
See the `smtplib` docs for a list of possible exceptions, all of which are
subclasses of `SMTPException`."
2.
[https://docs.djangoproject.com/en/6.0/topics/email/#django.core.mail.EmailMessage.send:~:text=If%20the%20keyword%20argument%20fail_silently%20is%20True%2C%20exceptions%20raised%20while%20sending%20the%20message%20will%20be%20quashed.
EmailMessage.send()]: "If the keyword argument `fail_silently` is True,
exceptions raised while sending the message will be quashed."
3.
[https://docs.djangoproject.com/en/6.0/topics/email/#django.core.mail.get_connection:~:text=The%20keyword%2Donly%20fail_silently%20argument%20controls%20how%20the%20backend%20should%20handle%20errors.%20If%20fail_silently%20is%20True%2C%20exceptions%20during%20the%20email%20sending%20process%20will%20be%20silently%20ignored.
get_connection()]: "If `fail_silently` is True, exceptions during the
email sending process will be silently ignored."
The claims about `SMTPException` are accurate only when using an smtplib-
based EmailBackend. And even then not 100% true: Django's default SMTP
backend can also raise various `ssl.SSLError` and `OSError` exceptions.
Third-party backends might raise just about anything—e.g., a requests
`HTTPError` or boto3 `ClientError`. (The `SMTPException` language is
likely left over from before Django supported pluggable email backends and
secure SMTP connections.)
The other two sentences are mostly accurate, but should probably clarify
that only "some" errors are silently ignored. Callers must not assume they
can avoid all error handling with `fail_silently=True`.
The intent of `fail_silently` seems to be suppressing "expected errors"
that are common when sending mail, such as transient network problems. One
use case is for sending email as an error reporting mechanism, like in
Django's AdminEmailHandler.
Each EmailBackend implementation has its own logic for which errors should
fail silently and which remain loud. For example, Django's SMTP
EmailBackend will raise `ImproperlyConfigured` for settings problems or
`ValueError` for message serialization problems, even with
`fail_silently=True`.
Suggest updating all three places to use some context-appropriate version
of: "If `fail_silently` is True, some exceptions during the email sending
process will be silently ignored." And remove references to specific
errors in !#1. (And perhaps include a longer explanation of "some
exceptions" in !#2?)
If we want to document what specific exceptions might be raised during
sending, that should be moved to documentation for each individual email
backend. (I don't think it's necessary.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36907>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019c35472a6b-ce61fa40-4760-457f-8714-1f0c6ed19e0c-000000%40eu-central-1.amazonses.com.
