From: Raymond Hettinger <rhettinger@users.noreply.github.com>
Date: Thu, 30 Jul 2026 22:39:09 +0000 (-0500)
Subject: gh-154746: Document `collections.Counter` internal order and display order (#154777)
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=22fed93a21c36c032d87629e66ea5d1eeeecc96e;p=thirdparty%2FPython%2Fcpython.git

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

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index d09a6c92bbd3..599a898eb2ce 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`