From f57111deb35ade3f4ec55bcd1fcba06014fc958f Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Thu, 29 May 2025 10:08:28 -0400 Subject: [PATCH 1/5] Add references to locale module for locale-aware number formatting --- Doc/library/string.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index c4012483a52f73..c7f995bce763c8 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -469,7 +469,9 @@ of a number respectively. It can be one of the following: | | this option is not supported. | +---------+----------------------------------------------------------+ -For a locale aware separator, use the ``'n'`` presentation type instead. +For a locale-aware separator, use the ``'n'`` presentation type instead. Note +that the locale setting for numeric values must first be set using the +:mod:`locale` module, *e.g.,* ``locale.setlocale(locale.LC_NUMERIC, 'en_US')``. .. versionchanged:: 3.1 Added the ``','`` option (see also :pep:`378`). @@ -517,7 +519,8 @@ 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 group separators. | + | | digit group separators, provided that the locale has | + | | been properly set (see the :mod:`locale` module). | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -599,8 +602,9 @@ 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 group separators | - | | for the integral part of a number. | + | | digit group separators for the integral part of a | + | | number, provided that the locale has been properly set | + | | (see the :mod:`locale` module). | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. | From 9223d7315d59d2ef1a60f7ecd3c25d2c9942e07e Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Thu, 29 May 2025 17:30:25 +0200 Subject: [PATCH 2/5] Rephrasing changes per review comments --- Doc/library/string.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index c7f995bce763c8..66d5fda63db321 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -469,9 +469,10 @@ of a number respectively. It can be one of the following: | | this option is not supported. | +---------+----------------------------------------------------------+ -For a locale-aware separator, use the ``'n'`` presentation type instead. Note -that the locale setting for numeric values must first be set using the -:mod:`locale` module, *e.g.,* ``locale.setlocale(locale.LC_NUMERIC, 'en_US')``. +For a locale-aware separator, use the ``'n'`` presentation type instead. +Note that the locale setting for numeric values must first be set using +the :mod:`locale` module, for example, +``locale.setlocale(locale.LC_NUMERIC, 'en_US')``. .. versionchanged:: 3.1 Added the ``','`` option (see also :pep:`378`). @@ -519,8 +520,10 @@ 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 group separators, provided that the locale has | - | | been properly set (see the :mod:`locale` module). | + | | digit group separators. Note that the default locale is | + | | not the system locale, and therefore, you must set, at a | + | | minimum, the ``LC_NUMERIC`` category (see the | + | | :mod:`locale` module for more information). | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -603,8 +606,10 @@ 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 group separators for the integral part of a | - | | number, provided that the locale has been properly set | - | | (see the :mod:`locale` module). | + | | number. Note that the default locale is not the system | + | | locale, and therefore, you must set, at a minimum, the | + | | ``LC_NUMERIC`` category (see the :mod:`locale` module | + | | for more information). | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. | From d3d2e8181977e07542d411a687774045bb387c52 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Mon, 18 May 2026 10:09:22 -0700 Subject: [PATCH 3/5] Address comment --- 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 593a1aae3e2e7e..3cd88a490ff800 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -524,9 +524,9 @@ 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 group separators. Note that the default locale is | - | | not the system locale, and therefore, you must set, at a | - | | minimum, the ``LC_NUMERIC`` category (see the | - | | :mod:`locale` module for more information). | + | | not the system locale. Depending on your use case, you | + | | may wish to set ``LC_NUMERIC`` (see the :mod:`locale` | + | | module for more information). | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -613,9 +613,9 @@ The available presentation types for :class:`float` and | | the current locale setting to insert the appropriate | | | digit group separators for the integral part of a | | | number. Note that the default locale is not the system | - | | locale, and therefore, you must set, at a minimum, the | - | | ``LC_NUMERIC`` category (see the :mod:`locale` module | - | | for more information). | + | | locale. Depending on your use case, you may wish to set | + | | ``LC_NUMERIC`` (see the :mod:`locale` module for more | + | | information). | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. | From 06bba17870b0845e531c3663bea09ee6e3a4ef8b Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Mon, 18 May 2026 15:32:45 -0700 Subject: [PATCH 4/5] Link to references in presentation type tables --- Doc/library/string.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 3cd88a490ff800..1fc2453e6469b4 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -472,10 +472,9 @@ of a number respectively. It can be one of the following: | | this option is not supported. | +---------+----------------------------------------------------------+ -For a locale-aware separator, use the ``'n'`` presentation type instead. -Note that the locale setting for numeric values must first be set using -the :mod:`locale` module, for example, -``locale.setlocale(locale.LC_NUMERIC, 'en_US')``. +For a locale-aware separator, use the ``'n'`` +:ref:`float presentation type ` or +:ref:`integer presentation type ` instead. .. versionchanged:: 3.1 Added the ``','`` option (see also :pep:`378`). @@ -521,12 +520,14 @@ The available integer presentation types are: | | In case ``'#'`` is specified, the prefix ``'0x'`` will | | | be upper-cased to ``'0X'`` as well. | +---------+----------------------------------------------------------+ - | ``'n'`` | Number. This is the same as ``'d'``, except that it uses | + | ``'n'`` | .. _n-format-integer: | + | | | + | | Number. This is the same as ``'d'``, except that it uses | | | the current locale setting to insert the appropriate | | | digit group separators. Note that the default locale is | | | not the system locale. Depending on your use case, you | - | | may wish to set ``LC_NUMERIC`` (see the :mod:`locale` | - | | module for more information). | + | | may wish to set :const:`~locale.LC_NUMERIC` using | + | | :func:`locale.setlocale` . | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -609,13 +610,15 @@ The available presentation types for :class:`float` and | | ``'E'`` if the number gets too large. The | | | representations of infinity and NaN are uppercased, too. | +---------+----------------------------------------------------------+ - | ``'n'`` | Number. This is the same as ``'g'``, except that it uses | + | ``'n'`` | .. _n-format-float: | + | | | + | | Number. This is the same as ``'g'``, except that it uses | | | the current locale setting to insert the appropriate | | | digit group separators for the integral part of a | | | number. Note that the default locale is not the system | | | locale. Depending on your use case, you may wish to set | - | | ``LC_NUMERIC`` (see the :mod:`locale` module for more | - | | information). | + | | :const:`~locale.LC_NUMERIC` using | + | | :func:`locale.setlocale` . | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. | From 5684a4889dcd4922f98e63bee9670ee6b08f72a2 Mon Sep 17 00:00:00 2001 From: Stefanie Molin <24376333+stefmolin@users.noreply.github.com> Date: Mon, 18 May 2026 15:46:57 -0700 Subject: [PATCH 5/5] Rephrase table entries --- Doc/library/string.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 1fc2453e6469b4..be968a3c53d843 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -526,8 +526,8 @@ The available integer presentation types are: | | the current locale setting to insert the appropriate | | | digit group separators. Note that the default locale is | | | not the system locale. Depending on your use case, you | - | | may wish to set :const:`~locale.LC_NUMERIC` using | - | | :func:`locale.setlocale` . | + | | may wish to set :const:`~locale.LC_NUMERIC` with | + | | :func:`locale.setlocale` before using ``'n'``. | +---------+----------------------------------------------------------+ | None | The same as ``'d'``. | +---------+----------------------------------------------------------+ @@ -617,8 +617,8 @@ The available presentation types for :class:`float` and | | digit group separators for the integral part of a | | | number. Note that the default locale is not the system | | | locale. Depending on your use case, you may wish to set | - | | :const:`~locale.LC_NUMERIC` using | - | | :func:`locale.setlocale` . | + | | :const:`~locale.LC_NUMERIC` with | + | | :func:`locale.setlocale` before using ``'n'``. | +---------+----------------------------------------------------------+ | ``'%'`` | Percentage. Multiplies the number by 100 and displays | | | in fixed (``'f'``) format, followed by a percent sign. |