homepage

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

AltStyle によって変換されたページ (->オリジナル) /