classification
Title: Doc/c-api/arg.rst: fix documentation of number formats
Type: Stage:
Components: Documentation, Interpreter Core Versions: Python 3.2
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, mark.dickinson, vstinner
Priority: normal Keywords:

Created on 2010-06-09 10:34 by vstinner, last changed 2015-10-14 16:21 by vstinner. This issue is now closed.

Messages (6)
msg107379 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-09 10:34
The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex).

I suppose that the following paragraph is also outdated:

"It is possible to pass "long" integers (integers whose value exceeds the
 platform's :const:`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)."

Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2).
msg107381 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-06-09 10:46
Yes, most of that paragraph is outdated.

We should check exactly what does happen when the "receiving field is too small" (both in practice and in theory).  In C, downcasting to an unsigned type is well-defined and will always reduce modulo 2**<width_of_type>.  The result of downcasting to a signed type is implementation-defined, however;  do we actually do that anywhere?  If so, it would be nice to fix it.
msg107382 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-06-09 10:48
The other variable of interest here is that some integer formats will accept types with an __index__ method, while others won't.  I'm not sure which types fall into each category, right now.
msg178883 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2013-01-03 01:42
Three years later, nobody looks to be interested to work on this part of the documentation, so I'm closing the issue. => read the code, luke! (not the doc...)
msg178922 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-01-03 08:00
It's still a valid bug.
msg253003 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-10-14 16:21
This issue is now 5 years old and it doesn't contain much information. It's more a TODO item, and I'm not more interested to work on it. So I close the issue. If you want to work on the doc, please write a patch ;-)
History
Date User Action Args
2015-10-14 16:21:52vstinnersetstatus: open -> closed

nosy: + vstinner
messages: + msg253003

resolution: out of date
2013-01-03 14:55:38vstinnersetnosy: - vstinner
2013-01-03 08:00:46georg.brandlsetstatus: closed -> open

nosy: + georg.brandl
messages: + msg178922

resolution: fixed -> (no value)
2013-01-03 01:42:06vstinnersetstatus: open -> closed
resolution: fixed
messages: + msg178883
2010-06-09 10:48:47mark.dickinsonsetmessages: + msg107382
2010-06-09 10:46:57mark.dickinsonsetmessages: + msg107381
2010-06-09 10:34:46vstinnercreate