classification
Title: ftplib documentation is unclear
Type: enhancement Stage:
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, georg.brandl, giampaolo.rodola, orsenthil, rafe.kettler
Priority: normal Keywords: patch

Created on 2010-10-12 13:32 by rafe.kettler, last changed 2010-10-15 19:46 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
ftplib-patch.diff rafe.kettler, 2010-10-12 18:55
ftplib-patch.txt rafe.kettler, 2010-10-12 19:23
Messages (6)
msg118423 - (view) Author: Rafe Kettler (rafe.kettler) Date: 2010-10-12 13:32
I think that the documentation for ftplib 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.

This can become particularly unclear for less FTP-savvy users.

I can propose a patch to the documentation if needed.
msg118437 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2010-10-12 17:12
A patch would be great.
msg118459 - (view) Author: Rafe Kettler (rafe.kettler) Date: 2010-10-12 18:55
I've drafted up a patch. For those of you who don't want to read the diff, it changes all references to FTP reply codes with short explanations of what they do. Also, in the docs for retrlines() and nlst() the commands LIST, NLST, and MLSD are explained.

Attached is the patch.
msg118460 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-10-12 19:10
Looks good to me.  Before committing, spaces after full stops should be doubled.
msg118462 - (view) Author: Rafe Kettler (rafe.kettler) Date: 2010-10-12 19:23
Double spaced after the sentence ending periods.
msg118826 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-10-15 19:46
Committed after review in r85548.  Thanks!
History
Date User Action Args
2010-10-15 19:46:32georg.brandlsetstatus: open -> closed

nosy: + georg.brandl
messages: + msg118826

resolution: accepted
2010-10-12 19:23:09rafe.kettlersetfiles: + ftplib-patch.txt

messages: + msg118462
2010-10-12 19:22:43rafe.kettlersetfiles: - ftplib-patch.txt
2010-10-12 19:10:47eric.araujosetnosy: + eric.araujo
messages: + msg118460
2010-10-12 18:57:00rafe.kettlersetfiles: + ftplib-patch.txt
2010-10-12 18:56:14rafe.kettlersetfiles: - ftplib-patch.rst
2010-10-12 18:55:42rafe.kettlersetfiles: + ftplib-patch.diff
keywords: + patch
2010-10-12 18:55:21rafe.kettlersetfiles: + ftplib-patch.rst

messages: + msg118459
2010-10-12 17:12:40giampaolo.rodolasetmessages: + msg118437
2010-10-12 13:59:39pitrousetnosy: + giampaolo.rodola
2010-10-12 13:32:09rafe.kettlercreate