bpo-35904: Add statistics.fmean() (GH-11892)
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 7d051e1..79a7bdd 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -404,7 +404,7 @@
size five::
# http://statistics.about.com/od/Applications/a/Example-Of-Bootstrapping.htm
- from statistics import mean
+ from statistics import fmean as mean
from random import choices
data = 1, 2, 4, 4, 10
@@ -419,7 +419,7 @@
between the effects of a drug versus a placebo::
# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
- from statistics import mean
+ from statistics import fmean as mean
from random import shuffle
drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index 26bb592..20a2c1c 100644
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -39,6 +39,7 @@
======================= =============================================
:func:`mean` Arithmetic mean ("average") of data.
+:func:`fmean` Fast, floating point arithmetic mean.
:func:`harmonic_mean` Harmonic mean of data.
:func:`median` Median (middle value) of data.
:func:`median_low` Low median of data.
@@ -111,6 +112,23 @@
``mean(data)`` is equivalent to calculating the true population mean μ.
+.. function:: fmean(data)
+
+ Convert *data* to floats and compute the arithmetic mean.
+
+ This runs faster than the :func:`mean` function and it always returns a
+ :class:`float`. The result is highly accurate but not as perfect as
+ :func:`mean`. If the input dataset is empty, raises a
+ :exc:`StatisticsError`.
+
+ .. doctest::
+
+ >>> fmean([3.5, 4.0, 5.25])
+ 4.25
+
+ .. versionadded:: 3.8
+
+
.. function:: harmonic_mean(data)
Return the harmonic mean of *data*, a sequence or iterator of
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 2f759f3..bf7300d 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -254,6 +254,15 @@
post-handshake authentication.
(Contributed by Christian Heimes in :issue:`34670`.)
+
+statistics
+----------
+
+Added :func:`statistics.fmean` as a faster, floating point variant of
+:func:`statistics.mean()`. (Contributed by Raymond Hettinger and
+Steven D'Aprano in :issue:`35904`.)
+
+
tokenize
--------