Add usage notes for collections.Counter()

diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index ebb35b1eabe71f7bc32fb8531a10a618ca451a95..b19af9c730d5c3ef99ec14b7e9606a7a59263138 100644 (file)
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -258,6 +258,33 @@ counts, but the output will exclude results with counts of zero or less.
     >>> c | d                       # union:  max(c[x], d[x])
     Counter({'a': 3, 'b': 2})
 
+.. note::
+
+   Counters were primarily designed to work with positive integers to represent
+   running counts; however, care was taken to not unnecessarily preclude use
+   cases needing other types or negative values.  To help with those use cases,
+   this section documents the minimum range and type restrictions.
+
+   * The :class:`Counter` class itself is a dictionary subclass with no
+     restrictions on its keys and values.  The values are intended to be numbers
+     representing counts, but you *could* store anything in the value field.
+
+   * The :meth:`most_common` method requires only that the values be orderable.
+
+   * For in-place operations such as ``c[key] += 1``, the value type need only
+     support addition and subtraction.  So fractions, floats, and decimals would
+     work and negative values are supported.  The same is also true for
+     :meth:`update` and :meth:`subtract` which allow negative and zero values
+     for both inputs and outputs.
+
+   * The multiset methods are designed only for use cases with positive values.
+     The inputs may be negative or zero, but only outputs with positive values
+     are created.  There are no type restrictions, but the value type needs to
+     support support addition, subtraction, and comparison.
+
+   * The :meth:`elements` method requires integer counts.  It ignores zero and
+     negative counts.
+
 .. seealso::
 
     * `Counter class <http://code.activestate.com/recipes/576611/>`_