[issue15013] smtplib: add low-level APIs to doc?
New submission from Sandro Tosi <sandro.tosi@gmail.com>: 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? ---------- assignee: docs@python components: Documentation messages: 162395 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: smtplib: add low-level APIs to doc? versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- components: +email nosy: +barry _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________
Terry J. Reedy added the comment: 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." ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________
Maciej Urbański added the comment: 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. ---------- keywords: +patch nosy: +rooter Added file: http://bugs.python.org/file45086/issue15013.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________
participants (4)
-
Maciej Urbański -
R. David Murray
-
Sandro Tosi
-
Terry J. Reedy