[Python-bugs-list] [Bug #125919] random.shuffle isn't documented

[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: random.shuffle isn't documented

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.


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