[issue29161] random.SystemRandom(seed) documentation issue

[Gary E. Miller]

Gary E. Miller added the comment:

> The docs are clear that System Random uses os.urandom() for creating random 
> numbers, that there is not state, that sequences aren't reproducible, and 
> that seed method has no effect and is ignored.  

Agreed, but not relevant. I have anecdotal proof that the docs are not clear to 
a number of talented Python programmers that the seed parameter is not used.  
Or that the seed parameter is passed to the seed() method (and thus unused).

Disappointing...

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Raymond Hettinger]

Raymond Hettinger added the comment:

Thank you for the submission.  I respect what you're trying to do, but disagree 
that there is any issue here.   The docs are clear that System Random uses 
os.urandom() for creating random numbers, that there is not state, that 
sequences aren't reproducible, and that seed method has no effect and is 
ignored.  Also, the square brackets on the seed argument is our traditional way 
of saying that an argument is optional.

Apologies, but I'm going to close this.  IMO, the proposed wording is less 
clear and doesn't really help if someone is already misunderstanding what 
SystemRandom is all about and is imagining that the "seed" argument has some 
effect when the seed method is documented as being ignored.

--
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Gary E. Miller]

Gary E. Miller added the comment:

Is there a better place to submit documentation problems to?  After my 
programming team spends a lot of valuable time figuring what the Python doc 
failed to mention I would like this knowledge to be put to good use by others.  
Paying it forward if you will.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Gary E. Miller]

Gary E. Miller added the comment:

> > why have an ignored parameter that is not plainly documented as ignored.

> Because it improves the substitutability of one RNG for another (i.e. the 
> same reason that we even have a seed() method).

I understand why it the parameter it there.  I think the parameter should stay 
there.  I am all for orthogonal functions.  It just needs to be documented that 
the parameter is ignored by SystemRandom().

Programmers are being misled by the online documentation and adding a seed 
parameter when it does nothing.

I should not have to read the library code to find out that a parameter is 
ignored.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Raymond Hettinger]

Raymond Hettinger added the comment:

> why have an ignored parameter that is not plainly documented as ignored.

Because it improves the substitutability of one RNG for another (i.e. the same 
reason that we even have a seed() method).

--
priority: normal -> low
resolution:  -> not a bug

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Gary E. Miller]

Gary E. Miller added the comment:

I would change:

"Accordingly, the seed() method has no effect and is ignored."

To:

"Accordingly, the optional seed parameter and the seed() method have no effect 
and are ignored."

It was not obvious to me that the seed paramrter got passed to the seed() 
method and was then ignored.  After all, why have an ignored parameter that is 
not plainly documented as ignored.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Raymond Hettinger]

Raymond Hettinger added the comment:

>From the docs at 
>https://docs.python.org/3/library/random.html#alternative-generator :

"""
class random.SystemRandom([seed])
Class that uses the os.urandom() function for generating random numbers from 
sources provided by the operating system. Not available on all systems. Does 
not rely on software state, and sequences are not reproducible. Accordingly, 
the seed() method has no effect and is ignored. The getstate() and setstate() 
methods raise NotImplementedError if called.
"""

What is it that you think needs to be added or changed?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee:  -> rhettinger
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue29161] random.SystemRandom(seed) documentation issue

[Gary E. Miller]

New submission from Gary E. Miller:

The man page for random.SystemRandom([seed]]) fails to mention that the 
parameter 'seed' is never used.  This should be prominent in the documentation. 
 I have found several cases where a seed was provided to SystemRandom().

https://docs.python.org/2.7/library/random.html?highlight=systemrandom

Present in all versions of Python docs that I could find.

--
components: Library (Lib)
messages: 284678
nosy: gem
priority: normal
severity: normal
status: open
title: random.SystemRandom(seed) documentation issue
type: behavior
versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com