Clarify that the signed number convertors to PyArg_ParseTuple... *do* overflow checking

[anntzer]

BPO	33033
Nosy	@serhiy-storchaka, @anntzer

^{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 = None
created_at = <Date 2018-03-09.00:47:58.411>
labels = ['docs']
title = 'Clarify that the signed number convertors to PyArg_ParseTuple... *do* overflow checking'
updated_at = <Date 2018-03-09.09:34:18.737>
user = 'https://github.com/anntzer'

bugs.python.org fields:

activity = <Date 2018-03-09.09:34:18.737>
actor = 'Antony.Lee'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-03-09.00:47:58.411>
creator = 'Antony.Lee'
dependencies = []
files = []
hgrepos = []
issue_num = 33033
keywords = []
message_count = 3.0
messages = ['313471', '313474', '313478']
nosy_count = 3.0
nosy_names = ['docs@python', 'serhiy.storchaka', 'Antony.Lee']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue33033'
versions = ['Python 3.6']

Linked PRs

• gh-77214: Update outdated documentation for numeric PyArg_Parse formats #128454
• [3.13] gh-77214: Update outdated documentation for numeric PyArg_Parse formats (GH-128454) #128538
• [3.12] gh-77214: Update outdated documentation for numeric PyArg_Parse formats (GH-128454) #128539

[anntzer]

At https://docs.python.org/3/c-api/arg.html#numbers, it is explicitly documented that the unsigned number convertors do not perform overflow checking. Implicitly, this suggests that the signed convertors *do* perform overflow checking, which they indeed do; but it would be nice to document this behavior explicitly (as overflow checking is not always expected of C-level functions).

[serhiy-storchaka]

This doesn't look a good idea to me. It is implied that all checks are performed. For example it is implied that an error will be raised if the argument is of wrong type. I think that adding "with overflow checking" to every converting from a Python integer will just clutter the documentation.

[anntzer]

One could just add, immediately below the "Numbers" section, something like: "The signed convertors (b, h, i, ...) perform overflow checking. The unsigned convertors (B, H, I, ...) do not." That would actually be shorter than the current version, which repeats the second half for each unsigned entry...

[serhiy-storchaka]

It is worse -- right after all format units there is a paragraph which states that no proper range checking is done:

It is possible to pass "long" integers (integers whose value exceeds the
platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value (actually, the semantics are inherited from downcasts
in C --- your mileage may vary).

It is likely dates to the times when there were separate types int and long and conversion from long to int truncated value. This is absolutely false now.

I think that we should add a paragraph at the beginning of the "Numbers" section (similar to the paragraph at the beginning of the "Strings and buffers" section) which clarifies general rules: what types are accepted, what conversions are performed and how overflow is handled.