[Python-Dev] [Python-checkins] r87445 - python/branches/py3k/Lib/numbers.py

[Nick Coghlan]

On Mon, Dec 27, 2010 at 3:13 AM, Éric Araujo <merwok at netwok.org> wrote:
> Le 24/12/2010 02:08, Nick Coghlan a écrit :
>> On Fri, Dec 24, 2010 at 4:41 AM, eric.araujo <python-checkins at python.org> wrote:
>>> Fix small inaccuracy: there is no index function
>>
>> Yes, there is, it just isn't a builtin - it lives in the operator module.
> Defining object.__index__ with operator.index seems pretty circular to
> me :)  http://docs.python.org/dev/reference/datamodel#object.__index__
> does it, but it should be fixed IMO.  The difference between __int__ and
> __index__ is also not clear.

Yes, the definition in the language reference could definitely be
improved to mention the semantics first, and then reference
operator.index second.

Possible wording "Indicates to the Python interpreter that the object
is semantically equivalent to the returned integer, rather than merely
supporting a possibly lossy coercion to an integer (i.e. as the
__int__ method allows for types like float and decimal.Decimal). This
allows non-builtin objects to be used as sequence indices, elements of
a slice definition, multiplies in sequence repetition, etc. Can be
invoked explicitly from Python code via operator.index()"

Removing the circularity from the definitions of __index__ and
operator.index doesn't have a great deal to do with the docstrings in
numbers.py, though.

>>>     def __index__(self):
>>> -        """index(self)"""
>>> +        """someobject[self]"""
>>>         return int(self)
>>
>> Changing the docstring to say "operator.index(self)" would be the
>> clearest solution here.
> I disagree.  __add__ is documented as implementing +, not operator.add.

That's because "+" is the idiomatic spelling. operator.index *is* the
Python level spelling of obj.__index__() - there is no other way to
spell it (other than calling the method explicitly, which is subtly
different).

>> (Choosing to accept arbitrary index objects as
>> integer equivalents is up to the object being indexed, just like
>> interpreting slices is - a dict, for example, will never invoke
>> __index__ methods).
> I honestly don’t know what the best fix is.  We could copy the doc from
> datamodel (“called whenever Python needs an integer object (such as in
> slicing, or in the built-in bin(), hex() and oct() functions)”).  I’ve
> been told on IRC to let Mark Dickison decide how to fix the docstrings
> in the numbers module (deleting them being of course an option: magic
> methods are documented in the language reference, they don’t need
> docstrings).

Indeed. However, as a reference module for the numeric tower, it makes
a certain amount of sense to keep the docstrings in this particular
case.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia