PEP: XXX

Title: A rational number module for Python

Version: $Revision: 1.4 $

Last-Modified: $Date: 2003/09/22 04:51:50 $

Author: Mike Meyer <mw*@mired.org>

Status: Draft

Type: Staqndards

Content-Type: text/x-rst

Created: 16-Dec-2004

Python-Version: 2.5

Post-History: 30-Aug-2002

Abstract

========

This PEP proposes a rational number module to add to the Python

standard library.

Rationale

=========

Rationals are a standard mathematical concept, included in a variety

of programming languages already. Python, which comes with 'batteries

included' should not be deficient in this area. When the subject was

brought up on comp.lang.python several people mentioned having

implemented a rational number module, one person more than once. In

fact, there is a rational number module distributed with Python as an

example module. Such repetition shows the need for such a class in the

standard library.

There are currently two PEPs dealing with rational numbers - 'Adding a

Rational Type to Python' [#PEP-239] and 'Adding a Rational Literal to

Python' [#PEP-240], both by Craig and Zadka. This PEP competes with

those PEPs, but does not change the Python language as those two PEPs

do [#PEP-239-implicit]. As such, it should be easier for it to gain

acceptance. At some future time, PEP's 239 and 240 may replace the

``rational`` module.

Specification

=============

The module shall be ``rational``, and the class ``Rational``, to

follow the example of the decimal [#PEP-327] module. The class

creation method shall accept as arguments a numerator, and an optional

denominator, which defaults to one. Both the numerator and

denominator - if present - must be of integer type. Since all other

numeric types in Python are immutable, Rational objects will be

immutable. Internally, the representation will insure that the

numerator and denominator have a greatest common divisor of 1, and

that the sign of the denominator is positive.

The ``Rational`` class shall define all the standard mathematical

operations: addition, subtraction, multiplication, division, modulo

and power. It will also provide the methods:

- max(*args): return the largest of a list of numbers and self.

- min(*args): return the smallest of a list of numbers and self.

- decimal(): return the decimal approximation to the rational in the

current context.

- inv(): Return the inverse of self.

Rationals will mix with all other numeric types. When combined with an

integer type, that integer will be converted to a rational before the

operation. When combined with a floating type - either complex or

float - the rational will be converted to a floating approximation

before the operation, and a float or complex will be returned. The

reason for this is that floating point numbers - including complex -

are already imprecise. To convert them to rational would give an

incorrect impression that the results of the operation are

precise. Decimals will be converted to rationals before the

operation. [Open question: is this the right thing to do?]

Rationals can be converted to floats by float(rational), and to

integers by int(rational).

The module will define and at times raise the following exceptions:

- DivisionByZero: divide by zero

- OverflowError: overflow attempting to convert to a float.

Implementation

==============

There is currently a rational module distributed with Python, and a

second rational module in the Python cvs source tree that is not

distributed. While one of these could be chosen and made to conform

to the specification, I am hoping that several people will volunteer

implementatins so that a ''best of breed'' implementation may be

chosen.

References

==========

... [#PEP-239] Adding a Rational Type to Python, Craig, Zadka

(http://www.python.org/peps/pep-0239.html)

... [#PEP-240] Adding a Rational Literal to Python, Craig, Zadka

(http://www.python.org/peps/pep-0240.html)

... [#PEP-327] Decimal Data Type, Batista

(http://www.python.org/peps/pep-0327.html)

... [#PEP-239-implicit] PEP 240 adds a new literal type to Pytbon,

PEP 239 implies that division of integers would

change to return rationals.

Copyright

=========

This document has been placed in the public domain.

...

Local Variables:

mode: indented-text

indent-tabs-mode: nil

sentence-end-double-space: t

fill-column: 70

End: