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

[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.