The `collections.Counter` library contains very useful methods for playing with dicts and sets (mainly the most_common()) function.

Even though it is fairly trivial to retrieve the least common elements in a Counter() by doing Counter(...).most_common(n)[:-n:-1] I believe that for the sake of consistency, the `least_common` method should also be available. 

The attached patch contains the following:
- The method definition in Lib/__init__.py to support least_common;
- The tests to make sure least_common behaves as expected;
- The documentation for 2.7 and the general documentation.

Everywhere `most_common` was mentioned, you will now find `least_common` mentioned as well.

I left a review on Rietveld.
Since this is a new feature it can't go on 2.7, and it should target 3.4 instead.

What is use case for this method? Actually, any element which is not in a collection, is a least common for this collection.

Latest patch after code review round #1

Hi there @serhiy.storchaka, 

Consider the case where one would calculate the k-combination of set S. When the set has `n` elements, the number of k-combination is equal to its binomial coefficient. e.g. ( n!/( (k!(n-k)! ).

One method of statistically optimising the computation is to remove n least common elements from the set S. 

I do agree that this new method is merely for consistency because right now it is quite easy to simply do c.most_common(...)[:-(n+1):-1] to get th e least common elements. 

The goal of this patch is to make it intuitive to get the least common elements of a Counter, therefore making it easy to remove them from a collection.

Does it make any sense to you?

> One method of statistically optimising the computation is to remove n least common elements from the set S.

May be you need not remove least common elements from the set, but *get* a set of (len(S)-n) most common elements?

> Does it make any sense to you?

Frankly, not very much.

Note, that least common element is not defined in most cases. Usually there are only a few most (or even one) common elements, but a lot of least common elements. Result of least_common(n) is practically random due to hash randomization.

Another note is that most_common()[:-n] in many cases faster than least_common(n) for n >> 1. This is right for most_common(n) too, but it usually used for very small n (in particular for n=1) and this has more sense.

This proposition was discussed also on Python-Ideas (https://mail.python.org/pipermail/python-ideas/2017-March/045215.html).

I think it should be rejected. In general this doesn't make sense. In rare cases when you want to to get the least common items in the Counter (I don't know any practical examples), you can take a list of all items sorted by the value and take few last items.

Thank you for the suggestion, but I'm going to mark it as rejected for the reasons listed in the other posts.

stage: patch review -> resolved

messages: + msg180213

messages: + msg180204

stage: patch review