[Python-Dev] [Python-checkins] cpython: Remove the redundant and poorly worded warning message.

[Raymond Hettinger]

On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gaynor at 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".


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140510/b5f3ef2e/attachment.html>