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 (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
