From 272c5135b33c2ad5c8b03aef5946f9a18e54bc63 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Wed, 2 Apr 2025 18:41:02 +0000 Subject: [PATCH 01/11] Refactor grouping description --- Doc/library/string.rst | 62 ++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 721c5c8d334674..85027ad3b4f1ab 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -325,11 +325,11 @@ The general form of a *standard format specifier* is: align: "<" | ">" | "=" | "^" sign: "+" | "-" | " " width_and_precision: [`width_with_grouping`][`precision_with_grouping`] - width_with_grouping: [`width`][`grouping_option`] - precision_with_grouping: "." [`precision`]`grouping_option` + width_with_grouping: [`width`][`grouping`] + precision_with_grouping: "." [`precision`][`grouping`] width: `~python-grammar:digit`+ - grouping_option: "_" | "," precision: `~python-grammar:digit`+ + grouping: "," | "_" type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" : | "G" | "n" | "o" | "s" | "x" | "X" | "%" @@ -419,29 +419,6 @@ decimal-point character appears in the result of these conversions only if a digit follows it. In addition, for ``'g'`` and ``'G'`` conversions, trailing zeros are not removed from the result. -.. index:: single: , (comma); in string formatting - -The ``','`` option signals the use of a comma for a thousands separator for -floating-point presentation types and for integer presentation type ``'d'``. -For other presentation types, this option is an error. -For a locale aware separator, use the ``'n'`` integer presentation type -instead. - -.. versionchanged:: 3.1 - Added the ``','`` option (see also :pep:`378`). - -.. index:: single: _ (underscore); in string formatting - -The ``'_'`` option signals the use of an underscore for a thousands -separator for floating-point presentation types and for integer -presentation type ``'d'``. For integer presentation types ``'b'``, -``'o'``, ``'x'``, and ``'X'``, underscores will be inserted every 4 -digits. For other presentation types, specifying this option is an -error. - -.. versionchanged:: 3.6 - Added the ``'_'`` option (see also :pep:`515`). - *width* is a decimal integer defining the minimum total field width, including any prefixes, separators, and other formatting characters. If not specified, then the field width will be determined by the content. @@ -463,10 +440,37 @@ indicates the maximum field size - in other words, how many characters will be used from the field content. The *precision* is not allowed for integer presentation types. -The ``'_'`` or ``','`` option after *precision* means the use of an underscore -or a comma for a thousands separator of the fractional part for floating-point -presentation types. +The *grouping* option after *width* and *precision* specifies a thousands +separator for integral and fractional parts of a number respectively. +It can be one of the following: + +.. index:: + single: , (comma); in string formatting + single: _ (underscore); in string formatting + ++---------+----------------------------------------------------------+ +| Option | Meaning | ++=========+==========================================================+ +| ``','`` | Uses a comma as a thousands separator for | +| | floating-point presentation types | +| | and integer presentation type ``'d'``. | +| | For other presentation types, this option is an error. | ++---------+----------------------------------------------------------+ +| ``'_'`` | Uses an underscore as a thousands separator for | +| | floating-point presentation types | +| | and integer presentation type ``'d'``. | +| | For integer presentation types | +| | ``'b'``, ``'o'``, ``'x'``, and ``'X'``, | +| | underscores will be inserted every 4 digits. | +| | For other presentation types, this option is an error. | ++---------+----------------------------------------------------------+ + +For a locale aware separator, use the ``'n'`` presentation type instead. +.. versionchanged:: 3.1 + Added the ``','`` option (see also :pep:`378`). +.. versionchanged:: 3.6 + Added the ``'_'`` option (see also :pep:`515`). .. versionchanged:: 3.14 Support thousands separators for the fractional part. From 2c83cdf3523e2f387343b461c6b76c2987bf6650 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Wed, 2 Apr 2025 18:41:39 +0000 Subject: [PATCH 02/11] Capitalize sentences for sign option --- Doc/library/string.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 85027ad3b4f1ab..a50d0ee68c6907 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -385,13 +385,13 @@ following: +---------+----------------------------------------------------------+ | Option | Meaning | +=========+==========================================================+ -| ``'+'`` | indicates that a sign should be used for both | +| ``'+'`` | Indicates that a sign should be used for both | | | positive as well as negative numbers. | +---------+----------------------------------------------------------+ -| ``'-'`` | indicates that a sign should be used only for negative | +| ``'-'`` | Indicates that a sign should be used only for negative | | | numbers (this is the default behavior). | +---------+----------------------------------------------------------+ -| space | indicates that a leading space should be used on | +| space | Indicates that a leading space should be used on | | | positive numbers, and a minus sign on negative numbers. | +---------+----------------------------------------------------------+ From d99700d69a8657da8e887621e80864c88f367a0e Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Thu, 3 Apr 2025 11:46:52 +0000 Subject: [PATCH 03/11] Reword grouping description --- Doc/library/string.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index a50d0ee68c6907..12c15ebee60966 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -440,7 +440,7 @@ indicates the maximum field size - in other words, how many characters will be used from the field content. The *precision* is not allowed for integer presentation types. -The *grouping* option after *width* and *precision* specifies a thousands +The *grouping* option after *width* and *precision* specifies a digit separator for integral and fractional parts of a number respectively. It can be one of the following: @@ -451,17 +451,17 @@ It can be one of the following: +---------+----------------------------------------------------------+ | Option | Meaning | +=========+==========================================================+ -| ``','`` | Uses a comma as a thousands separator for | -| | floating-point presentation types | -| | and integer presentation type ``'d'``. | +| ``','`` | Inserts a comma every 3 digits for | +| | integer presentation type ``'d'`` and | +| | floating-point presentation types, excluding ``'n'``. | | | For other presentation types, this option is an error. | +---------+----------------------------------------------------------+ -| ``'_'`` | Uses an underscore as a thousands separator for | -| | floating-point presentation types | -| | and integer presentation type ``'d'``. | +| ``'_'`` | Inserts an underscore every 3 digits for | +| | integer presentation type ``'d'`` and | +| | floating-point presentation types, excluding ``'n'``. | | | For integer presentation types | | | ``'b'``, ``'o'``, ``'x'``, and ``'X'``, | -| | underscores will be inserted every 4 digits. | +| | underscores are inserted every 4 digits. | | | For other presentation types, this option is an error. | +---------+----------------------------------------------------------+ @@ -472,7 +472,7 @@ For a locale aware separator, use the ``'n'`` presentation type instead. .. versionchanged:: 3.6 Added the ``'_'`` option (see also :pep:`515`). .. versionchanged:: 3.14 - Support thousands separators for the fractional part. + Support *grouping* option for the fractional part. Finally, the *type* determines how the data should be presented. @@ -720,7 +720,7 @@ Replacing ``%x`` and ``%o`` and converting the value to different bases:: >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' -Using the comma or the underscore as a thousands separator:: +Using the comma or the underscore as a digit separator:: >>> '{:,}'.format(1234567890) '1,234,567,890' From d2f0bb932b021468eb4e736455e2990835805d15 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Thu, 3 Apr 2025 11:47:47 +0000 Subject: [PATCH 04/11] Update descriptions of type n --- Doc/library/string.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 12c15ebee60966..24bb4069d583d8 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -511,7 +511,7 @@ The available integer presentation types are: +---------+----------------------------------------------------------+ | ``'n'`` | Number. This is the same as ``'d'``, except that it uses | | | the current locale setting to insert the appropriate | - | | number separator characters. | + | | digit separator characters. | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -593,7 +593,8 @@ The available presentation types for :class:`float` and +---------+----------------------------------------------------------+ | ``'n'`` | Number. This is the same as ``'g'``, except that it uses | | | the current locale setting to insert the appropriate | - | | number separator characters. | + | | digit separator characters | + | | for the integral part of a number. | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. | From c3499d62b63cda015d49f9cd0b7d54791b3dfee1 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Thu, 3 Apr 2025 11:48:38 +0000 Subject: [PATCH 05/11] Add example of _ with octal type --- Doc/library/string.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 24bb4069d583d8..d72377da4a1616 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -727,6 +727,8 @@ Using the comma or the underscore as a digit separator:: '1,234,567,890' >>> '{:_}'.format(1234567890) '1_234_567_890' + >>> '{:_o}'.format(1234567890) + '111_4540_1322' >>> '{:_}'.format(123456789.123456789) '123_456_789.12345679' >>> '{:._}'.format(123456789.123456789) From dd9acb65b68e6081a00e342daf65d0445f131b4e Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Fri, 4 Apr 2025 22:03:20 +0300 Subject: [PATCH 06/11] Add line breaks after versionchanged MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/string.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index d72377da4a1616..a689f9c568df79 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -469,8 +469,10 @@ For a locale aware separator, use the ``'n'`` presentation type instead. .. versionchanged:: 3.1 Added the ``','`` option (see also :pep:`378`). + .. versionchanged:: 3.6 Added the ``'_'`` option (see also :pep:`515`). + .. versionchanged:: 3.14 Support *grouping* option for the fractional part. From 0c8a03622b3d30f63843c11aaa8f1d1f02887706 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Fri, 4 Apr 2025 19:20:14 +0000 Subject: [PATCH 07/11] Add missing the --- Doc/library/string.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index a689f9c568df79..8542284339bdc5 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -419,7 +419,7 @@ decimal-point character appears in the result of these conversions only if a digit follows it. In addition, for ``'g'`` and ``'G'`` conversions, trailing zeros are not removed from the result. -*width* is a decimal integer defining the minimum total field width, +The *width* is a decimal integer defining the minimum total field width, including any prefixes, separators, and other formatting characters. If not specified, then the field width will be determined by the content. @@ -440,7 +440,7 @@ indicates the maximum field size - in other words, how many characters will be used from the field content. The *precision* is not allowed for integer presentation types. -The *grouping* option after *width* and *precision* specifies a digit +The *grouping* option after *width* and *precision* fields specifies a digit separator for integral and fractional parts of a number respectively. It can be one of the following: @@ -474,7 +474,7 @@ For a locale aware separator, use the ``'n'`` presentation type instead. Added the ``'_'`` option (see also :pep:`515`). .. versionchanged:: 3.14 - Support *grouping* option for the fractional part. + Support the *grouping* option for the fractional part. Finally, the *type* determines how the data should be presented. From c6a175fe5de0934e52474c5b07657b612fd8a0d5 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Fri, 4 Apr 2025 19:52:18 +0000 Subject: [PATCH 08/11] Use digit group separator --- Doc/library/string.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 8542284339bdc5..0b544a9f89ed0d 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -440,9 +440,9 @@ indicates the maximum field size - in other words, how many characters will be used from the field content. The *precision* is not allowed for integer presentation types. -The *grouping* option after *width* and *precision* fields specifies a digit -separator for integral and fractional parts of a number respectively. -It can be one of the following: +The *grouping* option after *width* and *precision* fields specifies +a digit group separator for integral and fractional parts +of a number respectively. It can be one of the following: .. index:: single: , (comma); in string formatting @@ -513,7 +513,7 @@ The available integer presentation types are: +---------+----------------------------------------------------------+ | ``'n'`` | Number. This is the same as ``'d'``, except that it uses | | | the current locale setting to insert the appropriate | - | | digit separator characters. | + | | digit group separators. | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -595,7 +595,7 @@ The available presentation types for :class:`float` and +---------+----------------------------------------------------------+ | ``'n'`` | Number. This is the same as ``'g'``, except that it uses | | | the current locale setting to insert the appropriate | - | | digit separator characters | + | | digit group separators | | | for the integral part of a number. | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | @@ -723,7 +723,7 @@ Replacing ``%x`` and ``%o`` and converting the value to different bases:: >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42) 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010' -Using the comma or the underscore as a digit separator:: +Using the comma or the underscore as a digit group separator:: >>> '{:,}'.format(1234567890) '1,234,567,890' From fd55c51fe6451f17c3f565a1e4d9302a34346de8 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 00:22:29 +0300 Subject: [PATCH 09/11] Add missing the MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/string.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 0b544a9f89ed0d..4a3047fe47fba1 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -441,7 +441,7 @@ used from the field content. The *precision* is not allowed for integer presentation types. The *grouping* option after *width* and *precision* fields specifies -a digit group separator for integral and fractional parts +a digit group separator for the integral and fractional parts of a number respectively. It can be one of the following: .. index:: From 29b521f0991472e8cfa384f97fdc4c62ca039d28 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Fri, 4 Apr 2025 21:24:55 +0000 Subject: [PATCH 10/11] Reword unavailability --- Doc/library/string.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 4a3047fe47fba1..42c62de7bb447f 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -454,7 +454,8 @@ of a number respectively. It can be one of the following: | ``','`` | Inserts a comma every 3 digits for | | | integer presentation type ``'d'`` and | | | floating-point presentation types, excluding ``'n'``. | -| | For other presentation types, this option is an error. | +| | For other presentation types, | +| | this option is not supported. | +---------+----------------------------------------------------------+ | ``'_'`` | Inserts an underscore every 3 digits for | | | integer presentation type ``'d'`` and | @@ -462,7 +463,8 @@ of a number respectively. It can be one of the following: | | For integer presentation types | | | ``'b'``, ``'o'``, ``'x'``, and ``'X'``, | | | underscores are inserted every 4 digits. | -| | For other presentation types, this option is an error. | +| | For other presentation types, | +| | this option is not supported. | +---------+----------------------------------------------------------+ For a locale aware separator, use the ``'n'`` presentation type instead. From 27b28dbd1b8dfb3c8908065a7e5c0e0747d56533 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Fri, 4 Apr 2025 21:27:28 +0000 Subject: [PATCH 11/11] Change example from octal to b and x --- Doc/library/string.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 42c62de7bb447f..f2f3ab9eefdd50 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -731,8 +731,10 @@ Using the comma or the underscore as a digit group separator:: '1,234,567,890' >>> '{:_}'.format(1234567890) '1_234_567_890' - >>> '{:_o}'.format(1234567890) - '111_4540_1322' + >>> '{:_b}'.format(1234567890) + '100_1001_1001_0110_0000_0010_1101_0010' + >>> '{:_x}'.format(1234567890) + '4996_02d2' >>> '{:_}'.format(123456789.123456789) '123_456_789.12345679' >>> '{:._}'.format(123456789.123456789)