Alternative Python standard library reference

Question

I love Python; I absolutely despise its official documentation. Tutorials do not count as library references, but that appears to be what they're attempting.

What I really want is the ability to find a class in the standard library and view documentation for all of its properties and methods. Actionscript, MSDN, and Java all do this just fine (although each with their odd quirks).

Where is this for python?

For example, I wanted to sort a list. mylist.sort(). Awesome. But what if I wanted it sorted in descending order? Official documentation is not - much - help. Or what if I wanted to specify a key function? That's also supported: mylist.sort(key=lamba item: item.customVar)- but documented...where?

I understand that Python's approach to OOP may not be equivalent to Java et. al. Maybe list isn't actually a class - maybe it's just a function that returns an iterable when the tachyon beams are set to glorious and the unboxed hyper enumeration is quantized, but...I don't care. I just want to know how to sort lists.

(Apologies for the angst - too much caffeine today)

Answer 1

The problem isn't with list not being a class (it is), but with its interface not being unique to the class. So list.sort ends up being documented in the Mutable Sequence Types section.

The kind of information you want is available through the pydoc command-line tool, the help() builtin function, and (for example) the pydoc.org website. However, the specific example of list.sort isn't documented very well, there -- it's information that's built out of docstrings, and in most cases it's really a quick-reference, not particularly useful if you don't at all know what the documentation is about.

None of this really has to do with Python's approach to documentation or OOP or any of that, but really about it being an opensource project, and documentation all too frequently gets the least amount of investment in it. Patches, however, welcome.

Answer 2

The first google hit for "python list sorting" provides this helpful link on the Python wiki: "Sorting Mini HOWTO"

You're right that it could be better documented in the appropriate sections you linked above. Keep in mind that the examples of "good" documentation mention (Java, MSDN, ActionScript) have multimillion dollar companies behind them. I think the Python docs are quite good for an open source project, but would certainly benefit from further contributions. (Hint, hint. :-))

Answer 3

Given the use case mentioned in your Q, perhaps you would find it more convenient to access the Documentation this way:

(from a shell):

pydoc -p 8888

now point your browser to:

localhost:8888

So from here, you can access exactly what you mentioned, via 'builtin' > class:'list' > 'sort