classification
Title: int.to_bytes(): docstring is not precise
Type: enhancement Stage:
Components: Documentation, Library (Lib) Versions: Python 3.6
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, inada.naoki, r.david.murray, serhiy.storchaka, socketpair
Priority: normal Keywords:

Created on 2016-07-26 06:20 by socketpair, last changed 2016-07-26 18:34 by socketpair. This issue is now closed.

Messages (11)
msg271327 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 06:20
Docstring says:

The signed keyword-only argument determines whether two's complement is
used to represent the integer.  If signed is False and a negative integer
is given, an OverflowError is raised.

But actually, 

    (130).to_bytes(1, 'big', signed=True)

will also trigger OverflowError
msg271328 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-07-26 06:22
What is wrong?
msg271333 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 06:50
The docstring does not say, that positive values also may raise OverflowError if it can not fit into `(byte_count * 8) - 1` bits.
msg271334 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 06:51
I mean when signed=True
msg271336 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2016-07-26 06:53
docstring says:

The integer is represented using length bytes.  An OverflowError is
raised if the integer is not representable with the given number of
bytes.

(Python 3.5.2)
msg271337 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 06:58
Well. Phrase `If signed is False and a negative integer is given, an OverflowError is raised.` describe onlyhalf of behaviour. It does not explain behaviour when `signed=True` and value is big enough to trigger exception, but not enough to trigger it when signed=False.
msg271338 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 06:59
So, in order to make documentation consistent, either new text should be added, or last phraze removed. That's what I think.
msg271339 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2016-07-26 07:01
@mmarkk

Do you read full docstring?  It's documented very clearly.

---
int.to_bytes(length, byteorder, *, signed=False) -> bytes

Return an array of bytes representing an integer.

The integer is represented using length bytes.  An OverflowError is
raised if the integer is not representable with the given number of
bytes.

The byteorder argument determines the byte order used to represent the
integer.  If byteorder is 'big', the most significant byte is at the
beginning of the byte array.  If byteorder is 'little', the most
significant byte is at the end of the byte array.  To request the native
byte order of the host system, use `sys.byteorder' as the byte order value.

The signed keyword-only argument determines whether two's complement is
used to represent the integer.  If signed is False and a negative integer
is given, an OverflowError is raised.
---
msg271340 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-07-26 07:04
The docstring looks correct to me. The last phrase corresponds to the last paragraph that describes the signed keyword-only argument.

Is there anyone else for whom the docstring looks wrong?
msg271382 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-26 15:47
Looks correct to me as well.  If you can think of a wording that would be clearer, Марк, that would be great, but it shouldn't make the docstring much wordier (we strive for conciseness in docstrings).  That last phrase can't be just removed without omitting an important piece of information (an *additional* time OverflowError can be raised).
msg271402 - (view) Author: Марк Коренберг (socketpair) * Date: 2016-07-26 18:34
Ok. This is minor fix, I will not fight for my point of view :)
History
Date User Action Args
2016-07-26 18:34:56socketpairsetstatus: open -> closed
resolution: rejected
messages: + msg271402
2016-07-26 15:47:18r.david.murraysetmessages: - msg271381
2016-07-26 15:47:10r.david.murraysetmessages: + msg271382
2016-07-26 15:46:11r.david.murraysetnosy: + r.david.murray
messages: + msg271381
2016-07-26 07:04:52serhiy.storchakasetmessages: + msg271340
2016-07-26 07:01:36inada.naokisetmessages: + msg271339
2016-07-26 06:59:59socketpairsetmessages: + msg271338
2016-07-26 06:58:46socketpairsetmessages: + msg271337
2016-07-26 06:53:53inada.naokisetnosy: + inada.naoki
messages: + msg271336
2016-07-26 06:51:37socketpairsetmessages: + msg271334
2016-07-26 06:50:48socketpairsetmessages: + msg271333
2016-07-26 06:22:23serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg271328
2016-07-26 06:20:37socketpaircreate