[Python-checkins] bpo-38382: Document the early-out behavior for a zero (GH-17037) (GH-17078)

[Raymond Hettinger]

https://github.com/python/cpython/commit/6b66dc387935df432cdbc01397ddef534a84ade9
commit: 6b66dc387935df432cdbc01397ddef534a84ade9
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-11-06T21:58:11-08:00
summary:

bpo-38382: Document the early-out behavior for a zero (GH-17037) (GH-17078)

(cherry picked from commit 7f460494d2309ace004a400bae8fc59134dc325c)

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 a702b2463c39b..00c0b539edce9 100644
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -164,7 +164,8 @@ However, for reading convenience, most of the examples show sorted sequences.
    The harmonic mean, sometimes called the subcontrary mean, is the
    reciprocal of the arithmetic :func:`mean` of the reciprocals of the
    data. For example, the harmonic mean of three values *a*, *b* and *c*
-   will be equivalent to ``3/(1/a + 1/b + 1/c)``.
+   will be equivalent to ``3/(1/a + 1/b + 1/c)``.  If one of the values
+   is zero, the result will be zero.
 
    The harmonic mean is a type of average, a measure of the central
    location of the data.  It is often appropriate when averaging
@@ -190,6 +191,10 @@ However, for reading convenience, most of the examples show sorted sequences.
    :exc:`StatisticsError` is raised if *data* is empty, or any element
    is less than zero.
 
+   The current algorithm has an early-out when it encounters a zero
+   in the input.  This means that the subsequent inputs are not tested
+   for validity.  (This behavior may change in the future.)
+
    .. versionadded:: 3.6