[docs] Bug Report: Incorrect Abstract Method Requirements in numbers.Integral Documentation

[Lefavor, Matthew (GSFC-582.0)[MICROTEL LLC]]

To whom it may concern:

The documentation for numbers.Integral reports incorrect abstract method requirements for numbers.Integral.

The documentation for numbers.Integral (in both Python 2.7 and Python 3.2) states:

Subtypes Rational<http://docs.python.org/library/numbers.html#numbers.Rational> and adds a conversion to int<http://docs.python.org/library/functions.html#int>. Provides defaults for float()<http://docs.python.org/library/functions.html#float>, numerator<http://docs.python.org/library/numbers.html#numbers.Rational.numerator>, and denominator<http://docs.python.org/library/numbers.html#numbers.Rational.denominator>, and bit-string operations: <<, >>, &, ^, |, ~.

Defaults for operations <<, >>, &, ^, |, and ~ are not provided, and a look at the source code shows that they are all given as abstract methods. In addition, in Python 2.x, numbers.Integral adds an abstract conversion to long. This is not recorded in the documentation.

Originally, I was going to report this as a bug, because PEP 3141<http://www.python.org/dev/peps/pep-3141/> (the PEP that specifies the numbers module) goes so far as to include the <<, >>, &, ^, |, and ~ in the source code for numbers.Integral. It looks like somebody already had reported this years ago, however, to python-dev with Issue 3056<http://bugs.python.org/issue3056>. The issue was never resolved, but has since been closed.

Since the development community does not seem interested in adding these features, the features should be removed from documentation.

Thank you for your time,

Matthew Lefavor

NASA GSFC [Microtel, LLC]
Mail Code 699.0/Org Code 582.0
matthew.lefavor at nasa.gov
(301) 614-6818 (Desk)
(443) 758-4891 (Cell)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20120207/9924f338/attachment-0001.html>