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

[Ezio Melotti]

Hi,

On Sun, May 11, 2014 at 12:35 AM, Raymond Hettinger
<raymond.hettinger at gmail.com> wrote:
>
> 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

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".