From: Raymond Hettinger <python@rcn.com>
Date: Mon, 6 Sep 2010 23:36:31 +0000 (+0000)
Subject: Document which part of the random module module are guaranteed.
X-Git-Tag: v3.2a3~408
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=435cb0f23304d57b0cafb2a4449a41150f7fffa9;p=thirdparty%2FPython%2Fcpython.git

Document which part of the random module module are guaranteed.
---

diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index bf89ade3d37f..6ef5d209fcf7 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -270,3 +270,19 @@ Examples of basic usage::
    <http://code.activestate.com/recipes/576707/>`_ for a compatible alternative
    random number generator with a long period and comparatively simple update
    operations.
+
+Notes on Reproducibility
+========================
+
+Sometimes it is useful to be able to reproduce the sequences given by a pseudo
+random number generator.  By re-using a seed value, the same sequence should be
+reproducible from run to run as long as multiple threads are not running.
+
+Most of the random module's algorithms and seeding functions are subject to
+change across Python versions, but two aspects are guaranteed not to change:
+
+* If a new seeding method is added, then a backward compatible seeder will be
+  offered.
+
+* The generator's :meth:`random` method will continue to produce the same
+  sequence when the compatible seeder is given the same seed.
diff --git a/Misc/NEWS b/Misc/NEWS
index 262983b31378..014164ea7d7c 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -13,6 +13,11 @@ Core and Builtins
 Library
 -------
 
+- Updates to the random module:
+
+  * Document which parts of the module are guaranteed to stay the same
+    across versions and which parts are subject to change.
+
 - collections.OrderedDict now supports a new method for repositioning
   keys to either end.