From 2e8d1914598dd39537d641ca79fa4bb55df39c39 Mon Sep 17 00:00:00 2001 From: oda-gitso Date: Thu, 9 Feb 2023 17:59:34 +0700 Subject: [PATCH 1/7] Document Decimal.__round__() --- Doc/library/decimal.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index fec9b86864c5781..cafed7de5a232ec 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -886,6 +886,42 @@ Decimal objects :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. + .. method:: __round__(n=None) + + If *n* is ``None``, returns the nearest :class:`int` to ``self``, rounding + ties to even, ignoring the rounding mode of the :class:`Decimal` context. + Raises :exc:`OverflowError` if ``self`` is an infinity or :exc:`ValueError` + if ``self`` is a (quiet or signaling) NaN. + + If *n* is an :class:`int`, the context's rounding mode is respected and + a :class:`Decimal` representing ``self`` rounded to the nearest multiple + of ``Decimal('1E-n')`` is returned; ``round(self, n)`` is exactly equivalent + to ``self.quantize(Decimal('1E-n'))``. Returns ``Decimal('NaN')`` if ``self`` + is a quiet NaN. Raises :class:`InvalidOperation` if ``self`` is an + infinity, a signaling NaN, or if the length of the coefficient after the + quantize operation would be greater than the current context's precision. + In other words, for the non-corner cases: + + * if *n* is positive, return ``self`` rounded to *n* decimal places; + * if *n* is zero, return ``self`` rounded to the nearest integer; + * if *n* is negative, return ``self`` rounded to the nearest multiple of + ``10**abs(n)``. + + For example:: + + >>> from decimal import Decimal, getcontext, ROUND_DOWN + >>> getcontext().rounding = ROUND_DOWN + >>> round(Decimal('3.75')) # context rounding ignored + 4 + >>> round(Decimal('3.5')) # round-ties-to-even + 4 + >>> round(Decimal('3.75'), 0) # uses the context rounding + Decimal('3') + >>> round(Decimal('3.75'), 1) + Decimal('3.7') + >>> round(Decimal('3.75'), -1) + Decimal('0E+1') + .. _logical_operands_label: From 7db936569339e2a34988e8c91968eddb847c7023 Mon Sep 17 00:00:00 2001 From: OTheDev <116417456+OTheDev@users.noreply.github.com> Date: Fri, 24 May 2024 13:37:05 +0700 Subject: [PATCH 2/7] Use describe instead of method --- Doc/library/decimal.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 11eb8958e2d6de4..9228587915f7e1e 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -897,25 +897,26 @@ Decimal objects :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. - .. method:: __round__(n=None) + .. describe:: round(number, n=None) - If *n* is ``None``, returns the nearest :class:`int` to ``self``, rounding - ties to even, ignoring the rounding mode of the :class:`Decimal` context. - Raises :exc:`OverflowError` if ``self`` is an infinity or :exc:`ValueError` - if ``self`` is a (quiet or signaling) NaN. + If *n* is ``None``, returns the nearest :class:`int` to ``number``, + rounding ties to even, ignoring the rounding mode of the :class:`Decimal` + context. Raises :exc:`OverflowError` if ``number`` is an infinity or + :exc:`ValueError` if ``number`` is a (quiet or signaling) NaN. If *n* is an :class:`int`, the context's rounding mode is respected and - a :class:`Decimal` representing ``self`` rounded to the nearest multiple - of ``Decimal('1E-n')`` is returned; ``round(self, n)`` is exactly equivalent - to ``self.quantize(Decimal('1E-n'))``. Returns ``Decimal('NaN')`` if ``self`` - is a quiet NaN. Raises :class:`InvalidOperation` if ``self`` is an - infinity, a signaling NaN, or if the length of the coefficient after the - quantize operation would be greater than the current context's precision. - In other words, for the non-corner cases: - - * if *n* is positive, return ``self`` rounded to *n* decimal places; - * if *n* is zero, return ``self`` rounded to the nearest integer; - * if *n* is negative, return ``self`` rounded to the nearest multiple of + a :class:`Decimal` representing ``number`` rounded to the nearest multiple + of ``Decimal('1E-n')`` is returned; ``round(number, n)`` is exactly + equivalent to ``self.quantize(Decimal('1E-n'))``. Returns + ``Decimal('NaN')`` if ``number`` is a quiet NaN. Raises + :class:`InvalidOperation` if ``number`` is an infinity, a signaling NaN, + or if the length of the coefficient after the quantize operation would be + greater than the current context's precision. In other words, for the + non-corner cases: + + * if *n* is positive, return ``number`` rounded to *n* decimal places; + * if *n* is zero, return ``number`` rounded to the nearest integer; + * if *n* is negative, return ``number`` rounded to the nearest multiple of ``10**abs(n)``. For example:: From bd432ec466b07ee54fe5d09ef017d58225cd4cdd Mon Sep 17 00:00:00 2001 From: OTheDev <116417456+OTheDev@users.noreply.github.com> Date: Fri, 24 May 2024 14:05:39 +0700 Subject: [PATCH 3/7] Use ndigits instead of n --- Doc/library/decimal.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 9228587915f7e1e..7c7c96a8dcca3ef 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -897,27 +897,28 @@ Decimal objects :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. - .. describe:: round(number, n=None) + .. describe:: round(number, ndigits=None) - If *n* is ``None``, returns the nearest :class:`int` to ``number``, + If *ndigits* is ``None``, returns the nearest :class:`int` to ``number``, rounding ties to even, ignoring the rounding mode of the :class:`Decimal` context. Raises :exc:`OverflowError` if ``number`` is an infinity or :exc:`ValueError` if ``number`` is a (quiet or signaling) NaN. - If *n* is an :class:`int`, the context's rounding mode is respected and - a :class:`Decimal` representing ``number`` rounded to the nearest multiple - of ``Decimal('1E-n')`` is returned; ``round(number, n)`` is exactly - equivalent to ``self.quantize(Decimal('1E-n'))``. Returns - ``Decimal('NaN')`` if ``number`` is a quiet NaN. Raises - :class:`InvalidOperation` if ``number`` is an infinity, a signaling NaN, - or if the length of the coefficient after the quantize operation would be - greater than the current context's precision. In other words, for the - non-corner cases: - - * if *n* is positive, return ``number`` rounded to *n* decimal places; - * if *n* is zero, return ``number`` rounded to the nearest integer; - * if *n* is negative, return ``number`` rounded to the nearest multiple of - ``10**abs(n)``. + If *ndigits* is an :class:`int`, the context's rounding mode is respected + and a :class:`Decimal` representing ``number`` rounded to the nearest + multiple of ``Decimal('1E-ndigits')`` is returned; + ``round(number, ndigits)`` is exactly equivalent to + ``self.quantize(Decimal('1E-ndigits'))``. Returns ``Decimal('NaN')`` if + ``number`` is a quiet NaN. Raises :class:`InvalidOperation` if ``number`` + is an infinity, a signaling NaN, or if the length of the coefficient after + the quantize operation would be greater than the current context's + precision. In other words, for the non-corner cases: + + * if *ndigits* is positive, return ``number`` rounded to *ndigits* decimal + places; + * if *ndigits* is zero, return ``number`` rounded to the nearest integer; + * if *ndigits* is negative, return ``number`` rounded to the nearest + multiple of ``10**abs(ndigits)``. For example:: From bfc8c15f08ed35469c8ff13760753173160ed235 Mon Sep 17 00:00:00 2001 From: OTheDev <116417456+OTheDev@users.noreply.github.com> Date: Fri, 24 May 2024 14:20:32 +0700 Subject: [PATCH 4/7] Use consistent markup for both arguments --- Doc/library/decimal.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 7c7c96a8dcca3ef..d827b3871466cc7 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -899,25 +899,25 @@ Decimal objects .. describe:: round(number, ndigits=None) - If *ndigits* is ``None``, returns the nearest :class:`int` to ``number``, + If *ndigits* is ``None``, returns the nearest :class:`int` to *number*, rounding ties to even, ignoring the rounding mode of the :class:`Decimal` - context. Raises :exc:`OverflowError` if ``number`` is an infinity or - :exc:`ValueError` if ``number`` is a (quiet or signaling) NaN. + context. Raises :exc:`OverflowError` if *number* is an infinity or + :exc:`ValueError` if *number* is a (quiet or signaling) NaN. If *ndigits* is an :class:`int`, the context's rounding mode is respected - and a :class:`Decimal` representing ``number`` rounded to the nearest + and a :class:`Decimal` representing *number* rounded to the nearest multiple of ``Decimal('1E-ndigits')`` is returned; ``round(number, ndigits)`` is exactly equivalent to ``self.quantize(Decimal('1E-ndigits'))``. Returns ``Decimal('NaN')`` if - ``number`` is a quiet NaN. Raises :class:`InvalidOperation` if ``number`` + *number* is a quiet NaN. Raises :class:`InvalidOperation` if *number* is an infinity, a signaling NaN, or if the length of the coefficient after the quantize operation would be greater than the current context's precision. In other words, for the non-corner cases: - * if *ndigits* is positive, return ``number`` rounded to *ndigits* decimal + * if *ndigits* is positive, return *number* rounded to *ndigits* decimal places; - * if *ndigits* is zero, return ``number`` rounded to the nearest integer; - * if *ndigits* is negative, return ``number`` rounded to the nearest + * if *ndigits* is zero, return *number* rounded to the nearest integer; + * if *ndigits* is negative, return *number* rounded to the nearest multiple of ``10**abs(ndigits)``. For example:: From 2dea5ba42c25d1b17995c8aa6896d41649e8522a Mon Sep 17 00:00:00 2001 From: OTheDev <116417456+OTheDev@users.noreply.github.com> Date: Fri, 24 May 2024 19:14:08 +0700 Subject: [PATCH 5/7] Minor wording tweaks --- 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 d827b3871466cc7..f3191f57367c5dc 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -900,14 +900,14 @@ Decimal objects .. describe:: round(number, ndigits=None) If *ndigits* is ``None``, returns the nearest :class:`int` to *number*, - rounding ties to even, ignoring the rounding mode of the :class:`Decimal` - context. Raises :exc:`OverflowError` if *number* is an infinity or - :exc:`ValueError` if *number* is a (quiet or signaling) NaN. + rounding ties to even, and ignoring the rounding mode of the + :class:`Decimal` context. Raises :exc:`OverflowError` if *number* is an + infinity or :exc:`ValueError` if it is a (quiet or signaling) NaN. If *ndigits* is an :class:`int`, the context's rounding mode is respected and a :class:`Decimal` representing *number* rounded to the nearest - multiple of ``Decimal('1E-ndigits')`` is returned; - ``round(number, ndigits)`` is exactly equivalent to + multiple of ``Decimal('1E-ndigits')`` is returned; in this case, + ``round(number, ndigits)`` is equivalent to ``self.quantize(Decimal('1E-ndigits'))``. Returns ``Decimal('NaN')`` if *number* is a quiet NaN. Raises :class:`InvalidOperation` if *number* is an infinity, a signaling NaN, or if the length of the coefficient after From dbadd172e2ffba1c66e1ccd4cb597da3576a06cd Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 31 May 2024 13:43:47 +0200 Subject: [PATCH 6/7] Add a heading to separate the `describe` from methods --- Doc/library/decimal.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index f3191f57367c5dc..3a9bdc69ff72bbc 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -897,6 +897,8 @@ Decimal objects :const:`Rounded`. If given, applies *rounding*; otherwise, uses the rounding method in either the supplied *context* or the current context. + Decimal numbers can be rounded using the :func:`.round` function: + .. describe:: round(number, ndigits=None) If *ndigits* is ``None``, returns the nearest :class:`int` to *number*, From 852c2e560e4b89300cb2cf00fcd69d7d824e6dd3 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 10 Jun 2024 11:47:50 +0200 Subject: [PATCH 7/7] Split the usage --- Doc/library/decimal.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 3a9bdc69ff72bbc..db323802a6f68c5 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -899,9 +899,11 @@ Decimal objects Decimal numbers can be rounded using the :func:`.round` function: - .. describe:: round(number, ndigits=None) + .. describe:: round(number) + .. describe:: round(number, ndigits) - If *ndigits* is ``None``, returns the nearest :class:`int` to *number*, + If *ndigits* is not given or ``None``, + returns the nearest :class:`int` to *number*, rounding ties to even, and ignoring the rounding mode of the :class:`Decimal` context. Raises :exc:`OverflowError` if *number* is an infinity or :exc:`ValueError` if it is a (quiet or signaling) NaN.