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

[Antoine Pitrou]

On Sat, 10 May 2014 14:35:38 -0700
Raymond Hettinger <raymond.hettinger at gmail.com> wrote:
> 
> 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.

I agree with Alex. It's not about being bright or not, it's about being
*willing* to eat walls of text. However pleasant it may be for some
people to *write* documentation, for most readers (and especially
non-native English readers, who read more slowly and more painfully
than native ones), documentation is a piece of reference that they skim
from, rather than read from start to end like a novel.

So it makes sense to single out useful information. Knowing that
the functions from the random module are not appropriate for
cryptography is (IMO) more important than knowing that

"""Python uses the Mersenne Twister as the core generator. It produces
53-bit precision floats and has a period of 2**19937-1. The underlying
implementation in C is both fast and threadsafe"""

Regards

Antoine.