[Django] #29430: django.core.mail.send_mail()'s fail_silently kwarg is documented incorrectly
Django
incorrectly
------------------------------------------+------------------------
Reporter: ティン・ルーフ | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 2.0
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------+------------------------
From https://docs.djangoproject.com/en/2.0/topics/email/#send-mail: “If
it’s False, send_mail will raise an smtplib.SMTPException.”
This is often untrue, and certainly misleading. Certainly, if it's False,
send_mail is ''capable'' of raising SMTPException, but it's not
guaranteed.
I was going to open a pull request and change it to “If it's True,
send_mail can raise smtplib.SMTPException”, but I'm not confident that
other exceptions cannot be raised, or that send_mail will never raise
SMTPException if fail_silently is True.
--
Ticket URL: <https://code.djangoproject.com/ticket/29430>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
incorrectly
Reporter: ティン・ルーフ | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 2.0
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Description changed by ティン・ルーフ:
Old description:
> From https://docs.djangoproject.com/en/2.0/topics/email/#send-mail: “If
> it’s False, send_mail will raise an smtplib.SMTPException.”
>
> This is often untrue, and certainly misleading. Certainly, if it's False,
> send_mail is ''capable'' of raising SMTPException, but it's not
> guaranteed.
>
> I was going to open a pull request and change it to “If it's True,
> send_mail can raise smtplib.SMTPException”, but I'm not confident that
> other exceptions cannot be raised, or that send_mail will never raise
> SMTPException if fail_silently is True.
New description:
From https://docs.djangoproject.com/en/2.0/topics/email/#send-mail: “If
it’s False, send_mail will raise an smtplib.SMTPException.”
This is often untrue, and certainly misleading. Certainly, if it's False,
send_mail is ''capable'' of raising SMTPException, but it's not
guaranteed.
I was going to open a pull request and change it to “If it's True,
send_mail can raise smtplib.SMTPException”, but I'm not confident that
other exceptions cannot be raised, or that send_mail will never raise
SMTPException if fail_silently is True.
The main thing I would like would be for the intent of fail_silently to be
expressed; what kind of errors is it trying to suppress, for example? What
kind of emails could a Django site be sending that are unimportant enough
that failing silently is a good idea?
--
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:1>
Django
--------------------------------+--------------------------------------
Reporter: ティン・ルーフ | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 2.0
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:2>
Django
--------------------------------------+------------------------------------
Reporter: ティン・ルーフ | Owner: nobody
Component: Documentation | Version: 2.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham):
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:3>
Django
--------------------------------------+------------------------------------
Reporter: ティン・ルーフ | Owner: nobody
Component: Documentation | Version: 2.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Sub):
From an initial glance, I can see that fail_silently is only used in the
smtp.py service file to decide whether an exception should be raised.
See lines 127-128:
https://github.com/django/django/blob/5a6f70b4281817656db2f36c5919036d38fcce7f/django/core/mail/backends/smtp.py
The exception to be raised in this case is smtplib.SMTPException. I agree
that it does not guarantee that this exception will be raised, and could
be misinterpreted. Maybe it would be clearer as "If it’s False, send_mail
will raise an smtplib.SMTPException if an error occurs." I think it should
definitely be explaining the False case, (not True) as we want to explain
the what happens if the failure isn't ignored.
Replying to [ticket:29430 ティン・ルーフ]:
> From https://docs.djangoproject.com/en/2.0/topics/email/#send-mail: “If
it’s False, send_mail will raise an smtplib.SMTPException.”
>
> This is often untrue, and certainly misleading. Certainly, if it's
False, send_mail is ''capable'' of raising SMTPException, but it's not
guaranteed.
>
> I was going to open a pull request and change it to “If it's True,
send_mail can raise smtplib.SMTPException”, but I'm not confident that
other exceptions cannot be raised, or that send_mail will never raise
SMTPException if fail_silently is True.
>
> The main thing I would like would be for the intent of fail_silently to
be expressed; what kind of errors is it trying to suppress, for example?
What kind of emails could a Django site be sending that are unimportant
enough that failing silently is a good idea?
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: ティン・ルーフ | Owner: Sub
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 2.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Sub):
* status: new => assigned
* owner: nobody => Sub
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:5>
Django
--------------------------------------+------------------------------------
Reporter: ティン・ルーフ | Owner: Sub
Component: Documentation | Version: 2.0
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"085ebc5f1a0e96784516e551cb9225cc6836f1d0" 085ebc5f]:
{{{
#!CommitTicketReference repository=""
revision="085ebc5f1a0e96784516e551cb9225cc6836f1d0"
Fixed #29430 -- Clarified send_mail()'s fail_silently docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:6>
Django
--------------------------------------+------------------------------------
Reporter: ティン・ルーフ | Owner: Sub
Type: Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"84afe81b9e31ed3819708aaac6fa00a9325d536d" 84afe81b]:
{{{
#!CommitTicketReference repository=""
revision="84afe81b9e31ed3819708aaac6fa00a9325d536d"
[2.1.x] Fixed #29430 -- Clarified send_mail()'s fail_silently docs.
Backport of 085ebc5f1a0e96784516e551cb9225cc6836f1d0 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/29430#comment:7>