jessenoller.com

I — like most peo­ple com­fort­able with my rel­a­tively sane (yet lim­ited) knowl­edge of Python — rarely go and read the python docs except when I know what I’m look­ing for. For exam­ple, I have a win­dow open to iter­tools and col­lec­tions open a lot more than I care to admit (I love you named­tu­ple. I loves you so much), but I rarely go off look­ing 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 — Ray­mond Het­tinger is a python core devel­oper and author/maintainer of quite a few inter­est­ing mod­ules within the stan­dard library (and a con­stant stream of ASPN recipes). Ray­mond is also highly active on python-dev and other lists the sub­ject 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 cur­rent mem­ber of the Python Soft­ware Foun­da­tion board of direc­tors. To say he’s active would be an understatement.

Back to the sub­ject at hand: Docs.

Ray­mond posted some­thing I think should see a lit­tle bit more atten­tion — as I stated in my opener, many of us are guilty of not read­ing much in the way of Python docs unless we are look­ing for some­thing spe­cific. We miss out on gems/updates to older docs that really make them shine. We also miss out on new exam­ples, and other things that really help make Python’s docs some of the best out there.

As I said in my for­ward to Doug Hellmann’s “The Python Stan­dard Library By Exam­ple” -

The stan­dard library’s doc­u­men­ta­tion is good, and con­stantly improving/evolving. Given the size and breadth of the stan­dard library, it’s amaz­ing for what it is. It’s awe­some that we have hun­dreds of pages of doc­u­men­ta­tion con­tributed by hun­dreds of devel­op­ers and users that are used every sin­gle day by hun­dreds of thou­sands of peo­ple to cre­ate things – things as sim­ple as one-off scripts, and as com­plex as the soft­ware that con­trols giant robotic arms.

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

• Pri­or­ity Queue Imple­men­ta­tion Notes
• Search­ing Sorted Lists
• Writ­ing a Tokenizer
• A Beefed out cmd example
• Ordered Dict exam­ples and Recipes
• The new log­ging howto/cookbook
• A howto on sorting
• collections.namedtuple (I <3 this thing)

The newly added/revised log­ging howto by Vinay (author/maintainer of the log­ging mod­ule) is really good to note (You have vis­ited the python docs how­tos, right? It’s here.). The addi­tional log­ging cook­book nicely com­pli­ments Vinay’s revised log­ging mod­ule documentation.

Oh, and if you were won­der­ing — yes, there is an easy to read list in the “What’s new” doc­u­ment for 2.7 (curated by Ray­mond) that lists out all the new Python 3 fea­tures back ported to python 2.7 for your read­ing plea­sure.

Last night, an addi­tional resource popped up on my radar — pyth0n.org — a site, while need­ing some CSS love (oh, the CSS love it needs) is an excel­lent way to jump to just about any­thing within Python (docs, classes, meth­ods, built-ins, etc). I think I killed it with load from tweet­ing about it last night, so be gen­tle. It really is a cool site, it’s like a uber-index of Python.

As an adden­dum — Ray­mond has also become very active on post­ing inter­est­ing bit of python knowledge/pro­tips on his twit­ter account, which have been a joy to see pop up in my tweet stream (Given how guilty I am of say­ing things that might be con­strued as “noise”). Some of highlights:

• #python fac­toid: random.sample() auto­mat­i­cally chooses an algo­rithm, remember-previous-picks or remove-picks-from-the-population
• #python pro-tip: deque’s optional maxlen argu­ment use­ful for n most recent items, mov­ing aver­ages, slid­ing win­dows, tail­ing files
• #python pro tip: def mean(s): return math.fsum(s)/len(s) # don’t lose pre­ci­sion while adding large num­bers of small values.
• Dirt sim­ple map/reduce util­ity for #python:http://code.activestate.com/recipes/577676

So, take a look around the lat­est docs and fol­low him, and other python devel­op­ers such (Barry War­saw, David Bea­z­ley, Nick Cogh­lan, R. David Mur­ray, Guido Van Rossum) on twit­ter (you can fol­low me if you want). Brett Can­non (another core com­mit­ter) has a twit­ter list of com­mit­ters.

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 excel­lent peo­ple con­tribute changes almost daily to them. They are a fan­tas­tic resource, and are greatly com­pli­mented by work like the Python Mod­ule of the Week (Doug Hell­mann) and other tuto­ri­als spread across the web.

If you know of a par­tic­u­larly good tuto­r­ial, or expla­na­tion of a mod­ule, you might con­sider sub­mit­ting a ticket cit­ing it, and sug­gest­ing it be included into the stan­dard library docs as well. What are some of your favorite doc­u­men­ta­tion gems, or exam­ples for Python?

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: Priority Queue Implementation Notes Searching Sorted Lists Writing a Tokenizer A Beefed out cmd example Ordered Dict examples and Recipes The new logging howto/cookbook A howto on sorting collections.namedtuple (I &lt;3 this thing) 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: #python factoid: random.sample() automatically chooses an algorithm, remember-previous-picks or remove-picks-from-the-population #python pro-tip: deque's optional maxlen argument useful for n most recent items, moving averages, sliding windows, tailing files #python 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 #python:http://code.activestate.com/recipes/577676 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?