[issue15013] smtplib: add low-level APIs to doc?

[Maciej Urbański]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15013] smtplib: add low-level APIs to doc?

[Terry J. Reedy]

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 rep...@bugs.python.org
http://bugs.python.org/issue15013
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15013] smtplib: add low-level APIs to doc?

[Sandro Tosi]

New submission from Sandro Tosi sandro.t...@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 rep...@bugs.python.org
http://bugs.python.org/issue15013
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15013] smtplib: add low-level APIs to doc?

[R. David Murray]

R. David Murray rdmur...@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 rep...@bugs.python.org
http://bugs.python.org/issue15013
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15013] smtplib: add low-level APIs to doc?

[R. David Murray]

Changes by R. David Murray rdmur...@bitdance.com:


--
components: +email
nosy: +barry

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue15013
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com