From 7f460494d2309ace004a400bae8fc59134dc325c Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 6 Nov 2019 21:50:44 -0800 Subject: [PATCH] bpo-38382: Document the early-out behavior for a zero (GH-17037) --- Doc/library/statistics.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst index a702b2463c3..00c0b539edc 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