classification
Title: Misleading docs for sha1, sha256, sha512, md5 modules
Type: behavior Stage: resolved
Components: Extension Modules Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Rosuav, cheryl.sabella, christian.heimes, r.david.murray, serhiy.storchaka, vajrasky, vstinner
Priority: normal Keywords: patch

Created on 2014-01-10 02:21 by vajrasky, last changed 2018-10-28 17:20 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
fix_doc_sha_module.patch vajrasky, 2014-01-10 02:21 review
fix_doc_sha_module_v2.patch vajrasky, 2014-01-10 03:21 review
Pull Requests
URL Status Linked Edit
PR 9873 merged thatiparthy, 2018-10-14 16:25
PR 9971 merged miss-islington, 2018-10-19 17:43
PR 10183 merged serhiy.storchaka, 2018-10-28 16:57
Messages (9)
msg207822 - (view) Author: Vajrasky Kok (vajrasky) * Date: 2014-01-10 02:21
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.
msg207830 - (view) Author: Vajrasky Kok (vajrasky) * Date: 2014-01-10 03:21
Added md5 module to this ticket.
msg252766 - (view) Author: Chris Angelico (Rosuav) * Date: 2015-10-11 05:49
"bytes of binary data" seems redundant - how about just "byte string"? Otherwise, sure.
msg252815 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-10-11 15:27
'bytes of binary data' should be 'bytes object', which is what is used in the ReST documentation.  Otherwise the patch looks good to me.
msg327445 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python triager) Date: 2018-10-10 00:00
@vajrasky, Would you be interested in converting your patch to a GitHub pull request?  Thanks!
msg328079 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-19 23:20
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) 
https://github.com/python/cpython/commit/f192aeb95a139ede74d69e39c046c498ff288a37
msg328080 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-19 23:21
New changeset 23efe77acf0dce513d7b7cab5523c061bb006b60 by Victor Stinner (Miss Islington (bot)) in branch '3.7':
bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873) (GH-9971)
https://github.com/python/cpython/commit/23efe77acf0dce513d7b7cab5523c061bb006b60
msg328081 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2018-10-19 23:25
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 ;-)
msg328713 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-10-28 17:20
New changeset f29bded3d3b0de63b45819eec292f5007c0cd3cf by Serhiy Storchaka in branch '3.6':
[3.6] bpo-20216: Correct docstrings of digest() methods in hashlib. (GH-9873). (GH-10183)
https://github.com/python/cpython/commit/f29bded3d3b0de63b45819eec292f5007c0cd3cf
History
Date User Action Args
2018-10-28 17:20:34serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg328713
2018-10-28 16:57:43serhiy.storchakasetpull_requests: + pull_request9506
2018-10-19 23:25:54vstinnersetstatus: open -> closed
versions: + Python 3.7
messages: + msg328081

resolution: fixed
stage: patch review -> resolved
2018-10-19 23:21:01vstinnersetmessages: + msg328080
2018-10-19 23:20:24vstinnersetnosy: + vstinner
messages: + msg328079
2018-10-19 17:43:07miss-islingtonsetpull_requests: + pull_request9316
2018-10-14 16:25:14thatiparthysetstage: needs patch -> patch review
pull_requests: + pull_request9238
2018-10-10 00:00:27cheryl.sabellasetversions: + Python 3.8, - Python 3.4, Python 3.5, Python 3.6
nosy: + cheryl.sabella

messages: + msg327445

stage: needs patch
2015-10-11 15:27:04r.david.murraysetnosy: + r.david.murray

messages: + msg252815
versions: + Python 3.5, Python 3.6, - Python 3.3
2015-10-11 05:49:51Rosuavsetnosy: + Rosuav
messages: + msg252766
2014-01-10 03:21:49vajraskysetfiles: + fix_doc_sha_module_v2.patch

messages: + msg207830
title: Misleading docs for sha1, sha256, sha512 modules -> Misleading docs for sha1, sha256, sha512, md5 modules
2014-01-10 02:21:30vajraskycreate