From 453bc8c9e866d76db3d294390a54dec287e260d8 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sat, 7 May 2022 12:58:50 +0100 Subject: [PATCH 01/10] gh-92417: `fractions` docs: remove references to Python <3.2 #92417 --- Doc/library/fractions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index c893f2d5389d57..890151af58e36f 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -122,7 +122,7 @@ another rational number, or from a string. .. note:: - From Python 3.2 onwards, you can also construct a + You can also construct a :class:`Fraction` instance directly from a :class:`float`. @@ -133,7 +133,7 @@ another rational number, or from a string. .. note:: - From Python 3.2 onwards, you can also construct a + You can also construct a :class:`Fraction` instance directly from a :class:`decimal.Decimal` instance. From eb5a0ac3aeb4cb4effe1efc3dbea10a8359f6522 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Sun, 8 May 2022 18:03:54 +0100 Subject: [PATCH 02/10] Address review --- Doc/library/decimal.rst | 44 ++++++++++++++++----------------------- Doc/library/fractions.rst | 26 ++++++----------------- 2 files changed, 24 insertions(+), 46 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 2ad84f20b5560f..22563109a51b0e 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -374,10 +374,22 @@ Decimal objects returns ``Decimal('1.414')``. If *value* is a :class:`float`, the binary floating point value is losslessly - converted to its exact decimal equivalent. This conversion can often require - 53 or more digits of precision. For example, ``Decimal(float('1.1'))`` - converts to - ``Decimal('1.100000000000000088817841970012523233890533447265625')``. + converted to its exact decimal equivalent. This means, for example, that + `Decimal(0.1)` is not the same as `Decimal('0.1')`. + Since 0.1 is not exactly representable in binary floating point, the + value is stored as the nearest representable value which is + `0x1.999999999999ap-4`. + + .. doctest:: + + >>> Decimal(0.1) + Decimal('0.1000000000000000055511151231257827021181583404541015625') + >>> Decimal(float('nan')) + Decimal('NaN') + >>> Decimal(float('inf')) + Decimal('Infinity') + >>> Decimal(float('-inf')) + Decimal('-Infinity') The *context* precision does not affect how many digits are stored. That is determined exclusively by the number of digits in *value*. For example, @@ -571,29 +583,9 @@ Decimal objects >>> Decimal(321).exp() Decimal('2.561702493119680037517373933E+139') - .. method:: from_float(f) + .. classmethod:: from_float(f) - Classmethod that converts a float to a decimal number, exactly. - - Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. - Since 0.1 is not exactly representable in binary floating point, the - value is stored as the nearest representable value which is - `0x1.999999999999ap-4`. That equivalent value in decimal is - `0.1000000000000000055511151231257827021181583404541015625`. - - .. note:: From Python 3.2 onwards, a :class:`Decimal` instance - can also be constructed directly from a :class:`float`. - - .. doctest:: - - >>> Decimal.from_float(0.1) - Decimal('0.1000000000000000055511151231257827021181583404541015625') - >>> Decimal.from_float(float('nan')) - Decimal('NaN') - >>> Decimal.from_float(float('inf')) - Decimal('Infinity') - >>> Decimal.from_float(float('-inf')) - Decimal('-Infinity') + Alternative constructor that only accepts instances of :class:`float`. .. versionadded:: 3.1 diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 890151af58e36f..e0e5b4a2e37936 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -114,29 +114,15 @@ another rational number, or from a string. .. versionadded:: 3.8 - .. method:: from_float(flt) + .. classmethod:: from_float(flt) - This class method constructs a :class:`Fraction` representing the exact - value of *flt*, which must be a :class:`float`. Beware that - ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. + Alternative constructor which only accepts instances of + :class:~numbers.Integral` or :class:`float`. - .. note:: - - You can also construct a - :class:`Fraction` instance directly from a :class:`float`. - - - .. method:: from_decimal(dec) - - This class method constructs a :class:`Fraction` representing the exact - value of *dec*, which must be a :class:`decimal.Decimal` instance. - - .. note:: - - You can also construct a - :class:`Fraction` instance directly from a :class:`decimal.Decimal` - instance. + .. classmethod:: from_decimal(dec) + Alternative constructor which only accepts instances of + :class:`decimal.Decimal`. .. method:: limit_denominator(max_denominator=1000000) From ac23becfa59a487cd6166fa912c094011c83e322 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Sun, 8 May 2022 18:09:26 +0100 Subject: [PATCH 03/10] reST --- Doc/library/decimal.rst | 4 ++-- Doc/library/fractions.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 22563109a51b0e..36e2a432170417 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -375,10 +375,10 @@ Decimal objects If *value* is a :class:`float`, the binary floating point value is losslessly converted to its exact decimal equivalent. This means, for example, that - `Decimal(0.1)` is not the same as `Decimal('0.1')`. + ``Decimal(0.1)`` is not the same as ``Decimal('0.1')``. Since 0.1 is not exactly representable in binary floating point, the value is stored as the nearest representable value which is - `0x1.999999999999ap-4`. + ``0x1.999999999999ap-4``. .. doctest:: diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index e0e5b4a2e37936..78c5f56abb0ad2 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,7 +117,7 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:~numbers.Integral` or :class:`float`. + :class:`~numbers.Integral` or :class:`float`. .. classmethod:: from_decimal(dec) From 20399c34689175201657647da236d430700cbc74 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Sun, 8 May 2022 18:42:06 +0100 Subject: [PATCH 04/10] Address review 2 --- Doc/library/decimal.rst | 3 ++- Doc/library/fractions.rst | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 36e2a432170417..aaa5e0662e3b9c 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -585,7 +585,8 @@ Decimal objects .. classmethod:: from_float(f) - Alternative constructor that only accepts instances of :class:`float`. + Alternative constructor that only accepts instances of :class:`float` or + :class:`int`. .. versionadded:: 3.1 diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 78c5f56abb0ad2..7d413a2b8d524b 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,12 +117,12 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:`~numbers.Integral` or :class:`float`. + :class:`float` or :class:`numbers.Integral`. .. classmethod:: from_decimal(dec) Alternative constructor which only accepts instances of - :class:`decimal.Decimal`. + :class:`decimal.Decimal` or :class:`numbers.Integral`. .. method:: limit_denominator(max_denominator=1000000) From f519d0a94758c9cf4194fb3a813b14e4ae0b008b Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Sun, 8 May 2022 18:59:19 +0100 Subject: [PATCH 05/10] More doctest Co-authored-by: Ezio Melotti --- Doc/library/decimal.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index aaa5e0662e3b9c..f589b88a71017e 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -382,6 +382,8 @@ Decimal objects .. doctest:: + >>> Decimal(0.1) == Decimal('0.1') + False >>> Decimal(0.1) Decimal('0.1000000000000000055511151231257827021181583404541015625') >>> Decimal(float('nan')) From e023dc67f018b4a037a2a2a3c1b9f6b4b77201a1 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Mon, 9 May 2022 08:41:47 +0100 Subject: [PATCH 06/10] Use longform representation, not hex representation --- Doc/library/decimal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index f589b88a71017e..30a2385e2a1178 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -378,7 +378,7 @@ Decimal objects ``Decimal(0.1)`` is not the same as ``Decimal('0.1')``. Since 0.1 is not exactly representable in binary floating point, the value is stored as the nearest representable value which is - ``0x1.999999999999ap-4``. + ``0.1000000000000000055511151231257827021181583404541015625``. .. doctest:: From 8f537ea9e72a3c10b116ae2b4ec4989f8f53c089 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Mon, 9 May 2022 08:48:50 +0100 Subject: [PATCH 07/10] Add notes that these are legacy methods --- Doc/library/decimal.rst | 3 ++- Doc/library/fractions.rst | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 30a2385e2a1178..4486880065582d 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -588,7 +588,8 @@ Decimal objects .. classmethod:: from_float(f) Alternative constructor that only accepts instances of :class:`float` or - :class:`int`. + :class:`int`. A legacy method which largely exists for backwards + compatibility. .. versionadded:: 3.1 diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 7d413a2b8d524b..6224d7abd94782 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,12 +117,14 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:`float` or :class:`numbers.Integral`. + :class:`float` or :class:`numbers.Integral`. A legacy method which + largely exists for backwards compatibility. .. classmethod:: from_decimal(dec) Alternative constructor which only accepts instances of - :class:`decimal.Decimal` or :class:`numbers.Integral`. + :class:`decimal.Decimal` or :class:`numbers.Integral`. A legacy method + which largely exists for backwards compatibility. .. method:: limit_denominator(max_denominator=1000000) From 44357721f48839b87e88f4846d56daf0710d673b Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Mon, 9 May 2022 09:25:59 +0100 Subject: [PATCH 08/10] I can write in full sentences --- Doc/library/decimal.rst | 2 +- Doc/library/fractions.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 4486880065582d..79c12ef4094361 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -588,7 +588,7 @@ Decimal objects .. classmethod:: from_float(f) Alternative constructor that only accepts instances of :class:`float` or - :class:`int`. A legacy method which largely exists for backwards + :class:`int`. This is a legacy method which largely exists for backwards compatibility. .. versionadded:: 3.1 diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 6224d7abd94782..f2dacf1f76e011 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,14 +117,14 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:`float` or :class:`numbers.Integral`. A legacy method which - largely exists for backwards compatibility. + :class:`float` or :class:`numbers.Integral`. This is a legacy method + which largely exists for backwards compatibility. .. classmethod:: from_decimal(dec) Alternative constructor which only accepts instances of - :class:`decimal.Decimal` or :class:`numbers.Integral`. A legacy method - which largely exists for backwards compatibility. + :class:`decimal.Decimal` or :class:`numbers.Integral`. This is a legacy + method which largely exists for backwards compatibility. .. method:: limit_denominator(max_denominator=1000000) From 4a8d55e132257482f9724aadfcb7c0fd76cf8110 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Mon, 9 May 2022 10:40:11 +0100 Subject: [PATCH 09/10] Revert addition of notes that these are legacy methods --- Doc/library/decimal.rst | 3 +-- Doc/library/fractions.rst | 6 ++---- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 79c12ef4094361..30a2385e2a1178 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -588,8 +588,7 @@ Decimal objects .. classmethod:: from_float(f) Alternative constructor that only accepts instances of :class:`float` or - :class:`int`. This is a legacy method which largely exists for backwards - compatibility. + :class:`int`. .. versionadded:: 3.1 diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index f2dacf1f76e011..7d413a2b8d524b 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,14 +117,12 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:`float` or :class:`numbers.Integral`. This is a legacy method - which largely exists for backwards compatibility. + :class:`float` or :class:`numbers.Integral`. .. classmethod:: from_decimal(dec) Alternative constructor which only accepts instances of - :class:`decimal.Decimal` or :class:`numbers.Integral`. This is a legacy - method which largely exists for backwards compatibility. + :class:`decimal.Decimal` or :class:`numbers.Integral`. .. method:: limit_denominator(max_denominator=1000000) From bf191193ec095f17fa26417f777ac255f8bf4071 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Tue, 10 May 2022 12:45:58 +0100 Subject: [PATCH 10/10] Start again --- Doc/library/decimal.rst | 42 ++++++++++++++++++++++----------------- Doc/library/fractions.rst | 16 ++++++++++++++- 2 files changed, 39 insertions(+), 19 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 30a2385e2a1178..d052581c970124 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -374,24 +374,10 @@ Decimal objects returns ``Decimal('1.414')``. If *value* is a :class:`float`, the binary floating point value is losslessly - converted to its exact decimal equivalent. This means, for example, that - ``Decimal(0.1)`` is not the same as ``Decimal('0.1')``. - Since 0.1 is not exactly representable in binary floating point, the - value is stored as the nearest representable value which is - ``0.1000000000000000055511151231257827021181583404541015625``. - - .. doctest:: - - >>> Decimal(0.1) == Decimal('0.1') - False - >>> Decimal(0.1) - Decimal('0.1000000000000000055511151231257827021181583404541015625') - >>> Decimal(float('nan')) - Decimal('NaN') - >>> Decimal(float('inf')) - Decimal('Infinity') - >>> Decimal(float('-inf')) - Decimal('-Infinity') + converted to its exact decimal equivalent. This conversion can often require + 53 or more digits of precision. For example, ``Decimal(float('1.1'))`` + converts to + ``Decimal('1.100000000000000088817841970012523233890533447265625')``. The *context* precision does not affect how many digits are stored. That is determined exclusively by the number of digits in *value*. For example, @@ -590,6 +576,26 @@ Decimal objects Alternative constructor that only accepts instances of :class:`float` or :class:`int`. + Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`. + Since 0.1 is not exactly representable in binary floating point, the + value is stored as the nearest representable value which is + `0x1.999999999999ap-4`. That equivalent value in decimal is + `0.1000000000000000055511151231257827021181583404541015625`. + + .. note:: From Python 3.2 onwards, a :class:`Decimal` instance + can also be constructed directly from a :class:`float`. + + .. doctest:: + + >>> Decimal.from_float(0.1) + Decimal('0.1000000000000000055511151231257827021181583404541015625') + >>> Decimal.from_float(float('nan')) + Decimal('NaN') + >>> Decimal.from_float(float('inf')) + Decimal('Infinity') + >>> Decimal.from_float(float('-inf')) + Decimal('-Infinity') + .. versionadded:: 3.1 .. method:: fma(other, third, context=None) diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst index 7d413a2b8d524b..5f0ecf1f135ea5 100644 --- a/Doc/library/fractions.rst +++ b/Doc/library/fractions.rst @@ -117,13 +117,27 @@ another rational number, or from a string. .. classmethod:: from_float(flt) Alternative constructor which only accepts instances of - :class:`float` or :class:`numbers.Integral`. + :class:`float` or :class:`numbers.Integral`. Beware that + ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. + + .. note:: + + From Python 3.2 onwards, you can also construct a + :class:`Fraction` instance directly from a :class:`float`. + .. classmethod:: from_decimal(dec) Alternative constructor which only accepts instances of :class:`decimal.Decimal` or :class:`numbers.Integral`. + .. note:: + + From Python 3.2 onwards, you can also construct a + :class:`Fraction` instance directly from a :class:`decimal.Decimal` + instance. + + .. method:: limit_denominator(max_denominator=1000000) Finds and returns the closest :class:`Fraction` to ``self`` that has