https://github.com/python/cpython/commit/06a110f5227ba9d52f6205fde55924a14cab36ff
commit: 06a110f5227ba9d52f6205fde55924a14cab36ff
branch: main
author: Prometheus3375 <35541026+prometheus3...@users.noreply.github.com>
committer: picnixz <10796600+picn...@users.noreply.github.com>
date: 2025-04-05T10:28:50+02:00
summary:
gh-131912: Improve description of grouping options in the format specification
docs (#132030)
Co-authored-by: Bénédikt Tran <10796600+picn...@users.noreply.github.com>
files:
M Doc/library/string.rst
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 721c5c8d334674..f2f3ab9eefdd50 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" | "%"
@@ -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. |
+---------+----------------------------------------------------------+
@@ -419,30 +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.
-.. 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.
@@ -463,12 +440,43 @@ 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* fields specifies
+a digit group separator for the 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 |
++=========+==========================================================+
+| ``','`` | 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`).
.. versionchanged:: 3.14
- Support thousands separators for the fractional part.
+ Support the *grouping* option for the fractional part.
Finally, the *type* determines how the data should be presented.
@@ -507,7 +515,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'``. |
+---------+----------------------------------------------------------+
@@ -589,7 +597,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. |
@@ -716,12 +725,16 @@ 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 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'
>>> '{:._}'.format(123456789.123456789)
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
