PEP 485: Apply Chris's changes

pep-0485.txt

@@ -15,9 +15,9 @@ Resolution: https://mail.python.org/pipermail/python-dev/2015-February/138598.ht
 Abstract
 ========
 
-This PEP proposes the addition of a function to the standard library
+This PEP proposes the addition of an is_close() function to the standard
-that determines whether one value is approximately equal or "close" to
+library math module that determines whether one value is approximately equal
-another value.
+or "close" to another value.
 
 
 Rationale
@@ -31,7 +31,7 @@ Often a inequality comparison fits the bill, but there are times
 (often in testing) where the programmer wants to determine whether a
 computed value is "close" to an expected value, without requiring them
 to be exactly equal. This is common enough, particularly in testing,
-and not always obvious how to do it, so it would be useful addition to
+and not always obvious how to do it, that it would be useful addition to
 the standard library.
 
 
@@ -113,8 +113,14 @@ Non-float types
 The primary use-case is expected to be floating point numbers.
 However, users may want to compare other numeric types similarly. In
 theory, it should work for any type that supports ``abs()``,
-multiplication, comparisons, and subtraction.  The code will be written
+multiplication, comparisons, and subtraction. However, the implimentation
-and tested to accommodate these types:
+in the math module is written in C, and thus can not (easily) use python's
+duck typing. Rather, the values passed into the funciton will be converted
+to the float type before the calculation is performed. Passing in types
+(or values) that cannot be converted to floats will raise an appropirate
+Exception (TypeError, ValueError, or OverflowError).
+
+The code will be tested to accommodate at least some values of these types:
 
 * ``Decimal``
 
@@ -122,10 +128,14 @@ and tested to accommodate these types:
 
 * ``Fraction``
 
-* ``complex``: for complex, the absolute value of the complex values
+* ``complex``: For complex, a companion function will be added to the
+  ``cmath`` module. In ``cmath.isclose()``, the tolerances are specified
+  as floats, and the absolute value of the complex values
   will be used for scaling and comparison. If a complex tolerance is
   passed in, the absolute value will be used as the tolerance.
 
+NOTE: it may make sense to add a ``Decimal.isclose()`` that works properly and
+completely with the decimal type, but that is not included as part of this PEP.
 
 Behavior near zero
 ------------------
@@ -182,13 +192,14 @@ check as well.
 Implementation
 --------------
 
-A sample implementation is available (as of Jan 22, 2015) on gitHub:
+A sample implementation in python is available (as of Jan 22, 2015) on
+gitHub:
 
 https://github.com/PythonCHB/close_pep/blob/master/is_close.py
 
 This implementation has a flag that lets the user select which
 relative tolerance test to apply -- this PEP does not suggest that
-that be retained, but rather than the weak test be selected.
+that be retained, but rather that the weak test be selected.
 
 There are also drafts of this PEP and test code, etc. there:
 
@@ -386,7 +397,7 @@ they yield the same result, but this proposal uses the boost "weak"
 test case: it is symmetric and provides a more useful result for very
 large tolerances.
 
-Large tolerances
+Large Tolerances
 ----------------
 
 The most common use case is expected to be small tolerances -- on order of the
@@ -476,7 +487,7 @@ ideally would be doing careful error propagation analysis, and should
 understand exactly what to test for. It is also likely that ULP (Unit
 in the Last Place) comparison may be called for. While this function
 may prove useful in such situations, It is not intended to be used in
-that way.
+that way without careful consideration.
 
 
 Other Approaches