From 7a335ed24dc60b7cf5ca17c589b7c5e02853ab34 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Mon, 6 Jan 2025 14:01:30 +0300 Subject: [PATCH 1/5] decimal docs: specification link and examples * added a direct reference to a floating-point model used * and few examples for formatted string output --- Doc/library/decimal.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 185eaf3f721c72..0838c212c8571c 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -34,10 +34,12 @@ The :mod:`decimal` module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the :class:`float` datatype: -* Decimal "is based on a floating-point model which was designed with people - in mind, and necessarily has a paramount guiding principle -- computers must - provide an arithmetic that works in the same way as the arithmetic that - people learn at school." -- excerpt from the decimal arithmetic specification. +* Decimal "is based on a [floating-point + model](https://speleotrove.com/decimal/damodel.html#refnumber) which was + designed with people in mind, and necessarily has a paramount guiding + principle -- computers must provide an arithmetic that works in the same way + as the arithmetic that people learn at school." -- excerpt from the decimal + arithmetic specification. * Decimal numbers can be represented exactly. In contrast, numbers like ``1.1`` and ``2.2`` do not have exact representations in binary @@ -238,6 +240,23 @@ floating-point flying circus: >>> c % a Decimal('0.77') +Decimals could be formatted in fixed-point or scientific notation, using same +formatting syntax (see :ref:`formatspec`) as builtin :class:`float` type: + +.. doctest:: + + >>> format(Decimal('2.675'), "f") + '2.675' + >>> format(Decimal('2.675'), ".2f") + '2.68' + >>> format(Decimal('2.675'), ".2e") + '2.68e+0' + >>> with localcontext() as ctx: + ... ctx.rounding = ROUND_DOWN + ... print(format(Decimal('2.675'), ".2f")) + ... + 2.67 + And some mathematical functions are also available to Decimal: >>> getcontext().prec = 28 From a66b20a66b46185375e1fef2dfbff370af260399 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 10 Jan 2025 09:16:27 +0300 Subject: [PATCH 2/5] Update Doc/library/decimal.rst Co-authored-by: RUANG (James Roy) --- Doc/library/decimal.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 0838c212c8571c..8fe991b83e275b 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -34,8 +34,8 @@ The :mod:`decimal` module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the :class:`float` datatype: -* Decimal "is based on a [floating-point - model](https://speleotrove.com/decimal/damodel.html#refnumber) which was +* Decimal "is based on a [floating-point model] + (https://speleotrove.com/decimal/damodel.html#refnumber) which was designed with people in mind, and necessarily has a paramount guiding principle -- computers must provide an arithmetic that works in the same way as the arithmetic that people learn at school." -- excerpt from the decimal From 228091ad011173211e3d68427f23f8060bbc102d Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 10 Jan 2025 09:22:25 +0300 Subject: [PATCH 3/5] + fix sphinx markup; sorry I was in md mode) --- Doc/library/decimal.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 8fe991b83e275b..7669a2125f36c7 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -34,11 +34,11 @@ The :mod:`decimal` module provides support for fast correctly rounded decimal floating-point arithmetic. It offers several advantages over the :class:`float` datatype: -* Decimal "is based on a [floating-point model] - (https://speleotrove.com/decimal/damodel.html#refnumber) which was - designed with people in mind, and necessarily has a paramount guiding - principle -- computers must provide an arithmetic that works in the same way - as the arithmetic that people learn at school." -- excerpt from the decimal +* Decimal "is based on a `floating-point model + `_ which was designed + with people in mind, and necessarily has a paramount guiding principle -- + computers must provide an arithmetic that works in the same way as the + arithmetic that people learn at school." -- excerpt from the decimal arithmetic specification. * Decimal numbers can be represented exactly. In contrast, numbers like From 6fb60ef4ec9640b4aa6133cf66b1fafc77254bab Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Sat, 11 Jan 2025 05:06:52 +0300 Subject: [PATCH 4/5] Update Doc/library/decimal.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- 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 7669a2125f36c7..d3975ab4446435 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -240,7 +240,7 @@ floating-point flying circus: >>> c % a Decimal('0.77') -Decimals could be formatted in fixed-point or scientific notation, using same +Decimals can be formatted in fixed-point or scientific notation, using the same formatting syntax (see :ref:`formatspec`) as builtin :class:`float` type: .. doctest:: From 3d402cef7b075595068c4b58e5b9e08a472b8758 Mon Sep 17 00:00:00 2001 From: Sergey B Kirpichev Date: Fri, 24 Jan 2025 05:29:07 +0300 Subject: [PATCH 5/5] address review: refs to format/f-strings, add f-string example --- Doc/library/decimal.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index d3975ab4446435..146cf5dbaf29b1 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -240,8 +240,9 @@ floating-point flying circus: >>> c % a Decimal('0.77') -Decimals can be formatted in fixed-point or scientific notation, using the same -formatting syntax (see :ref:`formatspec`) as builtin :class:`float` type: +Decimals can be formatted (with :func:`format` built-in or :ref:`f-strings`) in +fixed-point or scientific notation, using the same formatting syntax (see +:ref:`formatspec`) as builtin :class:`float` type: .. doctest:: @@ -249,6 +250,8 @@ formatting syntax (see :ref:`formatspec`) as builtin :class:`float` type: '2.675' >>> format(Decimal('2.675'), ".2f") '2.68' + >>> f"{Decimal('2.675'):.2f}" + '2.68' >>> format(Decimal('2.675'), ".2e") '2.68e+0' >>> with localcontext() as ctx: