bpo-27181: Add statistics.geometric_mean() (GH-12638)
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
index 1d52d98..8bb2bdf 100644
--- a/Doc/library/statistics.rst
+++ b/Doc/library/statistics.rst
@@ -40,6 +40,7 @@
======================= ===============================================================
:func:`mean` Arithmetic mean ("average") of data.
:func:`fmean` Fast, floating point arithmetic mean.
+:func:`geometric_mean` Geometric mean of data.
:func:`harmonic_mean` Harmonic mean of data.
:func:`median` Median (middle value) of data.
:func:`median_low` Low median of data.
@@ -130,6 +131,24 @@
.. versionadded:: 3.8
+.. function:: geometric_mean(data)
+
+ Convert *data* to floats and compute the geometric mean.
+
+ Raises a :exc:`StatisticsError` if the input dataset is empty,
+ if it contains a zero, or if it contains a negative value.
+
+ No special efforts are made to achieve exact results.
+ (However, this may change in the future.)
+
+ .. doctest::
+
+ >>> round(geometric_mean([54, 24, 36]), 9)
+ 36.0
+
+ .. versionadded:: 3.8
+
+
.. function:: harmonic_mean(data)
Return the harmonic mean of *data*, a sequence or iterator of