This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: [doc] smtplib: add low-level APIs to doc?
Type: enhancement Stage: needs patch
Components: Documentation, email Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, docs@python, r.david.murray, rooter, sandro.tosi, terry.reedy
Priority: normal Keywords: patch

Created on 2012-06-06 07:44 by sandro.tosi, last changed 2022-04-11 14:57 by admin.

Files
File name Uploaded Description Edit
issue15013.patch rooter, 2016-10-13 20:48 review
Messages (4)
msg162395 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2012-06-06 07:44
In the smtplib doc I read:

  Low-level methods corresponding to the standard SMTP/ESMTP commands HELP, RSET, NOOP, MAIL, RCPT, and DATA are also supported. Normally these do not need to be called directly, so they are not documented here. For details, consult the module code.

Well, I think the documentation should include also those low-level apis (maybe in a separate subsection).

From my POV, smtplib should implement the protocol, and give the programmers the tools to use the protocol as they prefers, and as a plus some companion methods to easy the most common operations.

I'm in need to use the low-level apis, and not finding them in the doc is a disservice to me (with my user hat on ;)) and just say "go read the source" is kinda rude and unexpected.

What do you think?
msg162406 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-06-06 12:54
Well, personally I just read the code, and didn't think anything of it.  I guess Python code is documentation to me :)

I don't see why there would be any objection to documenting them if you want to, though.  It's not like we're going to want to change that API.
msg184806 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-20 21:49
By current standards, we normally document all public methods. 

.rset() and .noop() are trivial, "same as .docmd('funcname')"

.help() is almost trivial, just removing the first field of the reply (I assume a return code). 'returns message part of .putcmd('help')"

.mail(s, options) and .rcpt(r, options) are not so trivial. Explaining the possible options, I presume defined in the rfcs and used elsewhere by other methods, seems beyond the scope of the docs. "Open mail session; for *options* list, see RFCs" might be a possible entry.

.data(msg) also seems complicated in its details. I can see why the author left out such minutia for something that normally should not be called. I would be inclined to just say "Send message to server; see docstring for details."
msg278613 - (view) Author: Maciej Urbański (rooter) * Date: 2016-10-13 20:48
I guess documenting `data` method may still be needed after all. For now I followed the suggestions from comments to best of my ability.

Please see attached patch.
History
Date User Action Args
2022-04-11 14:57:31adminsetgithub: 59218
2021-12-06 14:40:30iritkatrielsettitle: smtplib: add low-level APIs to doc? -> [doc] smtplib: add low-level APIs to doc?
type: enhancement
versions: + Python 3.11, - Python 2.7, Python 3.2, Python 3.3
2016-10-13 20:48:50rootersetfiles: + issue15013.patch

nosy: + rooter
messages: + msg278613

keywords: + patch
2013-03-20 21:49:13terry.reedysetnosy: + terry.reedy
messages: + msg184806
2012-06-06 12:55:04r.david.murraysetnosy: + barry
components: + email
2012-06-06 12:54:49r.david.murraysetnosy: + r.david.murray
messages: + msg162406
2012-06-06 07:44:22sandro.tosicreate