You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: peps/pep-0786.rst
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
PEP: 786
2
-
Title: Precision and Modulo-Precision Flag format specifiers for integer fields
2
+
Title: Precision and modulo-precision flag format specifiers for integer fields
3
3
Author: Jay Berry <email@jb2170.com>
4
4
Sponsor: Alyssa Coghlan <ncoghlan@gmail.com>
5
5
Status: Draft
@@ -22,7 +22,7 @@ This PEP amends the clause of :pep:`3101` which states "[t]he precision is ignor
22
22
Rationale
23
23
=========
24
24
25
-
When string formatting integers in binary octal and hexadecimal, one often desires the resulting string to contain a guaranteed minimum number of digits. For unsigned integers of known machine-width bounds (eg 8 bit bytes) this often also ends up the exact resulting number of digits. This has previously been implemented in the old-style ``%`` formatting using the ``.`` "precision" format specifier, closely related to that of the C programming language.
25
+
When string formatting integers in binary octal and hexadecimal, one often desires the resulting string to contain a guaranteed minimum number of digits. For unsigned integers of known machine-width bounds (for example, 8-bit bytes) this often also ends up the exact resulting number of digits. This has previously been implemented in the old-style ``%`` formatting using the ``.`` "precision" format specifier, closely related to that of the C programming language.
26
26
27
27
.. code-block:: python
28
28
@@ -31,7 +31,7 @@ When string formatting integers in binary octal and hexadecimal, one often desir
31
31
>>>"0o%.3o"%18
32
32
'0o022'# three octal digits, ideal for displaying a umask or file permissions
33
33
34
-
When :pep:`3101` new-style formatting was first introduced, used in ``str.format`` and ``f``\ strings, the `format specification <formatspec_>`_ was simple enough that the behavior of "precision" could be trivially emulated with the ``width`` format specifier. Precision therefore was left unimplemented and forbidden for ``int`` fields. However, as time has progressed and new format specifiers have been added, whose interactions with ``width`` noticeably diverge its behavior away from emulating precision, the readmission of precision as its own format specifier, ``.``, is sufficiently warranted.
34
+
When :pep:`3101` new-style formatting was first introduced, used in ``str.format`` and f-strings, the `format specification <formatspec_>`_ was simple enough that the behavior of "precision" could be trivially emulated with the ``width`` format specifier. Precision therefore was left unimplemented and forbidden for ``int`` fields. However, as time has progressed and new format specifiers have been added, whose interactions with ``width`` noticeably diverge its behavior away from emulating precision, the readmission of precision as its own format specifier, ``.``, is sufficiently warranted.
35
35
36
36
The ``width`` format specifier guarantees a minimum length of the entire replacement field, not just the number of digits in a formatted integer. For example, the wonderful ``#`` specifier that prepends the prefix of the corresponding presentation type consumes from ``width``:
37
37
@@ -54,7 +54,7 @@ One could attempt to argue that since the length of a prefix is known to always
54
54
55
55
It is clear at this point that the reduction of complexity that would be provided by precision's implementation for ``int`` fields would be beneficial to any user. Nor is this proposal a new special-case behavior being demanded exclusively at the behest of ``int`` fields: the precision token ``.`` is already implemented as prescribed in :pep:`3101` for ``str`` data to truncate the field's length, and for ``float`` data to ensure that there are a fixed number of digits after the decimal point, eg ``f"{0.1+0.2: .4f}"`` producing ``' 0.3000'``. Thus no new tokens need adding to the `format specification <formatspec_>`_ because of this proposal, maintaining its modest size.
56
56
57
-
For the sake of completion, and lack of any reasonable objection, we propose that precision shall work also in decimal, base 10. Explicitly, the integer presentation types laid out in :pep:`3101` that are permitted to implement precision are ``'b'``, ``'d'``, ``'o'``, ``'x'``, ``'X'``, ``'n'``, and ``'' (None)``. The only presentation type not permitted is ``c`` ('character'), whose purpose is to format an integer to a single Unicode character, or an appropriate replacement for non-printable characters, for which it does not make sense to implement precision. In the event that new integer presentation types are added in the future, such as ``'B'`` and ``'O'`` which mutatis-mutandis could provide the same behavior as ``'X'`` (that is a capitalized prefix and digits), their addition should appropriately consider whether precision should be implemented or not. In the case of ``'B'`` and ``'O'`` as described here it would be correct to implement precision. A ``ValueError`` shall be raised when precision is attempted to be used for invalid integer presentation types.
57
+
For the sake of completion, and lack of any reasonable objection, we propose that precision shall work also in decimal, base 10. Explicitly, the integer presentation types laid out in :pep:`3101` that are permitted to implement precision are ``'b'``, ``'d'``, ``'o'``, ``'x'``, ``'X'``, ``'n'``, and ``''`` (``None``). The only presentation type not permitted is ``c`` ('character'), whose purpose is to format an integer to a single Unicode character, or an appropriate replacement for non-printable characters, for which it does not make sense to implement precision. In the event that new integer presentation types are added in the future, such as ``'B'`` and ``'O'`` which mutatis-mutandis could provide the same behavior as ``'X'`` (that is a capitalized prefix and digits), their addition should appropriately consider whether precision should be implemented or not. In the case of ``'B'`` and ``'O'`` as described here it would be correct to implement precision. A ``ValueError`` shall be raised when precision is attempted to be used for invalid integer presentation types.
58
58
59
59
60
60
Precision For Negative Numbers
@@ -166,7 +166,7 @@ A final compromise to consider and reject is implementing ``z`` not as a flag *d
166
166
Infinite Length Indication
167
167
''''''''''''''''''''''''''
168
168
169
-
Another, less popular, rejected alternative was for ``z`` to directly acknowledge the infinite prefix of ``0``\ s or ``1``\ s that precede a non-negative or negative number respectively. For example
169
+
Another, less popular, rejected alternative was for ``z`` to directly acknowledge the infinite prefix of ``0``\ s or ``1``\ s that precede a non-negative or negative number respectively. For example:
170
170
171
171
.. code-block:: python
172
172
@@ -199,7 +199,7 @@ Python's ``int`` type is indeed not limited by a maximum machine-width. Thus to
199
199
>>>f"{y:z#.8b}"
200
200
'0b[...1]11111111'
201
201
202
-
This may have been useful to educate beginner users on how bitwise binary operations work, for example showing how ``-1 & x`` is always trivially equal to ``x``, or how the binary representation of the negation of a number can be obtained by adding one to its bitwise complement:
202
+
This may have been useful to educate beginners on how bitwise binary operations work, for example showing how ``-1 & x`` is always trivially equal to ``x``, or how the binary representation of the negation of a number can be obtained by adding one to its bitwise complement:
203
203
204
204
.. code-block:: python
205
205
@@ -264,11 +264,11 @@ Syntax
264
264
Backwards Compatibility
265
265
=======================
266
266
267
-
To quote :pep:`682`
267
+
To quote :pep:`682`:
268
268
269
-
The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected
269
+
The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected.
270
270
271
-
unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`
271
+
unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`:
272
272
273
273
The authors of this PEP don't think that such applications exist
0 commit comments