classification
Title: Minor typo in the docs for struct.unpack
Type: Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: martin.panter Nosy List: Antony.Lee, baji, docs@python, georg.brandl, mark.dickinson, martin.panter, meador.inge, pitrou, python-dev, rhettinger, serhiy.storchaka, terry.reedy, vstinner
Priority: normal Keywords: patch

Created on 2016-03-11 02:45 by Antony.Lee, last changed 2016-04-16 02:33 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
issue26535.diff baji, 2016-03-11 10:29 review
struct-size.v2.patch martin.panter, 2016-04-15 06:00 review
Messages (13)
msg261538 - (view) Author: Antony Lee (Antony.Lee) * Date: 2016-03-11 02:45
The docstring of struct.unpack currently reads

Unpack from the buffer buffer (presumably packed by pack(fmt, ...)) according to the format string fmt. The result is a tuple even if it contains exactly one item. The buffer must contain exactly the amount of data required by the format (len(bytes) must equal calcsize(fmt)).

It should probably read "len(buffer) must equal calcsize(fmt)".
msg261545 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-03-11 07:04
I would remove "len(bytes) must equal " at all. len() can return a value not equal to the number of bytes contained in the buffer (e.g. for array('I')).
msg261546 - (view) Author: Antony Lee (Antony.Lee) * Date: 2016-03-11 07:36
I think mentioning calcsize is still helpful, so perhaps something like
"The buffer must contain exactly as many bytes (I think this is clearer than "the amount of data") as required by the format (this number can be obtained as `struct.calcsize(fmt)`)"?  (and likewise for "unpack_from" and "iter_unpack").
msg261548 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2016-03-11 07:59
That sounds good to me. Maybe without so many parentheses :)
msg261553 - (view) Author: Baji (baji) * Date: 2016-03-11 10:11
Modified as suggested in the comments
msg261556 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-03-11 10:25
Issue title: "Minor typo in the docs for struct.unpack"

I can say the same on issue26535.diff: there is a typo ;)
msg261631 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-03-12 01:50
The patch looks good to me, though it should be applied to all three unpack functions and Struct methods, and the doc strings (struct.unpack.__doc__ etc).

An alternative wording is already used for struct.iter_unpack(): “the buffer’s size in bytes”. Maybe that is slightly clearer, but it’s no big deal.
msg261679 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-03-13 07:14
The proposed wording looks fine.
msg263445 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-15 04:47
Here is a new patch:

* Use “The buffer’s size in bytes” wording
* Avoid brackets inside brackets
* Fix the three unpack functions and corresponding methods
* Also fix doc strings
msg263450 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-04-15 05:42
Seems you forgot to send a patch.
msg263451 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-15 06:00
Indeed, let me try again
msg263456 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-04-15 07:24
LGTM.
msg263531 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-04-15 23:45
New changeset 7889fcb0697b by Martin Panter in branch '3.5':
Issue #26535: Correct docs regarding the struct buffer size
https://hg.python.org/cpython/rev/7889fcb0697b

New changeset 39dc2f39373d by Martin Panter in branch 'default':
Issue #26535: Merge struct doc from 3.5
https://hg.python.org/cpython/rev/39dc2f39373d
History
Date User Action Args
2016-04-16 02:33:17martin.pantersetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2016-04-15 23:45:32python-devsetnosy: + python-dev
messages: + msg263531
2016-04-15 07:24:46serhiy.storchakasetassignee: docs@python -> martin.panter
messages: + msg263456
stage: patch review -> commit review
2016-04-15 06:00:59martin.pantersetfiles: + struct-size.v2.patch

messages: + msg263451
2016-04-15 05:42:26serhiy.storchakasetmessages: + msg263450
2016-04-15 04:47:02martin.pantersetmessages: + msg263445
stage: needs patch -> patch review
2016-03-13 07:23:07serhiy.storchakasetstage: patch review -> needs patch
2016-03-13 07:22:27serhiy.storchakasetnosy: + pitrou
2016-03-13 07:14:56rhettingersetnosy: + rhettinger
messages: + msg261679
2016-03-12 01:50:04martin.pantersetstage: needs patch -> patch review
messages: + msg261631
versions: + Python 3.5
2016-03-12 00:28:18terry.reedysetnosy: + terry.reedy
2016-03-11 10:29:24bajisetfiles: - issue26535.diff
2016-03-11 10:29:10bajisetfiles: + issue26535.diff
2016-03-11 10:25:19vstinnersetnosy: + vstinner
messages: + msg261556
2016-03-11 10:11:48bajisetfiles: + issue26535.diff

nosy: + baji
messages: + msg261553

keywords: + patch
2016-03-11 08:01:07serhiy.storchakasetstage: needs patch
2016-03-11 07:59:07georg.brandlsetnosy: + georg.brandl
messages: + msg261548
2016-03-11 07:36:31Antony.Leesetmessages: + msg261546
2016-03-11 07:04:35serhiy.storchakasetnosy: + mark.dickinson, meador.inge
2016-03-11 07:04:06serhiy.storchakasetnosy: + serhiy.storchaka, martin.panter
messages: + msg261545
2016-03-11 02:45:19Antony.Leecreate