md5() has been obsolete since 1996. It has no place as the first item in hashlib's list of "guaranteed to be available" hashes, and it doesn't work when Python has been compiled to be FIPS-compliant.

The documentation should be edited to make md5's availability as non-obvious as possible.

The only edit that is needed is for md5 to be documented as unavailable when Python has been compiled in FIPS-compliant mode.  Most of the world does not and will never use that mode.

md5 is still a perfectly good algorithm for many uses and is required for legacy reasons to support the decades of already deployed uses of md5.

Not to mention its continued popularity as a password hash, surpassed only by double-rot13. You've convinced me, it is reasonable to continue to support, nay, recommend md5 for the non-FIPS world. This hash function continues to have raving fans, especially in applications such as hashing data that is either read from or written to disk where the computational and storage cost of using a more modern hash is too severe for the majority of new applications.

The hashlib doc starts with "Warning: Some algorithms have known hash collision weaknesses, see the FAQ at the end" (the "FAQ at the end" is a link to a Wikipedia article). The sentence "Included are the FIPS secure hash algorithms SHA1, SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA’s MD5 algorithm" also conveys the idea that MD5 is not part of the "secure" bunch. The only addition I can think of would be to replace md5 with sha1 in the small example snippet at the beginning.

Taking a second look it is pretty good.

The only other thing that might be worth mentioning explicitly is that the "always present" hashes don't actually use OpenSSL.

"Constructors for hash algorithms that are always present in this module are md5(), sha1(), sha224(), sha256(), sha384(), and sha512(). Additional algorithms may also be available depending upon the OpenSSL library that Python uses on your platform."

The always present hashes do use openssl if the openssl version hashlib was compiled against supports them.  otherwise it falls back to the builtin C implementations.

Attached patch mentioning availability of md5 under FIPS compliance and the use of OpenSSL algorithms when available and altering the initial example to use sha1 instead of md5.

re-tweak treatment of md5 in hashlib docs (the SHA-2 family is currently recommended by http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html)

The looks good to me in general, but I'd suggest to refer to the new algorithms_guaranteed and algorithms_available attributes in the following paragraph:

    +:func:`sha512`. The :func:`md5` is typically available, but will be missing if
    +Python has been compiled in FIPS-compliant mode. If hashlib was compiled with
    +OpenSSL support then additional algorithms may also be available depending
    +upon the OpenSSL library that Python uses on your platform. OpenSSL
    +implementations of the builtin algorithms are used if available.

New changeset 13ea0a1d7dde by Gregory P. Smith in branch 'default':
issue15468 - use sha256 instead of md5 or sha1 in the examples.
https://hg.python.org/cpython/rev/13ea0a1d7dde

New changeset 1cfd627bee05 by Gregory P. Smith in branch 'default':
Clarify that md5 is in the algorithms_guaranteed list despite what
https://hg.python.org/cpython/rev/1cfd627bee05