[Python-checkins] bpo-35892: Add usage note to mode() (GH-15122) (GH-15176)

[Raymond Hettinger]

https://github.com/python/cpython/commit/5925b7d555bc36bd43ee8704ae75cc51900cf2d4
commit: 5925b7d555bc36bd43ee8704ae75cc51900cf2d4
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Raymond Hettinger <rhettinger at users.noreply.github.com>
date: 2019-08-08T01:36:55-07:00
summary:

bpo-35892: Add usage note to mode() (GH-15122) (GH-15176)

(cherry picked from commit e43e7ed36480190083740fd75e2b9cdca72f1a68)

Co-authored-by: Raymond Hettinger <rhettinger at users.noreply.github.com>

files:
M Doc/library/statistics.rst

diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index a906a591e62c..1a19e3741921 100644
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -313,7 +313,9 @@ However, for reading convenience, most of the examples show sorted sequences.
    measure of central location.
 
    If there are multiple modes, returns the first one encountered in the *data*.
-   If *data* is empty, :exc:`StatisticsError` is raised.
+   If the smallest or largest of multiple modes is desired instead, use
+   ``min(multimode(data))`` or ``max(multimode(data))``.  If the input *data* is
+   empty, :exc:`StatisticsError` is raised.
 
    ``mode`` assumes discrete data, and returns a single value. This is the
    standard treatment of the mode as commonly taught in schools: