classification
Title: Python 3.x internet documentation needs work
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: beazley, eric.araujo, ezio.melotti, georg.brandl, giampaolo.rodola, orsenthil, rafe.kettler, terry.reedy, yu_jin_zhi
Priority: normal Keywords: easy

Created on 2008-12-27 13:14 by beazley, last changed 2012-09-26 17:26 by ezio.melotti. This issue is now closed.

Messages (11)
msg78361 - (view) Author: David M. Beazley (beazley) Date: 2008-12-27 13:14
I have recently completed a pretty thorough survey of library 
documentation for Python 3.0 in conjunction with an update I'm making to 
my book.   This issue is not so much a bug as a documentation request.

For all of the library modules related to network programming, it would 
be extremely useful to be much very explicit about what methods work 
with strings and what methods requires byte.  So many of these modules 
operate on small fragments of data (e.g., send a request, add a header, 
parse a query string, etc.).  Sometimes using a string is okay, 
sometimes it's not and sadly, it's not often predictable.   Part of the 
problem is that the documentation has been written for a Python 2 world 
where text strings and binary data were interchangeable.

Anyways, this request minimally covers these modules:
 
      ftplib
      smtplib
      nntplib
      http.*
      urllib.*
      xmlrpc.*
      socketserver
      asynchat
      asyncore
    
If there is interest, I can submit more detailed notes from my own work, 
but I'm not sure how the documentation maintainer would want this.  
Separate issue for each?   Added as comments here?   Please advise.
msg78376 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-12-27 18:22
I'd be happy with comments on this bug.  I can't promise that I'll have
the time to review everything, but the more specific the remarks are,
the easier it's for me to update the docs.

Thanks for your efforts!
msg89969 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-07-01 10:14
David, I think that a list of notes posted here is ok, can you still
provide them?
msg96895 - (view) Author: 余谨智 (yu_jin_zhi) Date: 2009-12-27 03:20
As my opinion, Adding them as comments here is better as we can see the
same kind of issues all at once.
msg96897 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2009-12-27 04:07
If David doesn't answer I'd close this issue. A year passed since the
first message and several bugs have been probably fixed already.
msg96898 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2009-12-27 04:14
Hi Ezio, let us not close the issue. Waiting for David Beazley's patch
is okay or even looking at specific modules pointed out from the point
of str vs bytes interfaces and if any docs can be improved, we can
improve them. If we determine there is none, then we can close it as fixed.
msg96985 - (view) Author: David M. Beazley (beazley) Date: 2009-12-29 03:27
An apology on the delay.  Things have been rather hectic.

Regarding a patch, I don't really have a patch so much as a suggested 
procedure.   Basically, I'm suggesting that the maintainers of the 
library documentation simply do a quick survey of network related 
modules and make it clear that many of the operations work on "byte 
strings" and not "strings."     In Python 2.X, you could get away with 
being a little sloppy, but in Python 3, the bytes/strings distinction 
becomes much more prominent.

If I have time, I might be able to make a specific patch, but it 
probably wouldn't be until after PyCON sometime.
msg118370 - (view) Author: Rafe Kettler (rafe.kettler) Date: 2010-10-11 15:36
I stumbled upon this issue and I feel similarly about the documentation for a particular module, ftplib. I think that the documentation is a bit too concise and assumes that the reader in an expert in the protocol when the point of the module is to abstract out such details.

For example, for the error documentation, the exceptions are only explained by the error code the server can return to trigger them. So, while the explanation of error_perm, for example, should say something about permissions, it just says "raised when an error code in the range 500–599 is received." This is particularly unclear for those with no knowledge of the internals of the protocol.

Also, in the documentation for RetrLines(), the documentation mentions the options LIST, NLST, and MLSD without explaining what they are. I know that when I first started using ftplib I had to experiment with each option to determine what they do, and I think it would be better if this was clear in the docs from the start.

I can propose a patch to the documentation if needed.
msg118404 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-10-12 05:11
Rafe, thank you for your message and willingness to contribute.  I feel what you’re reporting is another bug: the original report talks about bytes/str confusion only, not about the simplicity of the APIs.   Could you open another bug with component “Documentation” and add orsenthil to the nosy list?  Thanks in advance.
msg118422 - (view) Author: Rafe Kettler (rafe.kettler) Date: 2010-10-12 13:27
Thanks Eric, I think you're right. I'll do that.
msg130407 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-09 03:06
I believe 3.2 has many code and doc improvements with respect to bytes/string usage. So it is hard to know what is still needed.

I think the way for anyone to advance this is to review just one of the modules listed and either report here that all is ok or open another issue just for that module and give a reference here.
History
Date User Action Args
2012-09-26 17:26:51ezio.melottisetstatus: languishing -> closed
resolution: out of date
stage: needs patch -> resolved
2011-03-10 22:26:48ezio.melottisetstatus: open -> languishing
nosy: + giampaolo.rodola
2011-03-09 03:06:50terry.reedysetnosy: + terry.reedy
messages: + msg130407
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-10-12 13:27:16rafe.kettlersetmessages: + msg118422
2010-10-12 05:11:46eric.araujosetmessages: + msg118404
2010-10-11 15:36:34rafe.kettlersetnosy: + rafe.kettler
messages: + msg118370
2010-03-28 00:45:41eric.araujosetnosy: + eric.araujo
2009-12-29 03:27:17beazleysetmessages: + msg96985
2009-12-28 22:02:28pitrousettitle: Python 3.0 internet documentation needs work -> Python 3.x internet documentation needs work
2009-12-27 04:14:39orsenthilsetstatus: pending -> open

messages: + msg96898
2009-12-27 04:07:29ezio.melottisetstatus: open -> pending

messages: + msg96897
versions: + Python 3.1, Python 3.2
2009-12-27 03:20:16yu_jin_zhisetnosy: + yu_jin_zhi

messages: + msg96895
versions: - Python 3.0
2009-07-01 10:14:42ezio.melottisetnosy: + ezio.melotti
messages: + msg89969
2009-04-22 18:47:54ajaksu2setpriority: normal
keywords: + easy
2009-02-12 18:45:38ajaksu2setnosy: + orsenthil
stage: needs patch
2008-12-27 18:22:23georg.brandlsetmessages: + msg78376
2008-12-27 13:14:39beazleycreate