int.to_bytes(): docstring is not precise

[socketpair]

BPO	27622
Nosy	@bitdancer, @methane, @socketpair, @serhiy-storchaka

^{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 2016-07-26.18:34:56.983>
created_at = <Date 2016-07-26.06:20:37.886>
labels = ['type-feature', 'library', 'docs']
title = 'int.to_bytes(): docstring is not precise'
updated_at = <Date 2016-07-26.18:34:56.982>
user = 'https://github.com/socketpair'

bugs.python.org fields:

activity = <Date 2016-07-26.18:34:56.982>
actor = 'socketpair'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-07-26.18:34:56.983>
closer = 'socketpair'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2016-07-26.06:20:37.886>
creator = 'socketpair'
dependencies = []
files = []
hgrepos = []
issue_num = 27622
keywords = []
message_count = 11.0
messages = ['271327', '271328', '271333', '271334', '271336', '271337', '271338', '271339', '271340', '271382', '271402']
nosy_count = 5.0
nosy_names = ['r.david.murray', 'methane', 'docs@python', 'socketpair', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue27622'
versions = ['Python 3.6']

[socketpair]

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

[serhiy-storchaka]

What is wrong?

[socketpair]

The docstring does not say, that positive values also may raise OverflowError if it can not fit into (byte_count * 8) - 1 bits.

[socketpair]

I mean when signed=True

[methane]

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)

[socketpair]

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.

[socketpair]

So, in order to make documentation consistent, either new text should be added, or last phraze removed. That's what I think.

[methane]

@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.
---

[serhiy-storchaka]

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?

[bitdancer]

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).

[socketpair]

Ok. This is minor fix, I will not fight for my point of view :)