PEP 504: expand ensure_repeatable docstring

pep-0504.txt

@@ -61,7 +61,18 @@ API behaviour as existed in previous Python versions (aside from the
 additional level of indirection)::
 
     def ensure_repeatable():
-        """Switch to using random.Random() for the module level APIs"""
+        """Switch to using random.Random() for the module level APIs
+
+        This switches the default RNG instance from the crytographically
+        secure random.SystemRandom() to the deterministic random.Random(),
+        enabling the seed(), getstate() and setstate() operations. This means
+        a particular random scenario can be replayed later by providing the
+        same seed value or restoring a previously saved state.
+
+        NOTE: Libraries implementing security sensitive operations should
+        always explicitly use random.SystemRandom() or os.urandom in order to
+        correctly handle applications that call this function.
+        """
         if not isinstance(_inst, Random):
             _inst = random.Random()