Raymond makes a good point. We mustn't clutter the docs with warnings. People are going to skip warning boxes if they occur too often. The documentation of the hashlib module contains three "note" boxes and one "warning box". That's far too many.

The first "note" box could be moved to "see also". The other two "note" could be removed and their content added to the documentation of update(). The warning box should follow the example of the ssl module and all further security considerations should be moved into a new section.

The Python stdlib documentation is the wrong place to teach users about crypto and security stuff. But in my opinion good documentation should point out that something is dangerous or may lure a user into false sense of security.

Perhaps I should start a howto with common security-related issues in Python software for 3.5.