Misleading docs for sha1, sha256, sha512, md5 modules

[vajrasky]

BPO	20216
Nosy	@vstinner, @tiran, @bitdancer, @Rosuav, @serhiy-storchaka, @vajrasky, @csabella
PRs	Closes bpo-20216: Correct a misleading docstring #9873 [3.7] bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873) #9971 [3.6] bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873). #10183
Files	fix_doc_sha_module.patch fix_doc_sha_module_v2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-10-19.23:25:54.364>
created_at = <Date 2014-01-10.02:21:30.519>
labels = ['extension-modules', '3.8', 'type-bug', '3.7']
title = 'Misleading docs for sha1, sha256, sha512, md5 modules'
updated_at = <Date 2018-10-28.17:20:34.405>
user = 'https://github.com/vajrasky'

bugs.python.org fields:

activity = <Date 2018-10-28.17:20:34.405>
actor = 'serhiy.storchaka'
assignee = 'none'
closed = True
closed_date = <Date 2018-10-19.23:25:54.364>
closer = 'vstinner'
components = ['Extension Modules']
creation = <Date 2014-01-10.02:21:30.519>
creator = 'vajrasky'
dependencies = []
files = ['33398', '33399']
hgrepos = []
issue_num = 20216
keywords = ['patch']
message_count = 9.0
messages = ['207822', '207830', '252766', '252815', '327445', '328079', '328080', '328081', '328713']
nosy_count = 7.0
nosy_names = ['vstinner', 'christian.heimes', 'r.david.murray', 'Rosuav', 'serhiy.storchaka', 'vajrasky', 'cheryl.sabella']
pr_nums = ['9873', '9971', '10183']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20216'
versions = ['Python 3.7', 'Python 3.8']

[vajrasky]

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.

[vajrasky]

Added md5 module to this ticket.

[Rosuav]

"bytes of binary data" seems redundant - how about just "byte string"? Otherwise, sure.

[bitdancer]

'bytes of binary data' should be 'bytes object', which is what is used in the ReST documentation. Otherwise the patch looks good to me.

[csabella]

@vajrasky, Would you be interested in converting your patch to a GitHub pull request? Thanks!

[vstinner]

Strange, no bot noticed that a change has been merged into the master branch:

bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873)
f192aeb

[vstinner]

New changeset 23efe77 by Victor Stinner (Miss Islington (bot)) in branch '3.7':
bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873) (GH-9971)
23efe77

[vstinner]

Thanks Vajrasky Kok for the initial patch and thanks Srinivas Thatiparthy (శ్రీనివాస్ తాటిపర్తి) for the PR!

Small note: Srinivas, maybe next time you convert a patch written by someone else to a PR, just mention the name of the initial author ;-)

[serhiy-storchaka]

New changeset f29bded by Serhiy Storchaka in branch '3.6':
[3.6] bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873). (GH-10183)
f29bded