python · james-emerton · Jan 27, 2019 · Jan 27, 2019
diff --git a/pep-9999.rst b/pep-9999.rst
@@ -0,0 +1,128 @@
+PEP: 9999
+Title: Format Specifier for Locale Specific Grouping
+Version: $Revision$
+Last-Modified: $Date$
+Author: James Emerton
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 4-Aug-2018
+Python-Version: 3.8
+Post-History: 4-Aug-2018
+
+
+Abstract
+========
+
+This PEP proposes to extend the string formatting syntax to support a
+fixed-point format specifier using locale-aware grouping and decimal
+place characters.
+
+
+Rationale
+=========
+
+Python already supports adding thousands separators (grouping) in a non-locale
+aware manner via the ``,`` [1]_ and ``_`` [2]_ modifiers, as well as a locale
+aware format type ``n`` that uses locale aware grouping for thousands
+separators but will render large numbers using exponential notation.
+
+Exponential notation is not approprate for many applications including
+financial software, where grouping would increase the legibility of a
+number presented to the user.
+
+While it is possible to use the existing grouping modifiers to format a
+number and subsequently replace the separators with the appropriate values
+as per the locale data, this does not address locales where the grouping may
+not occur every three digits.
+
+Finally, there exists ``locale.format_string()`` [3]_ but this is built upon
+%-formatting which will coerce ``Decimal`` values to floating point and can
+result in incorrect results for values which cannot accurately be represented
+by the floating point format.
+
+
+Proposal
+========
+
+A single-quote would be added to the format() specifier mini-language and
+could be used in place of the comma or underscore. The presence of this
+character will enable locale specific grouping as well as the locale specific
+decimal point character.
+
+This modifier can be combined with the 'd', 'e', 'f', 'g', 'E', 'G', '%' and
+'F' types.
+
+Examples
+--------
+
+    >>> locale.setlocale(locale.LC_ALL, 'en_US')
+    >>> format(12345, "'f")
+    12,345
+    >>> format(12345.67, "'f")
+    12,345.000000
+    >>> format(12345.67, "'.2f")
+    12,345.67
+
+    >>> locale.setlocale(locale.LC_ALL, 'de_DE')
+    >>> format(12345, "'f")
+    12.345
+    >>> format(12345.67, "'.2f")
+    12.345,67
+    >>> format(12345.67, "'.2e")
+    1,23e+4
+
+
+Prior Art
+=========
+
+The use of ``'`` for this purpose is already the established practice as per
+the Single UNIX Specification as is implemented for printf() in glibc and
+others. [4]_
+
+
+Draft Implementation
+====================
+
+A draft implementation for the Decimal type is currently available in PR 8612. [5]_
+
+Another implementation created independently is also available as PR 11405. [6]_
+
+Monetary vs Non-Monetary Formats
+================================
+
+There are a very small number of locales that differentiate between the format
+of monetary (``LC_MONETARY``) and non-monetary (``LC_NUMERIC``) values. The
+C99 specification does not appear to offer any mechanism to indicate that
+monetary formatting is required, and thus this implementation also omits
+monetary formats.
+
+
+Alternative Proposals
+=====================
+
+A number of other suggestions for the actual format character or modifier have
+been suggested:
+
+  * My original implementation used ``l`` (non-monetary) and ``L`` (monetary)
+    format characters
+
+  * The alternate implementation in PR 11405 uses ``m`` format character
+
+  * Stefan Krah proposed the use of ``$n``
+
+
+References
+==========
+
+.. [1] https://www.python.org/dev/peps/pep-0378/
+
+.. [2] https://www.python.org/dev/peps/pep-0515/
+
+.. [3] https://docs.python.org/3/library/locale.html#locale.format_string
+
+.. [4] http://man7.org/linux/man-pages/man3/printf.3.html
+
+.. [5] https://github.com/python/cpython/pull/8612
+
+.. [6] https://github.com/python/cpython/pull/11405