send_mail/send_messages do not document the return value

[Mark Jones]

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.

[mrezk]

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?

[Baptiste Mispelon]

Hi,

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

[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?

[Baptiste Mispelon]

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?

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

[mrezk]

Pull request updated.

[mrezk]

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

[mrezk]

Pull request updated.

[Baptiste Mispelon <bmispelon@…>]

In 7cd74fc96ee982acfed7a98e76d4623eabde146d:

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

[Baptiste Mispelon <bmispelon@…>]

In 841e21a85c17c87f8b7b41b5cbb5eae15888f9b7:

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

Backport of 7cd74fc96ee982acfed7a98e76d4623eabde146d from master.