updates from Facundo Batista, with edits

pep-0327.txt

@@ -8,7 +8,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 17-Oct-2003
 Python-Version: 2.4
-Post-History: 30-Nov-2003, 02-Jan-2004
+Post-History: 30-Nov-2003, 02-Jan-2004, 29-Jan-2004
 
 
 Abstract
@@ -400,21 +400,32 @@ The explicit construction does not get affected by the context (there
 is no rounding, no limits by the precision, etc.), because the context
 affects just operations' results.
 
-**From int or long**: There's no loss and no need to specify any other
-information::
+
+From int or long
+''''''''''''''''
+
+There's no loss and no need to specify any other information::
 
     Decimal(35)
     Decimal(-124)
 
-**From string**: Strings with floats in normal and engineering
-notation will be supported.  In this transformation there is no loss
-of information, as the string is directly converted to Decimal (there
-is not an intermediate conversion through float)::
+
+From string
+'''''''''''
+
+Strings with floats in normal and engineering notation will be
+supported.  In this transformation there is no loss of information, as
+the string is directly converted to Decimal (there is not an
+intermediate conversion through float)::
 
     Decimal("-12")
     Decimal("23.2e-7")
 
-**From float**: The initial discussion on this item was what should
+
+From float
+''''''''''
+
+The initial discussion on this item was what should
 happen when passing floating point to the constructor:
 
     1. ``Decimal(1.1) == Decimal('1.1')``
@@ -460,16 +471,25 @@ But Alex Martelli says that:
     I think "construction from float with some default precision" runs
     a substantial risk of tricking naive users.
 
-So, I think that the best solution is to have a parameter that says in
-which position after the decimal point you apply a round-half-up
-rounding.  If you do not specify this parameter, you get an exact
-conversion. In this way::
+So, the accepted solution through c.l.p is that you can not call Decimal
+with a float. Instead you must use a method: Decimal.from_float(). The
+syntax::
 
-    Decimal(1.1, 2) == Decimal('1.1')
-    Decimal(1.1, 16) == Decimal('1.1000000000000001')
-    Decimal(1.1) == Decimal('110000000000000008881784197001252...e-51')
+    Decimal.from_float(floatNumber, [positions])
+    
+where ``floatNumber`` is the float number origin of the construction and
+``positions`` is the positions after the decimal point where you apply a
+round-half-up rounding, if any.  In this way you can do, for example::
 
-**From tuples**: Aahz suggested to construct from tuples: it's easier
+    Decimal.from_float(1.1, 2): The same that doing Decimal('1.1').
+    Decimal.from_float(1.1, 16): The same that doing Decimal('1.1000000000000001').
+    Decimal.from_float(1.1): The same that doing Decimal('110000000000000008881784197001252...e-51').
+
+
+From tuples
+'''''''''''
+
+Aahz suggested to construct from tuples: it's easier
 to implement ``eval()``'s round trip and "someone who has numeric
 values representing a Decimal does not need to convert them to a
 string."
@@ -480,14 +500,24 @@ and the exponent is a signed int or long::
 
     Decimal((1, (3, 2, 2, 5), -2))     # for -32.25
 
-**From Decimal**: No mystery here, just a copy.
 
-**Syntax to all the cases**::
+From Decimal
+''''''''''''
 
-    Decimal(value, [decimal_digits])
+No mystery here, just a copy.
 
-where ``value`` can be any of the data types just mentioned and
-``decimal_digits`` is allowed only when value is float.
+
+Syntax for All Cases
+''''''''''''''''''''
+
+::
+
+    Decimal(value1)
+    Decimal.from_float(value2, [decimal_digits])
+
+where ``value1`` can be int, long, string, tuple or Decimal,
+``value1`` can be only float, and ``decimal_digits`` is an optional
+int.
 
 
 Implicit construction
@@ -509,15 +539,27 @@ thinks that
 
 So, here I define the behaviour again for each data type.
 
-**From int or long**: Aahz suggested the need of an explicit
-conversion from int, but also thinks it's OK if the precision in the
-current Context is not exceeded; in that case you raise ValueError.
-Votes in comp.lang.python agreed with this.
 
-**From string**: Everybody agrees to raise an exception here.
+From int or long
+''''''''''''''''
 
-**From float**: Aahz is strongly opposed to interact with float,
-suggesting an explicit conversion:
+Aahz suggested the need of an explicit conversion from int, but also
+thinks it's OK if the precision in the current Context is not
+exceeded; in that case you raise ValueError.  Votes in
+comp.lang.python agreed with this.
+
+
+From string
+'''''''''''
+
+Everybody agrees to raise an exception here.
+
+
+From float
+''''''''''
+
+Aahz is strongly opposed to interact with float, suggesting an
+explicit conversion:
 
     The problem is that Decimal is capable of greater precision,
     accuracy, and range than float.
@@ -533,7 +575,14 @@ precision in the current context (this is maybe too tricky, because
 for example with a precision of 9, ``Decimal(35) + 1.2`` is OK but
 ``Decimal(35) + 1.1`` raises an error).
 
-**From Decimal**: There isn't any issue here.
+This resulted to be too tricky. So tricky, that c.l.p agreed to raise
+TypeError in this case: you could not mix Decimal and float.
+
+
+From Decimal
+''''''''''''
+
+There isn't any issue here.
 
 
 Use of Context