From 57b2ae2659d68adc85e3098cbbc489e800d1cf68 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 12:30:24 +0000 Subject: [PATCH 01/10] Update BNF definition --- Doc/library/string.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 09165c481b246e..5ff5dcc2c0a6d5 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -319,12 +319,12 @@ non-empty format specification typically modifies the result. The general form of a *standard format specifier* is: .. productionlist:: format-spec - format_spec: [[`fill`]`align`][`sign`]["z"]["#"]["0"][`width`][`grouping_option`]["." `precision`][`type`] + format_spec: [[`fill`]`align`][`sign`]["z"]["#"]["0"][`width`][`grouping`]["." `precision`][`type`] fill: align: "<" | ">" | "=" | "^" sign: "+" | "-" | " " width: `~python-grammar:digit`+ - grouping_option: "_" | "," + grouping: "," | "_" precision: `~python-grammar:digit`+ type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%" From ecc32c767cc64e99edacaa54fd75b818ba8686d6 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 12:32:04 +0000 Subject: [PATCH 02/10] Update description 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 5ff5dcc2c0a6d5..82ffb6447397db 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -495,7 +495,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 group separators. | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -577,7 +577,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 group separators | + | | 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 939303e26f88d379978208fda316203527c8fd65 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 12:32:41 +0000 Subject: [PATCH 03/10] Refactor grouping description --- Doc/library/string.rst | 61 +++++++++++++++++++++++++----------------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 82ffb6447397db..6ef20fe01047e3 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -414,30 +414,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. -.. 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, +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. @@ -450,6 +427,42 @@ excluding :class:`complex`. This is equivalent to a *fill* character of Preceding the *width* field by ``'0'`` no longer affects the default alignment for strings. + +The *grouping* option after the *width* field specifies +a digit group separator for the integral part of a number. +It can be one of the following: + +.. index:: + single: , (comma); in string formatting + single: _ (underscore); in string formatting + ++---------+----------------------------------------------------------+ +| Option | Meaning | ++=========+==========================================================+ +| ``','`` | 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 not supported. | ++---------+----------------------------------------------------------+ +| ``'_'`` | 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 are inserted every 4 digits. | +| | For other presentation types, | +| | this option is not supported. | ++---------+----------------------------------------------------------+ + +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`). + The *precision* is a decimal integer indicating how many digits should be displayed after the decimal point for presentation types ``'f'`` and ``'F'``, or before and after the decimal point for presentation From 7d97b2e02305ea5a32d2be6f65e98742ff90bab0 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 12:36:36 +0000 Subject: [PATCH 04/10] Update examples --- Doc/library/string.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 6ef20fe01047e3..330adf231b3047 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -718,10 +718,18 @@ 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 as a thousands separator:: +Using the comma or the underscore as a digit group separator:: >>> '{:,}'.format(1234567890) '1,234,567,890' + >>> '{:_}'.format(1234567890) + '1_234_567_890' + >>> '{:_b}'.format(1234567890) + '100_1001_1001_0110_0000_0010_1101_0010' + >>> '{:_x}'.format(1234567890) + '4996_02d2' + >>> '{:_}'.format(123456789.123456789) + '123_456_789.12345679' Expressing a percentage:: From 543af6bbf1efab75af8369371ff470794f929a25 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 05/10] 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 330adf231b3047..2bc406d1e6d4d3 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -380,13 +380,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 b37539d4271f1e4d83d8046fd336f92d4a7f53e7 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 12:55:51 +0000 Subject: [PATCH 06/10] Add extra example --- Doc/library/string.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 2bc406d1e6d4d3..ff534b84057c05 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -728,6 +728,8 @@ Using the comma or the underscore as a digit group separator:: '100_1001_1001_0110_0000_0010_1101_0010' >>> '{:_x}'.format(1234567890) '4996_02d2' + >>> '{:,}'.format(123456789.123456789) + '123,456,789.12345679' >>> '{:_}'.format(123456789.123456789) '123_456_789.12345679' From 8745604716fa6fd77c4e35dacc8395c3edf386ab Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 15:58:52 +0000 Subject: [PATCH 07/10] Remove floating-point examples --- Doc/library/string.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index ff534b84057c05..a29b26e17a4648 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -728,10 +728,6 @@ Using the comma or the underscore as a digit group separator:: '100_1001_1001_0110_0000_0010_1101_0010' >>> '{:_x}'.format(1234567890) '4996_02d2' - >>> '{:,}'.format(123456789.123456789) - '123,456,789.12345679' - >>> '{:_}'.format(123456789.123456789) - '123_456_789.12345679' Expressing a percentage:: From 07be487274c17b38452679577753b55bcee82703 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 19:18:28 +0000 Subject: [PATCH 08/10] Change BNF definition --- 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 a29b26e17a4648..1cad5f3ff225f3 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -319,14 +319,16 @@ non-empty format specification typically modifies the result. The general form of a *standard format specifier* is: .. productionlist:: format-spec - format_spec: [[`fill`]`align`][`sign`]["z"]["#"]["0"][`width`][`grouping`]["." `precision`][`type`] + format_spec: [`options`][`width`][`grouping`]["." `precision`][`type`] + options: [[`fill`]`align`][`sign`]["z"]["#"]["0"] fill: align: "<" | ">" | "=" | "^" sign: "+" | "-" | " " width: `~python-grammar:digit`+ grouping: "," | "_" precision: `~python-grammar:digit`+ - type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%" + type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" + : | "G" | "n" | "o" | "s" | "x" | "X" | "%" If a valid *align* value is specified, it can be preceded by a *fill* character that can be any character and defaults to a space if omitted. From 6faffb85b2a1196a65d6532c7622262a8c6b16a1 Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 19:27:11 +0000 Subject: [PATCH 09/10] try to rebuild docs preview --- 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 1cad5f3ff225f3..11547630d3869f 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -316,7 +316,7 @@ A general convention is that an empty format specification produces the same result as if you had called :func:`str` on the value. A non-empty format specification typically modifies the result. -The general form of a *standard format specifier* is: +The general form of a *standard format specifier* is: .. productionlist:: format-spec format_spec: [`options`][`width`][`grouping`]["." `precision`][`type`] From 5915921a75ca982d85b67e2af3064b31413d312f Mon Sep 17 00:00:00 2001 From: Prometheus3375 <35541026+Prometheus3375@users.noreply.github.com> Date: Sat, 5 Apr 2025 20:16:55 +0000 Subject: [PATCH 10/10] Revert "try to rebuild docs preview" This reverts commit 6faffb85b2a1196a65d6532c7622262a8c6b16a1. --- 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 11547630d3869f..1cad5f3ff225f3 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -316,7 +316,7 @@ A general convention is that an empty format specification produces the same result as if you had called :func:`str` on the value. A non-empty format specification typically modifies the result. -The general form of a *standard format specifier* is: +The general form of a *standard format specifier* is: .. productionlist:: format-spec format_spec: [`options`][`width`][`grouping`]["." `precision`][`type`]