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 <mwm at 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: