Improve docstrings

python · rhettinger · May 4, 2024 · Apr 5, 2024 · Apr 5, 2024 · Apr 6, 2024
commit 37a89553ae953ee4598c3dbb4feffabd8654d045
diff --git a/Doc/library/statistics.rst b/Doc/library/statistics.rst
@@ -316,8 +316,11 @@ However, for reading convenience, most of the examples show sorted sequences.
    Return a function that makes a random selection from the estimated
    probability density function produced by ``kde(data, h, kernel)``.
 
-   For reproducible results, set *seed* to an integer, float, str, or bytes.
-   Not thread-safe without a lock around calls.
+   Providing a *seed* allows reproducible selections within a single
+   thread (or with a lock around calls).  In the future, the selection
+   method for the *parabolic*, *quartic*, and *triweight* kernels may be
+   replaced with faster algorithms that give different results.  The
+   seed may be an integer, float, str, or bytes.
 
    A :exc:`StatisticsError` will be raised if the *data* sequence is empty.
 

diff --git a/Lib/statistics.py b/Lib/statistics.py
@@ -1724,7 +1724,7 @@ def f_inv(y):
 
 def _simple_s_curve(power):
     "S-curve that crosses (0, -1), (1/2, 0), (1, 1)."
-    # Approximates the invcdf for kernels with support: -1 <= x <= 1.
+    # Approximates the inverse CDF for kernels with support: -1 < x < 1.
     return lambda p: ((2 * p) ** power - 1
                       if p <= 1/2 else
                       1 - (2 - 2*p) ** power)
@@ -1762,12 +1762,23 @@ def _simple_s_curve(power):
 
 def kde_random(data, h, kernel='normal', *, seed=None):
     """Return a function that makes a random selection from the estimated
-    probability density function created by:  kde(data, h, kernel)
+    probability density function created by kde(data, h, kernel).
 
-    For reproducible results, set *seed* to an integer, float, str, or bytes.
-    Not thread-safe without a lock around calls.
+    Providing a *seed* allows reproducible selections within a single
+    thread (or with a lock around calls).  In the future, the selection
+    method for the parabolic, quartic, and triweight kernels may be
+    replaced with faster algorithms that give different results.
+    The seed may be an integer, float, str, or bytes.
 
-    A StatisticsError will be raised if the data sequence is empty.
+    A StatisticsError will be raised if the *data* sequence is empty.
+
+    Example:
+
+    >>> data = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2]
+    >>> rand = kde_random(sample, h=1.5, seed=8675309)
+    >>> new_selections = [rand() for i in range(10)]
+    >>> [round(x, 1) for x in new_selections]
+    [0.7, 6.2, 1.2, 6.9, 7.0, 1.8, 2.5, -0.5, -1.8, 5.6]
 
     """
     n = len(data)