classification
Title: int() docstring - unclear what number is
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder: Documentation for int constructor mentions __int__ but not __trunc__
View: 26701
Assigned To: docs@python Nosy List: and, cheryl.sabella, cvrebert, docs@python, eryksun, ezio.melotti, martin.panter, rhettinger, zach.ware
Priority: normal Keywords:

Created on 2014-05-30 08:58 by and, last changed 2018-03-16 11:24 by cheryl.sabella. This issue is now closed.

Messages (6)
msg219379 - (view) Author: Dmitry Andreychuk (and) Date: 2014-05-30 08:58
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.
msg219530 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-06-01 22:38
> 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.
msg219551 - (view) Author: Dmitry Andreychuk (and) Date: 2014-06-02 06:49
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.
msg219552 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2014-06-02 07:34
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.
msg313908 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-03-15 19:14
Is this superseded by issue 26701?
msg313941 - (view) Author: Dmitry Andreychuk (and) Date: 2018-03-16 08:51
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.
History
Date User Action Args
2018-03-16 11:24:53cheryl.sabellasetstatus: open -> closed
superseder: Documentation for int constructor mentions __int__ but not __trunc__
resolution: duplicate
stage: resolved
2018-03-16 08:51:59andsetmessages: + msg313941
2018-03-15 19:14:01cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg313908
2014-08-29 03:35:54cvrebertsetnosy: + cvrebert
2014-08-28 02:29:14martin.pantersetnosy: + martin.panter
2014-06-02 07:34:12eryksunsetnosy: + eryksun
messages: + msg219552
2014-06-02 06:49:05andsetmessages: + msg219551
2014-06-01 22:38:44rhettingersetnosy: + rhettinger
messages: + msg219530
2014-05-31 16:23:47ezio.melottisetnosy: + ezio.melotti, zach.ware

type: enhancement
versions: - Python 3.1, Python 3.2, Python 3.3
2014-05-30 08:58:55andcreate