[issue21611] int() docstring - unclear what number is

[Cheryl Sabella]

Change by Cheryl Sabella :


--
resolution:  -> duplicate
stage:  -> resolved
status: open -> closed
superseder:  -> Documentation for int constructor mentions __int__ but not 
__trunc__

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Dmitry Andreychuk]

Dmitry Andreychuk  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Cheryl Sabella]

Cheryl Sabella  added the comment:

Is this superseded by issue 26701?

--
nosy: +csabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Chris Rebert]

Changes by Chris Rebert pyb...@rebertia.com:


--
nosy: +cvrebert

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Martin Panter]

Changes by Martin Panter vadmium...@gmail.com:


--
nosy: +vadmium

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Dmitry Andreychuk]

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 rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[eryksun]

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 rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Raymond Hettinger]

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 rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Ezio Melotti]

Changes by Ezio Melotti ezio.melo...@gmail.com:


--
nosy: +ezio.melotti, zach.ware
type:  - enhancement
versions:  -Python 3.1, Python 3.2, Python 3.3

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21611] int() docstring - unclear what number is

[Dmitry Andreychuk]

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 rep...@bugs.python.org
http://bugs.python.org/issue21611
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com