Iteration over strings

Jay Loden python at jayloden.com
Wed Aug 1 01:53:48 CEST 2007


Hexamorph wrote:
> Hexamorph schrieb:
>> Jay Loden schrieb:
>>> I have to agree with you WRT to the Python documentation, it does tend 
>>> to be lacking and difficult to find things at times.
> 
> Hmm, I find the Python documentation just excellent. You are 
> searching for a *string* related problem? Then just check the 
> *string* class. Also try the dir() function, like 
> dir(some_string_variable)
> 
> If you come from a C++ background this should be familar to you. 
> Check the appropriate class before trying some "procedural" way.
> 
> Anyway, glad we could help :)

Well, I don't want to start a flamewar or anything like that - after all, I'm on a Python mailing list, I love coding in Python, and I think it's a great language. I've just personally been repeatedly frustrated when programming on the lack of documentation for some modules (including some in the standard library).

Don't get me wrong, I love the documentation concepts like docstrings, pydoc, the online HTML docs, etc. What I don't like is how frequently I run into things that just aren't documented *well* ;) As an example, reading the docs for the "socket" module repeatedly tells you things like 'see the UNIX manual' instead of just documenting the appropriate information. I realize these are simply thin wrappers for C sockets, but that still assumes your audience is rather intimately familiar with socket programming in C on UNIX.

This isn't just a problem with the socket module, so please don't think I'm picking on it or singling it out, it's something I've seen a number of places. e.g. from os.stat: 

os.stat = stat(...)
    stat(path) -> stat result
    
    Perform a stat system call on the given path.

Ok...and what is the return value? a list? tuple? string? some type of stat object? dictionary? The only way to find out is to read the os module's source code or try it to find out. If you were really lucky you might find the related documentation from class statvfs_result and put two and two together to figure it out.

One of the items on my very long TODO list is to submit bug reports for items like the above but it's a long list and I just haven't gotten there yet ;)

-Jay



More information about the Python-list mailing list