PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4416

jb2170 · 2025-05-08T01:09:58Z

New rebased PR with the correct branch name to avoid confusion (786 not 791).

Thank you Alyssa for sponsoring this!

There is a TODO section in the PEP that shall perish as the PEP is tweaked before accepting

Relevant discussions, issues, PRs linked

https://discuss.python.org/t/implement-precision-format-spec-for-int-type-data/80760
gh-74756: support precision field for integer formatting types cpython#131926
Add integer formatting code for fixed-width signed arithmetic (2's complement) cpython#74756
[Old] PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4365

Basic requirements (all PEP Types)

Standards Track requirements

📚 Documentation preview 📚: https://pep-previews--4416.org.readthedocs.build/pep-0786/

AA-Turner

I haven't read the content of the PEP yet, but a few notes:

peps/pep-0786.rst

AA-Turner · 2025-05-08T01:23:11Z

peps/pep-0786.rst

+
+* Format all lines to ~80 characters. I've left this formatting until we're happy with the contents.
+* RFC 2119 Style Specification? After all is said and done here.
+* Add Sergey and Raymond to the authors field, or is Thanks enough?


Perhaps easiest to ask them which they'd prefer?

It's better to give the formatspec one canonical ordering than permit an overly liberal rearrangeability. If commutativity were added, then as well as the messy description required for the docs for the particular case of `int` data, two people could write two different format spec that result in the same output and not realise it or agree, because they've written different things, leading to confusion etc.

hugovk · 2025-05-08T14:51:07Z

.github/CODEOWNERS

+peps/pep-0786.rst  @ncoghlan
 # ...
 peps/pep-0787.rst  @ncoghlan


We can remove this gap:

Suggested change

peps/pep-0786.rst @ncoghlan

# ...

peps/pep-0787.rst @ncoghlan

peps/pep-0786.rst @ncoghlan

peps/pep-0787.rst @ncoghlan

hugovk · 2025-05-08T14:51:45Z

peps/pep-0786.rst

@@ -0,0 +1,355 @@
+PEP: 786
+Title: Precision and Modulo-Precision Flag format specifiers for integer fields


Consistent case: https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change

Title: Precision and Modulo-Precision Flag format specifiers for integer fields

Title: Precision and modulo-precision flag format specifiers for integer fields

hugovk · 2025-05-10T15:13:20Z

peps/pep-0786.rst

+Rationale
+=========
+
+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.


Avoid Latin abbreviations: https://devguide.python.org/documentation/style-guide/#use-simple-language

Suggested change

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.

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.

hugovk · 2025-05-10T15:15:17Z

peps/pep-0786.rst

+    >>> "0o%.3o" % 18
+    '0o022'          # three octal digits, ideal for displaying a umask or file permissions
+
+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.


Suggested change

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.

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.

hugovk · 2025-05-10T15:16:43Z

peps/pep-0786.rst

+    >>> f"{x:#08b}"
+    '0b001100'       # we wanted 8 bits, not 6 :(
+
+One could attempt to argue that since the length of a prefix is known to always be 2, it can be accounted for manually by adding 2 to the desired number of digits. Consider however the following demonstrations of why this is a bad idea:


Suggested change

One could attempt to argue that since the length of a prefix is known to always be 2, it can be accounted for manually by adding 2 to the desired number of digits. Consider however the following demonstrations of why this is a bad idea:

One could attempt to argue that since the length of a prefix is known to always be two, it can be accounted for manually by adding two to the desired number of digits. Consider however the following demonstrations of why this is a bad idea:

hugovk · 2025-05-10T15:42:33Z

peps/pep-0786.rst

+    >>> f"{y:z#.8b}"
+    '0b[...1]11111111'
+
+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:


Suggested change

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:

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:

hugovk · 2025-05-10T15:45:43Z

peps/pep-0786.rst

+
+  Verdict:
+
+  - Whilst graphically attractive, ``!`` would add too much more clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.


"too much" or "much more" instead of "too much more"?

Suggested change

- Whilst graphically attractive, ``!`` would add too much more clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.

- Whilst graphically attractive, ``!`` would add too much clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.

Suggested change

- Whilst graphically attractive, ``!`` would add too much more clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.

- Whilst graphically attractive, ``!`` would add much more clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.

hugovk · 2025-05-10T15:46:00Z

peps/pep-0786.rst

+Backwards Compatibility
+=======================
+
+To quote :pep:`682`


Suggested change

To quote :pep:`682`

To quote :pep:`682`:

hugovk · 2025-05-10T15:46:15Z

peps/pep-0786.rst

+
+To quote :pep:`682`
+
+  The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected


Suggested change

The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected

The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected.

hugovk · 2025-05-10T15:46:26Z

peps/pep-0786.rst

+
+  The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected
+
+unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`


Suggested change

unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`

unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`:

jb2170 and others added 4 commits May 8, 2025 01:56

First main commit to PEP 791

9c0ef26

791 -> 786

4e0e75e

Add Alyssa as the sponsor of PEP 786

bd628a0

Update .github/CODEOWNERS adding @ncoghlan for PEP 786

ac5024d

jb2170 requested a review from a team as a code owner May 8, 2025 01:09

jb2170 mentioned this pull request May 8, 2025

[Old] PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4365

Closed

27 tasks

AA-Turner added the new-pep A new draft PEP submitted for initial review label May 8, 2025

AA-Turner requested a review from ncoghlan May 8, 2025 01:19

AA-Turner reviewed May 8, 2025

View reviewed changes

jb2170 added 2 commits May 8, 2025 03:29

Address AA-Turner's notes

3ca6120

hugovk reviewed May 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4416

PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4416

jb2170 commented May 8, 2025 •

edited by hugovk

Loading

AA-Turner left a comment

AA-Turner May 8, 2025

hugovk May 8, 2025

hugovk May 8, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

hugovk May 10, 2025

		@@ -0,0 +1,355 @@
		PEP: 786
		Title: Precision and Modulo-Precision Flag format specifiers for integer fields

	One could attempt to argue that since the length of a prefix is known to always be 2, it can be accounted for manually by adding 2 to the desired number of digits. Consider however the following demonstrations of why this is a bad idea:
	One could attempt to argue that since the length of a prefix is known to always be two, it can be accounted for manually by adding two to the desired number of digits. Consider however the following demonstrations of why this is a bad idea:

	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:
	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:


		Verdict:

		- Whilst graphically attractive, ``!`` would add too much more clutter to the format specification for a purpose that can be achieved by overloading the preexisting ``z`` flag.


		To quote :pep:`682`

		The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected


		The new formatting behavior is opt-in, so numerical formatting of existing programs will not be affected

		unless someone out there is specifically relying upon ``.`` raising a ``ValueError`` for integers as it currently does, but to quote :pep:`475`

PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4416

Are you sure you want to change the base?

PEP 786: Precision and Modulo-Precision Flag format specifiers for integer fields #4416

Conversation

jb2170 commented May 8, 2025 • edited by hugovk Loading

Basic requirements (all PEP Types)

Standards Track requirements

AA-Turner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jb2170 commented May 8, 2025 •

edited by hugovk

Loading