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

On May 10, 2014, at 6:10 PM, Nick Coghlan wrote:

On 11 May 2014 07:37, "Raymond Hettinger" wrote:

...

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

I completely agree with Alex, Antoine, and Nick here. I’m both an experienced Python programmer and someone who is generally aware of the security implications of various parts of software. However I appreciate when I look at documentation that explicitly calls out the ways I might screw it up, especially in a security sensitive context, but I appreciate it any context really. ----------------- Donald Stufft PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA