Issues with `collections.Counter`

[brass75]

Bug report

Bug description:

I have found 2 issues with collections.Counter:

1. There is a discrepancy between the documentation on docs.python.org and help(collections.Counter). The former includes 2 additional constructor formats that are not mentioned in the help output:

• class collections.Counter(**kwargs)
• class collections.Counter(mapping, /, **kwargs)
  Since the help output only includes class collections.Counter(iterable, /, **kwargs) the implication is that a call to collections.Counter({'a': 1, 'b': 2}) will return collections.Counter({'a': 1, 'b': 1}) while in fact it will return collections.Counter({'b': 2, 'a': 1}). This behavior is documented on docs.python.org (although somewhat ambiguously) but not in the help output.

2. When initializing a collections.Counter object with a Mapping the collections.Counter object that is returned has the mapping reversed:

>>> Counter({'a': 1, 'b': 2})
Counter({'b': 2, 'a': 1})

Since dicts preserve insertion order this behaviour is counterintuitive. Either the order should be preserved or the reversal should be documented.

CC @nedbat @willingc

CPython versions tested on:

3.14

Operating systems tested on:

macOS

Linked PRs

• gh-154746: Document collections.Counter internal order and display order #154777
• gh-154746: Update doc string for collections.Counter #154792
• [3.15] gh-154746: Update docstring for collections.Counter (GH-154792) #154793
• [3.14] gh-154746: Update docstring for collections.Counter (GH-154792) #154794
• [3.13] gh-154746: Update docstring for collections.Counter (GH-154792) #154795

[StanFromIreland]

When initializing a collections.Counter object with a Mapping the collections.Counter object that is returned has the mapping reversed:

This is actually just a feature of the repr, it orders from the most common to the least:

cpython/Lib/collections/__init__.py

Lines 750 to 755 in 5afbb60

	try:
	# dict() preserves the ordering returned by most_common()
	d = dict(self.most_common())
	except TypeError:
	# handle case where values are not orderable
	d = dict(self)

The underlying storage is untouched:

>>> Counter({'a': 1, 'b': 2})
Counter({'b': 2, 'a': 1})
>>> list(Counter({'a': 1, 'b': 2}))
['a', 'b']

I'm not sure this is something we need to explicitly document currently, we don't document the repr or str representation of most types.

[brass75]

It should probably be documented that the repr is sorted when possible but insertion order is still preserved.

[StanFromIreland]

The ordering is deliberate (the repr has gone through most_common() since Counter was added in b8baf63) but intentionally unspecified, like most repr formats, it's an implementation detail, and code shouldn't parse or depend on it.

[sirosen]

I poked at doing a doc improvement for help(Counter), but even that is not trivial.

I tried applying a simple update to the docstring, but there's no sensible way of applying this as far as I know. For example, I added a few signature lines to the docstring.

sample diff

diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py
index 20f1e728733..4e0d5da7197 100644
--- a/Lib/collections/__init__.py
+++ b/Lib/collections/__init__.py
@@ -549,7 +549,12 @@ def _count_elements(mapping, iterable):
     pass

 class Counter(dict):
-    '''Dict subclass for counting hashable items.  Sometimes called a bag
+    '''
+    Counter(**kwds)
+    Counter(iterable, /, **kwds)
+    Counter(mapping, /, **kwds)
+
+    Dict subclass for counting hashable items.  Sometimes called a bag
     or multiset.  Elements are stored as dictionary keys and their counts
     are stored as dictionary values.

but this (as expected) results in help() grabbing the init signature and inserting it before these lines:

class Counter(builtins.dict)
 |  Counter(iterable=None, /, **kwds)
 |
 |  Counter(**kwds)
 |  Counter(iterable, /, **kwds)
 |  Counter(mapping, /, **kwds)

I see the help() output being misaligned with the doc page as unfortunate, but not presently resolvable.

Making the doc page match the real class is feasible, but I think the docs are better than the help(), so that's a different regression in the name of consistency.

[brass75]

Since Mapping requires __iter__ that makes all Mappings Iterables. So I think the fix for that part of the discrepancy is to modify the docs to match the help(). With that, I think expanding on the line:

Elements are counted from an iterable or initialized from another mapping (or counter):

that is in the docs, and updating the help() output to include the same text in regards to initializing from a Mapping would be a reasonable solution. My suggested text would add the sentence:

When initializing from a another mapping (or counter) the values of that mapping will be used as is.

RE the repr() issue I would simply add something to the effect of:

As Counter is a subclass of dict the insertion order is preferred. This may or may not be reflected in the implementations of __str__ and __repr__.

That would help alleviate the confusion that I had. I will also say that I showed this to @willingc prior to opening the issue and she expressed similar confusion as to the changed order.

[rhettinger]

I will make a small update to the docs to note the display order (when the counts are orderable, most common to least common).