On 11 May 2014 07:37, "Raymond Hettinger" <raymond.hettinger@gmail.com> wrote:
>
>
> On May 10, 2014, at 2:18 PM, Alex Gaynor <alex.gaynor@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.

That assumption has changed somewhat, as many users are now getting their education in programming (and how computers work in general) from introductory community workshops and the Python documentation.

This means that writing our docs based on the assumption that the reader is already going to be a professional programmer is no longer adequate. This is especially essential in security related areas, as even professional programmers usually aren't sufficiently paranoid about all the ways their software can be attacked.

As Alex notes, the short term way to eliminate the duplication here is to keep the security warnings and drop the material from the introductory paragraph, not go back to expecting readers to have already been alerted to randomness related cryptographic security issues in some other context. Readers that are already familiar with the security concerns will hopefully recognise that they're not a Python specific problem (and may even be appreciative of our attempts to convey the relevant knowledge to a broader audience), while readers that aren't yet aware of them may be more likely to account for them appropriately when writing their software. It's as much about cultivating a more paranoid more mindset in developers in general as it is about the contents of the specific security warning.

A "Security Considerations" section in the module documentation can be a better way to tackle this than trying to jam everything into one warning box, but there should still be a "Here be dragons" warning early on noting that random *is* a potentially security sensitive module in a cryptographic context.