[issue20216] Misleading docs for sha1, sha256, sha512 modules

[Vajrasky Kok]

New submission from Vajrasky Kok:

Misleading doc number 1:

>>> import _sha1
>>> _sha1.sha1.__doc__
'Return a new SHA1 hash object; optionally initialized with a string.'
>>> _sha1.sha1('cutecat')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Unicode-objects must be encoded before hashing
>>> _sha1.sha1(b'cutecat')
<_sha1.sha1 object at 0x7f800f669e00>
>>> _sha1.sha1(string=b'cutecat')
<_sha1.sha1 object at 0x7f800f669e00>

I don't think we can change the unfortunate keyword 'string'. But at least we must fix the doc.

Misleading doc number 2:

>>> import _sha1
>>> cutecat = _sha1.sha1(b'cutecat')
>>> cutecat.update.__doc__
"Update this hash object's state with the provided string."
>>> cutecat.update('bonobo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Unicode-objects must be encoded before hashing
>>> cutecat.update(b'bonobo')

Misleading doc number 3:

>>> cutecat.hexdigest()
'a5fbd19140a72992224b2469c4f4d8d6d4aff3e7'
>>> cutecat.hexdigest.__doc__
'Return the digest value as a string of hexadecimal digits.'
>>> cutecat.digest()
b'\xa5\xfb\xd1\x91@\xa7)\x92"K$i\xc4\xf4\xd8\xd6\xd4\xaf\xf3\xe7'
>>> cutecat.digest.__doc__
'Return the digest value as a string of binary data.'

"a string of binary data" in my mind is something like this: '\xa5\xfb\xd1\x91@\xa7)\x92"K$i\xc4\xf4\xd8\xd6\xd4\xaf\xf3\xe7' not b'\xa5\xfb\xd1\x91@\xa7)\x92"K$i\xc4\xf4\xd8\xd6\xd4\xaf\xf3\xe7'.

Provided the patch to fix the doc.

----------
components: Extension Modules
files: fix_doc_sha_module.patch
keywords: patch
messages: 207822
nosy: christian.heimes, vajrasky
priority: normal
severity: normal
status: open
title: Misleading docs for sha1, sha256, sha512 modules
type: behavior
versions: Python 3.3, Python 3.4
Added file: http://bugs.python.org/file33398/fix_doc_sha_module.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue20216>
_______________________________________