int() docstring - unclear what number is

[and]

BPO	21611
Nosy	@rhettinger, @ezio-melotti, @vadmium, @zware, @eryksun, @csabella
Superseder	bpo-26701: Documentation for int constructor mentions int but not trunc

^{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 2018-03-16.11:24:53.922>
created_at = <Date 2014-05-30.08:58:55.736>
labels = ['type-feature', 'docs']
title = 'int() docstring - unclear what number is'
updated_at = <Date 2018-03-16.11:24:53.921>
user = 'https://bugs.python.org/and'

bugs.python.org fields:

activity = <Date 2018-03-16.11:24:53.921>
actor = 'cheryl.sabella'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-03-16.11:24:53.922>
closer = 'cheryl.sabella'
components = ['Documentation']
creation = <Date 2014-05-30.08:58:55.736>
creator = 'and'
dependencies = []
files = []
hgrepos = []
issue_num = 21611
keywords = []
message_count = 6.0
messages = ['219379', '219530', '219551', '219552', '313908', '313941']
nosy_count = 9.0
nosy_names = ['rhettinger', 'ezio.melotti', 'cvrebert', 'docs@python', 'martin.panter', 'zach.ware', 'eryksun', 'and', 'cheryl.sabella']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '26701'
type = 'enhancement'
url = 'https://bugs.python.org/issue21611'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[and]

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.

[rhettinger]

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.

[and]

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.

[eryksun]

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.

[csabella]

Is this superseded by bpo-26701?

[and]

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.