[Python-checkins] bpo-25478: Add total() method to collections.Counter (GH-25829)

[rhettinger]

https://github.com/python/cpython/commit/8c598dbb9483bcfcb88fc579ebf27821d8861465
commit: 8c598dbb9483bcfcb88fc579ebf27821d8861465
branch: master
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2021-05-02T20:19:51-07:00
summary:

bpo-25478: Add total() method to collections.Counter (GH-25829)

files:
A Misc/NEWS.d/next/Library/2021-05-02-19-17-20.bpo-25478.AwlwdA.rst
M Doc/library/collections.rst
M Lib/collections/__init__.py
M Lib/test/test_collections.py

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 723c9da7be8d7b..94166ec6c754a7 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -313,6 +313,16 @@ For example::
 
         .. versionadded:: 3.2
 
+    .. method:: total()
+
+        Compute the sum of the counts.
+
+            >>> c = Counter(a=10, b=5, c=0)
+            >>> c.total()
+            15
+
+        .. versionadded:: 3.10
+
     The usual dictionary methods are available for :class:`Counter` objects
     except for two which work differently for counters.
 
@@ -342,7 +352,7 @@ All of those tests treat missing elements as having zero counts so that
 
 Common patterns for working with :class:`Counter` objects::
 
-    sum(c.values())                 # total of all counts
+    c.total()                       # total of all counts
     c.clear()                       # reset all counts
     list(c)                         # list unique elements
     set(c)                          # convert to a set
diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py
index 89c73bbf2c10d9..bae0805d6686c5 100644
--- a/Lib/collections/__init__.py
+++ b/Lib/collections/__init__.py
@@ -581,6 +581,10 @@ def __missing__(self, key):
         # Needed so that self[missing_item] does not raise KeyError
         return 0
 
+    def total(self):
+        'Sum of the counts'
+        return sum(self.values())
+
     def most_common(self, n=None):
         '''List the n most common elements and their counts from the most
         common to the least.  If n is None, then list all element counts.
diff --git a/Lib/test/test_collections.py b/Lib/test/test_collections.py
index 2ba1a19ead9d83..f98048b34a7a1d 100644
--- a/Lib/test/test_collections.py
+++ b/Lib/test/test_collections.py
@@ -2066,6 +2066,10 @@ def test_init(self):
         self.assertRaises(TypeError, Counter, (), ())
         self.assertRaises(TypeError, Counter.__init__)
 
+    def test_total(self):
+        c = Counter(a=10, b=5, c=0)
+        self.assertEqual(c.total(), 15)
+
     def test_order_preservation(self):
         # Input order dictates items() order
         self.assertEqual(list(Counter('abracadabra').items()),
diff --git a/Misc/NEWS.d/next/Library/2021-05-02-19-17-20.bpo-25478.AwlwdA.rst b/Misc/NEWS.d/next/Library/2021-05-02-19-17-20.bpo-25478.AwlwdA.rst
new file mode 100644
index 00000000000000..81d2724726dd06
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-05-02-19-17-20.bpo-25478.AwlwdA.rst
@@ -0,0 +1,2 @@
+Added a *total()* method to collections.Counter() to compute the sum of the
+counts.