From 22fed93a21c36c032d87629e66ea5d1eeeecc96e Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Thu, 30 Jul 2026 17:39:09 -0500 Subject: [PATCH] gh-154746: Document `collections.Counter` internal order and display order (#154777) --- Doc/library/collections.rst | 9 +++++++++ 1 file changed, 9 insertions(+) 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` -- 2.47.3