Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#22455 closed Cleanup/optimization (fixed)

send_mail/send_messages do not document the return value

Reported by: Mark Jones Owned by: mrezk
Component: Documentation Version: 1.6
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

Change History (12)

comment:1 by Tim Graham, 11 years ago

Easy pickings: set
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

comment:2 by mrezk, 11 years ago

Owner: changed from nobody to mrezk
Status: newassigned

comment:3 by mrezk, 11 years ago

Has patch: set

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?

comment:4 by Baptiste Mispelon, 11 years ago

Patch needs improvement: set

Hi,

The sentence you added is incorrect: send_messages returns the number of emails sent (which is potentially 0).

comment:5 by mrezk, 11 years ago

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?

comment:6 by Baptiste Mispelon, 11 years ago

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?

comment:7 by mrezk, 11 years ago

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 that the return value is generally ignored.

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 =)

Last edited 11 years ago by mrezk (previous) (diff)

comment:8 by mrezk, 11 years ago

Patch needs improvement: unset

Pull request updated.

comment:9 by mrezk, 11 years ago

Pull request updated. Please feel free to make any subtle comments about style!

comment:10 by mrezk, 11 years ago

Pull request updated. Also included documentation for send_mass_mail return value

Last edited 11 years ago by mrezk (previous) (diff)

comment:11 by Baptiste Mispelon <bmispelon@…>, 11 years ago

Resolution: fixed
Status: assignedclosed

In 7cd74fc96ee982acfed7a98e76d4623eabde146d:

Fixed #22455 -- Documented return values for send_mail and send_mass_mail

comment:12 by Baptiste Mispelon <bmispelon@…>, 11 years ago

In 841e21a85c17c87f8b7b41b5cbb5eae15888f9b7:

[1.7.x] Fixed #22455 -- Documented return values for send_mail and send_mass_mail

Backport of 7cd74fc96ee982acfed7a98e76d4623eabde146d from master.

Note: See TracTickets for help on using tickets.
Back to Top