I love python, I really do, and there is a library for everything you can imagine. So when I see things like this:

    c.most_common()[:-n:-1]  # n least common elements

For the love of ceiling_cat, how hard is it to implement a least_common method?

Well, that's pretty ugly anyway―what's wrong with:

    reversed(c.most_common())

Although I agree that a least_common function would be more "symmetrical" (don't ask me why c has one and not both), you can create it yourself (and have it not only readable but efficient!) in one line of code.

most_common(n) takes an optional argument, which makes a difference. With no arguments, you're just sorting the list, but when you just want the first N, you don't have to sort the entire list first. However, the partial-sorting optimizations are generally not symmetric, so supporting both most and least common would imply that either one direction is slower than the other, or the implementation is not as efficient as it could be for the case where only one direction is important. Only supporting most_common(n) makes it clear which case is optimized for.

In this case (Python's collections.Counter[1]), the argument doesn't do what you suggest: you don't return the most common out of the first n items, you return the n most common items.

I don't know anything of the specifics of partial sorting but if the argument did what you suggest I'd guess the code would have a line like:

    # Deal only with the first n items.
    items = items[:n]

As it would make the code much simpler (quoting from The Zen Of Python, "special cases aren't special enough to break the rules"—we don't need a partial sort).

[1] http://docs.python.org/library/collections.html#counter-obje...

  def least_common(c, n=None):
      key = operator.itemgetter(1)
      if n is None:
         return sorted(c.items(), key=key)
      return heapq.nsmallest(n, c.items(), key=key)

It has the same efficiency as Counter.most_common().

Not to pick nits, but this is off by one. If you need the n most common elements, you should use

  c.most_common()[:-n-1:-1]

because the element at

  c.most_common()[-n]

is actually the n-1th most common element.

Raymond Hettinger is a great Python educator, and also very active on the mailinglists. He gives talks, too:

Easy AI with Python: http://us.pycon.org/2009/conference/schedule/event/71/

Four powerful examples of composing Python tools: http://us.pycon.org/2010/conference/schedule/event/86/

Yup, I totally forgot to include his talks from the various conferences.

there is also this talk from pycon 2011:

Fun with Python's Newer Tools: http://blip.tv/file/4883247

I wish programming documentation in general were divided into two heavily linked parts, one conversational introductory section and one concise and technical reference section (like a manpage). By heavily linked, I mean the "conversational" section should have plenty of links to the reference section inline with the prose and vice versa. I don't like reading references when I don't even see the big picture. On the other hand, I don't like getting too used to intro material because it's too verbose to refer to later. But if the conversational part has links to the reference section and vice versa, I would get into the habit of following the links and gradually familiarizing myself with the layout of the reference section. Unfortunately, as it is, intros rarely have these links or footnotes to the references, and I have to search for items specifically, losing out on the holistic view.

Intro material, even if it's not too verbose, may omit important details anway. For example, a regex tutorial might only give a brief, vague explanation of raw strings (maybe a quick comment about not needing to escape backslashes, etc.). Eventually you'll want to read the more comprehensive reference on string literals, to make sure you haven't missed anything. (In the case of raw strings, unicode characters are still escaped and you can't end one with an odd number of backslashes.)

http://docs.python.org/reference/lexical_analysis.html#strin...

If you want a comprehensive introduction to Python that has no prerequisites, check out "Learning Python" by Mark Lutz. Unlike certain other so-called "introductory texts" this one doesn't presume that you're an expert in similar languages just picking up syntax.