Hi, On Sun, May 11, 2014 at 12:35 AM, Raymond Hettinger <raymond.hettin...@gmail.com> wrote: > > On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gay...@gmail.com> 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. > > > Raymond > > > 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". _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com