[Python-checkins] r57295 - peps/trunk/pep-3141.txt

[jeffrey.yasskin]

Author: jeffrey.yasskin
Date: Thu Aug 23 00:07:53 2007
New Revision: 57295

Modified:
   peps/trunk/pep-3141.txt
Log:
Resolve the open issues and address float.__mod__() returning the wrong answer for some arguments.


Modified: peps/trunk/pep-3141.txt
==============================================================================
--- peps/trunk/pep-3141.txt	(original)
+++ peps/trunk/pep-3141.txt	Thu Aug 23 00:07:53 2007
@@ -55,9 +55,7 @@
 
 Most implementations of complex numbers will be hashable, but if you
 need to rely on that, you'll have to check it explicitly: mutable
-numbers are supported by this hierarchy. **Open issue:** Should
-__pos__ coerce the argument to be an instance of the type it's defined
-on? Why do the builtins do this? ::
+numbers are supported by this hierarchy. ::
 
     class Complex(Number):
         """Complex defines the operations that work on the builtin complex type.
@@ -107,7 +105,11 @@
             raise NotImplementedError
 
         def __pos__(self):
-            return self
+            """+self
+
+            Coerces self to whatever class defines the method.
+            """
+            raise NotImplementedError
 
         def __sub__(self, other):
             return self + -other
@@ -189,6 +191,25 @@
             """
             raise NotImplementedError
 
+        @abstractmethod
+        def __floor__(self):
+            """Finds the greatest Integral <= self."""
+            raise NotImplementedError
+
+        @abstractmethod
+        def __ceil__(self):
+            """Finds the least Integral >= self."""
+            raise NotImplementedError
+
+        @abstractmethod
+        def __round__(self, ndigits:Integral=None):
+            """Rounds self to ndigits decimal places, defaulting to 0.
+
+            If ndigits is omitted, returns an Integral, otherwise
+            returns a Real. Rounds half toward even.
+            """
+            raise NotImplementedError
+
         def __divmod__(self, other):
             """The pair (self // other, self % other).
 
@@ -217,10 +238,18 @@
 
         @abstractmethod
         def __mod__(self, other):
+            """self % other
+
+            See
+            http://mail.python.org/pipermail/python-3000/2006-May/001735.html
+            and consider using "self/other - trunc(self/other)"
+            instead if you're worried about round-off errors.
+            """
             raise NotImplementedError
 
         @abstractmethod
         def __rmod__(self, other):
+            """other % self"""
             raise NotImplementedError
 
         @abstractmethod
@@ -250,9 +279,9 @@
             return self
 
 
-There is no built-in rational type, but it's straightforward to write,
-so we provide an ABC for it. **Open issue**: Add Demo/classes/Rat.py
-to the stdlib? ::
+We need to clean up Demo/classes/Rat.py and promote it into
+rational.py in the standard library. Then it will implement the
+Rational ABC. ::
 
     class Rational(Real, Exact):
         """.numerator and .denominator should be in lowest terms."""
@@ -388,27 +417,17 @@
 3. ``__ceil__(self)``, called from ``math.ceil(x)``, which returns the
    least Integral ``>= x``.
 
-4. ``__round__(self)``, called from ``round(x)``, with returns the
-   Integral closest to ``x``, rounding half toward even. **Open
-   issue:** We could support the 2-argument version, but then we'd
-   only return an Integral if the second argument were ``<= 0``.
-
-5. ``__properfraction__(self)``, called from a new function,
-   ``math.properfraction(x)``, which resembles C's ``modf()``: returns
-   a pair ``(n:Integral, r:Real)`` where ``x == n + r``, both ``n``
-   and ``r`` have the same sign as ``x``, and ``abs(r) < 1``. **Open
-   issue:** Oh, we already have ``math.modf``. What name do we want
-   for this? Should we use divmod(x, 1) instead?
+4. ``__round__(self)``, called from ``round(x)``, which returns the
+   Integral closest to ``x``, rounding half toward even. The
+   2-argument version should return a Real.
 
 Because the ``int()`` conversion from ``float`` is equivalent to but
 less explicit than ``trunc()``, let's remove it. (Or, if that breaks
 too much, just add a deprecation warning.)
 
-``complex.__{divmod,mod,floordiv,int,float}__`` should also go
-away. These should continue to raise ``TypeError`` to help confused
-porters, but should not appear in ``help(complex)`` to avoid confusing
-more people. **Open issue:** This is difficult to do with the
-``PyNumberMethods`` struct. What's the best way to accomplish it?
+``complex.__{divmod,mod,floordiv,int,float}__`` also go away. It would
+be nice to provide a nice error message to help confused porters, but
+not appearing in ``help(complex)`` is more important.
 
 
 Notes for type implementors