gh-154746: Document `collections.Counter` internal order and display order (#154777)

https://github.com/python/cpython/commit/22fed93a21c36c032d87629e66ea5d1eeeecc96e
commit: 22fed93a21c36c032d87629e66ea5d1eeeecc96e
branch: main
author: Raymond Hettinger <[email protected]>
committer: rhettinger <[email protected]>
date: 2026-07-30T17:39:09-05:00
summary:

gh-154746: Document `collections.Counter` internal order and display order (#154777)

files:
M Doc/library/collections.rst

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index d09a6c92bbd37d..599a898eb2cef8 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -268,6 +268,15 @@ For example::
         >>> c['sausage'] = 0                        # counter entry with a zero count
         >>> del c['sausage']                        # del actually removes the entry
 
+    Counters maintain insertion order internally but display from most common to
+    least common when possible:
+
+        >>> c = Counter(a=1, b=2, c=3)
+        >>> c                                       # display most common to least
+        Counter({'c': 3, 'b': 2, 'a': 1})
+        >>> list(c.items())                         # original insertion order
+        [('a', 1), ('b', 2), ('c', 3)]
+
     .. versionadded:: 3.1
 
     .. versionchanged:: 3.7 As a :class:`dict` subclass, :class:`Counter`

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]