On Sun, May 11, 2014 at 12:35 AM, Raymond Hettinger email@example.com wrote:
On May 10, 2014, at 2:18 PM, Alex Gaynor firstname.lastname@example.org wrote:
I think this change is a considerable usability regression for the documentation. Right now the warnings about CSPRNGs are hidden in the introductory paragraph, which users are likely to skip
In the past couple of years, we've grown an unfortunate tendency to fill the docs with big warning boxes
If the problem is the scary red boxes, http://bugs.python.org/issue13515 still has a patch to make them less intimidating (and some interesting discussion about it).
Best Regards, Ezio Melotti
(the subprocess docs are an example of implicitly communicating that the module is dangerous and unusable).
The preferred form of documentation is to be affirmatively worded, telling how to use a tool correctly and what its known limitations are. We save the warnings for cases of actual danger where otherwise well informed users get tripped-up.
Tim Peters used to be around to articulate the principle that we don't write the docs with the assumption that the users are less bright than we are or that they can't read.
People writing applications that need to be sure should probably have a howto guide. I don't think they are well served by filling the module docs with every possible way a person could make a security mistake).
If you're writing a secure on-line poker game, you really need to know a great deal more about security than the warning message can supply. My understanding is that actual gaming systems use seeded CSPRNGs rather than urandom() because those systems need to be auditable.
P.S. The docs for the random module had a successful 20 year history without the redundant big red warning box, so it is not really correct to say there has been a "considerable usability regression".