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.
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:31 | admin | set | github: 59218 |
| 2021年12月06日 14:40:30 | iritkatriel | set | title: 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:50 | rooter | set | files:
+ issue15013.patch nosy: + rooter messages: + msg278613 keywords: + patch |
| 2013年03月20日 21:49:13 | terry.reedy | set | nosy:
+ terry.reedy messages: + msg184806 |
| 2012年06月06日 12:55:04 | r.david.murray | set | nosy:
+ barry components: + email |
| 2012年06月06日 12:54:49 | r.david.murray | set | nosy:
+ r.david.murray messages: + msg162406 |
| 2012年06月06日 07:44:22 | sandro.tosi | create | |