Have you read your Python Docs Lately?

by jesse in ,

I - like most people comfortable with my relatively sane (yet limited) knowledge of Python - rarely go and read the python docs except when I know what I’m looking for. For example, I have a window open to itertools and collections open a lot more than I care to admit (I love you namedtuple. I loves you so much), but I rarely go off looking for new things/stuff that's changed.

For those few of you (and really, it should only be a few of you) who don’t know - Raymond Hettinger is a python core developer and author/maintainer of quite a few interesting modules within the standard library (and a constant stream of ASPN recipes). Raymond is also highly active on python-dev and other lists the subject of this post being python-list (the one list I refuse to join just due to the time/attention tradeoff).

Oh, he’s also a current member of the Python Software Foundation board of directors. To say he’s active would be an understatement.

Back to the subject at hand: Docs.

Raymond posted something I think should see a little bit more attention - as I stated in my opener, many of us are guilty of not reading much in the way of Python docs unless we are looking for something specific. We miss out on gems/updates to older docs that really make them shine. We also miss out on new examples, and other things that really help make Python’s docs some of the best out there.

As I said in my forward to Doug Hellmann’s “The Python Standard Library By Example” -

The standard library’s documentation is good, and constantly improving/evolving. Given the size and breadth of the standard library, it’s amazing for what it is. It’s awesome that we have hundreds of pages of documentation contributed by hundreds of developers and users that are used every single day by hundreds of thousands of people to create things – things as simple as one-off scripts, and as complex as the software that controls giant robotic arms.

In Raymond’s post to python-list, he listed some new/newly updated docs that are really interesting:

The newly added/revised logging howto by Vinay (author/maintainer of the logging module) is really good to note (You have visited the python docs howtos, right? It’s here.). The additional logging cookbook nicely compliments Vinay’s revised logging module documentation.

Oh, and if you were wondering - yes, there is an easy to read list in the “What’s new” document for 2.7 (curated by Raymond) that lists out all the new Python 3 features back ported to python 2.7 for your reading pleasure.

Last night, an additional resource popped up on my radar - pyth0n.org - a site, while needing some CSS love (oh, the CSS love it needs) is an excellent way to jump to just about anything within Python (docs, classes, methods, built-ins, etc). I think I killed it with load from tweeting about it last night, so be gentle. It really is a cool site, it's like a uber-index of Python.

As an addendum - Raymond has also become very active on posting interesting bit of python knowledge/protips on his twitter account, which have been a joy to see pop up in my tweet stream (Given how guilty I am of saying things that might be construed as “noise”). Some of highlights:

  • factoid: random.sample() automatically chooses an algorithm, remember-previous-picks or remove-picks-from-the-population
  • pro-tip: deque's optional maxlen argument useful for n most recent items, moving averages, sliding windows, tailing files
  • pro tip: def mean(s): return math.fsum(s)/len(s) # don't lose precision while adding large numbers of small values.
  • Dirt simple map/reduce utility for :

So, take a look around the latest docs and follow him, and other python developers such (Barry Warsaw, David Beazley, Nick Coghlan, R. David Murray, Guido Van Rossum) on twitter (you can follow me if you want). Brett Cannon (another core committer) has a twitter list of committers.

There’s been a lot of work done across the board to improve the docs, add to them and clean them up. A lot of excellent people contribute changes almost daily to them. They are a fantastic resource, and are greatly complimented by work like the Python Module of the Week (Doug Hellmann) and other tutorials spread across the web.

If you know of a particularly good tutorial, or explanation of a module, you might consider submitting a ticket citing it, and suggesting it be included into the standard library docs as well. What are some of your favorite documentation gems, or examples for Python?