[Python-bugs-list] [Bug #125919] docs for random, whrandom too complex

[noreply@sourceforge.net]

Bug #125919, was updated on 2000-Dec-15 11:02
Here is a current snapshot of the bug.

Project: Python
Category: Documentation
Status: Open
Resolution: None
Bug Group: None
Priority: 7
Submitted by: tim_one
Assigned to : fdrake
Summary: docs for random, whrandom too complex

Details: From the docstring:

"""
x, random=random.random -> shuffle list x in place; return
None.

Optional arg random is a 0-argument function returning a
random float in [0.0, 1.0); by default, the standard
random.random.

Note that for even rather small len(x), the total number
of permutations of x is larger than the period of most
random number generators; this implies that "most"
permutations of a long sequence can never be generated.
"""

I would have added this myself to the docs, but don't understand the
structure of the docs; e.g., I always thought whrandom was an internal
implementation detail for random that wasn't meant to be exposed on its
own, and the "Random Number Generator Interface" appears to be a half-baked
Grand Generalization that was abandoned the day after it got dreamt up.

Suggest the docs in this area would be much clearer if they documented the
random module on its own, and dropped the sections on whrandom and the
RNGI.  Python's randomization facilities are too meager to merit so much
complexity.


Follow-Ups:

Date: 2001-Jan-15 19:35
By: tim_one

Comment:
No, the docs mean [0,1).  People differ as to whether they favor [0,1) or
(0,1), but Python picked [0,1) a long time ago.  Doesn't mean you're ever
going to see a 0, but does mean it won't be considered a bug if you do see
one.  Python's implementation of Wichmann-Hill actually ends with a mod
operation, so a 0 return isn't impossible "in theory" (although on machines
using proper IEEE-754 double arithmetic, I don't believe the hardware can
actually generate a 0 from the sequence of operations Python performs).
-------------------------------------------------------

Date: 2001-Jan-15 18:52
By: randrews

Comment:
Possible related typo from Python Library Reference section 5.3.1 on The
Random Number Generator Interface:

random () 
     Returns the next random floating point number in the range [0.0 ...
1.0). 

Should the range read (0.0 ... 1.0) instead of [0.0 ... 1.0)?
-------------------------------------------------------

Date: 2000-Dec-15 11:16
By: fdrake

Comment:
random.shuffle() was documented before I got the bug notice for this one!

Your other comments still need to be dealt with, so I'll leave this open,
but re-title it.
-------------------------------------------------------

For detailed info, follow this link:
http://sourceforge.net/bugs/?func=detailbug&bug_id=125919&group_id=5470