[Django] #22455: send_mail/send_messages do not document the return value
Django
-------------------------------+--------------------
Reporter: mark0978 | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
Everything else is mentioned, but the return value for a successful
message sent is never specified.
Normally you would assume True means success, except that sometimes 0
means success to that an error can be flagged with the remaining values.
You can find the answer in the source, but that makes it take a good deal
longer. When talking about the backend and what it should implement, it
seems like the return value should be specified.
--
Ticket URL: <https://code.djangoproject.com/ticket/22455>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: mark0978 | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
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 timo):
* needs_better_patch: => 0
* needs_tests: => 0
* easy: 0 => 1
* needs_docs: => 0
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:1>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.6
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
--------------------------------------+------------------------------------
* owner: nobody => mrezk
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:2>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by mrezk):
* has_patch: 0 => 1
Comment:
Pull request created: https://github.com/django/django/pull/2576
I found out that actually `send_messages` is documented on this section:
https://docs.djangoproject.com/en/dev/topics/email/#defining-a-custom-
email-backend, do you think we should add more information somewhere else?
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:3>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_better_patch: 0 => 1
Comment:
Hi,
The sentence you added is incorrect: `send_messages` returns the number of
emails sent (which is potentially 0).
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:4>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by mrezk):
Hi,
That is true, but I am actually documenting `send_mail`. As far as I know,
you can only send 0 or 1 emails with that method, is there a way to send
more than 1 email with that method?
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:5>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by bmispelon):
You're absolutely right (I got too far down the rabbit hole of figuring
out what the return value was and forgot it was `send_message` we were
documenting).
Do we really need the "though generally ignored..." bit?
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:6>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by mrezk):
I thought that since I've never seen an example of `send_mail` which takes
in account the return value, it may be nice to clarify this.
If you don't think that it may be misleading that none of the examples
checks the return value, then it is OK for me to take it away =)
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:7>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* needs_better_patch: 1 => 0
Comment:
Pull request updated.
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:8>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by mrezk):
Pull request updated. Please feel free to make any subtle comments about
style!
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:9>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by mrezk):
Pull request updated.
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:10>
Django
Reporter: mark0978 | Owner: mrezk
Component: Documentation | Version: 1.6
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"7cd74fc96ee982acfed7a98e76d4623eabde146d"]:
{{{
#!CommitTicketReference repository=""
revision="7cd74fc96ee982acfed7a98e76d4623eabde146d"
Fixed #22455 -- Documented return values for send_mail and send_mass_mail
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:11>
Django
Reporter: mark0978 | Owner: mrezk
Type: Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by Baptiste Mispelon <bmispelon@…>):
In [changeset:"841e21a85c17c87f8b7b41b5cbb5eae15888f9b7"]:
{{{
#!CommitTicketReference repository=""
revision="841e21a85c17c87f8b7b41b5cbb5eae15888f9b7"
[1.7.x] Fixed #22455 -- Documented return values for send_mail and
send_mass_mail
Backport of 7cd74fc96ee982acfed7a98e76d4623eabde146d from master.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/22455#comment:12>