[issue21611] int() docstring - unclear what number is
New submission from Dmitry Andreychuk: https://docs.python.org/3.4/library/functions.html?highlight=int#int The docstring for int() function has these sentences: "If x is a number, return x.__int__()." "If x is not a number or if base is given..." Unfortunately the docstring doesn't describe how the function decides if x is a number or not. After searching and experimenting I came to conclusion that it is the presence of x.__int__() method makes int() treat x as a number. But I'm not sure it's a precise requirement or just something that happens to work with current implementation. I think there should be a precise definition of what is considered to be a number there. ---------- assignee: docs@python components: Documentation messages: 219379 nosy: and, docs@python priority: normal severity: normal status: open title: int() docstring - unclear what number is versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti, zach.ware type: -> enhancement versions: -Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Raymond Hettinger added the comment:
I think there should be a precise definition of what is considered to be a number there.
Sometimes "precise" definitions make the docs harder to use rather than easier. It is the goal of these docs to basically tell what int() does, not to provide a spec for it. For most users for the past 20+ years, what we already have was sufficient for them to understand that int('42') returned the integer 42 and that int('xyz') did not have a valid interpretation as an integer. FWIW, there are other parts of the docs that do have more precise specs about precisely specifies what can go in floats, identifiers, etc. Those parts of the docs are rarely used or read however, because what we have gets the job done reasonably well. For comparison look at the docs in other languages where the descriptions tend to be more much pithy, leaving intelligent people to fill in the blanks in a reasonable way. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Dmitry Andreychuk added the comment: Now I see that my message may look like a suggestion to add an encyclopedic definition of number there. Sorry. Actually I was talking about requirements for user-defined types to make them work with int(). Something like: "If x has __int__() method return x.__int__(). Else x must be a string, bytes, or bytearray...". After reading the docstring I was like: Should I just define __int__() for my class to work with int() or maybe int() uses isintance() and my class has also to inherit from numbers.Number? But maybe It's just me and it's clear for everyone else. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
eryksun added the comment: The constructor tries __trunc__ (truncate toward 0) if __int__ isn't defined. If __trunc__ doesn't return an instance of int, it calls the intermediate result's __int__ method. In terms of the numbers ABCs, numbers.Real requires __trunc__, which should return a numbers.Integral, which requires __int__. The special methods __trunc__, __floor__, and __ceil__ aren't documented in the language reference. They're mentioned briefly in the docs for the math functions trunc, floor, and ceil. ---------- nosy: +eryksun _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- nosy: +vadmium _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Changes by Chris Rebert <pybugs@rebertia.com>: ---------- nosy: +cvrebert _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21611> _______________________________________
Cheryl Sabella <chekat2@gmail.com> added the comment: Is this superseded by issue 26701? ---------- nosy: +csabella _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue21611> _______________________________________
Dmitry Andreychuk <and.dmitry@gmail.com> added the comment: I created this issue almost 4 years ago. Looking at it now, I think that I was asking too much of that docstring. I believe it's current version quite sufficient. I would close the issue, but I'm not sure if it's up to me to decide. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue21611> _______________________________________
Change by Cheryl Sabella <chekat2@gmail.com>: ---------- resolution: -> duplicate stage: -> resolved status: open -> closed superseder: -> Documentation for int constructor mentions __int__ but not __trunc__ _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue21611> _______________________________________
participants (7)
-
Cheryl Sabella -
Chris Rebert
-
Dmitry Andreychuk
-
eryksun
-
Ezio Melotti
-
Martin Panter
-
Raymond Hettinger