Short Verdict

We desire two behaviors, which motivates the implementation of a flag z to toggle on the latter’s behavior:

• For precision without the z flag, a negative integer x shall be formatted with a negative sign and the digits of -x’s formatting. This is the same friendly behavior as old-style % formatting.

  For example f"{-12:#.2x}" shall produce '-0x0c', equivalent to "%#.2x" % -12.

• For precision with the z flag, r = x % base ** n is first taken when formatting f"{x:z.{n}{base_char}}", and r is passed on to precision, the resulting string being equivalent to f"{r:.{n}{base_char}}". Because r is in range(base ** n) the number of digits will always be exactly n, resulting in a predictable two’s complement style formatting, which is useful to the end user in environments that deal with machine-width oriented integers such as struct.

  For example in formatting f"{-1:z#.2x}", -1 is reduced modulo 256 via 255 = -1 % 256, the resulting string being equivalent to f"{255:#.2x}", which is '0xff'.

  The z flag shall only be implemented for presentation types corresponding to bases that are powers of two, specifically at present binary, octal, and hexadecimal. Whilst reduction of integers modulo by powers of ten is computationally possible, a ‘ten’s complement?’ has no demand and so precision is unimplemented for decimal presentation types. The z flag shall work for all integers, not just negatives.

  The syntax choice of z is again out of respect for maintaining the modest size of the format specification. z was introduced to the format specification in PEP 682 as a flag for normalizing negative zero to positive zero for the float and Decimal types. It is currently unimplemented for the int type, and since integers never have a ‘negative zero’ situation it seems uncontroversial to repurpose z, again as a flag. If one squints hard enough, the z looks like a 2 for two’s complement!

Long Introspection

We first present some observations about the binary representations of signed integers in two’s complement. This leads us to a couple of alternative formulations of formatting negative numbers.

Observe that one can always extend a signed number’s binary representation by extending the the leading digit as a prefix:

 45 (8-bit)  00101101
 45 (9-bit) 000101101
-19 (8-bit)  11101101
-19 (9-bit) 111101101

For non-negative numbers this is obvious. For negative numbers this is because the erstwhile leading column of an n-bit representation goes from having a value of -2 ** (n-1), to +2 ** (n-1), with a new n+1th column of value -2 ** n prefixed on, the overall sum unaffected.

This is what C’s printf does, working with powers of two as the numbers of digits:

printf("%#hhb\n", -19); // 0b11101101
printf("%#hho\n", -19); // 0355
printf("%#hhx\n", -19); // 0xed

printf("%#b\n",   -19); // 0b11111111111111111111111111101101
printf("%#o\n",   -19); // 037777777755
printf("%#x\n",   -19); // 0xffffffed

Conversely it should be clear that one can losslessly truncate a signed number’s binary representation to have only one leading 0 if it is non-negative, and one leading 1 if it is negative:

 45 (8-bit)  00101101
 45 (7-bit)   0101101
-19 (8-bit)  11101101
-19 (7-bit)   1101101

If one were to truncate another digit off of these examples, then both would end up as 101101, 45 being indistinguishable from -19 when using only 6 binary digits because they are both the same modulo 2 ** 6 = 64. Therefore to losslessly and unambiguously represent a signed integer x as a binary string which is rendered to the end user, we have a de facto ‘minimal width’ representation convention, using n digits, where n is the smallest integer such that x is in range(-2 ** (n-1), 2 ** (n-1)).

For rendering octal and hexadecimal strings one has to extend the definition of the ‘minimal width’ representation convention to be sufficiently unambiguous. 383’s minimal width binary string is 0101111111, and -129’s is 101111111, a suffix of the former’s. A naive, incorrect, implementation of hexadecimal string formatting would render both as '0x17f' by padding both binary representations to 000101111111. The method was correct to desire a number of binary digits (12) that is divisible by the number of bits in the base (4 bits in base 16) so that the binary representation can be segmented up into (hex) digits, but it was incorrect in padding; the method should have instead extended as we have observed previously, 383 extended to 000101111111, and -129 extended to 111101111111, whence 383 is rendered as '0x17f' and -129 as 0xf7f.

Thus the generalized definition of our ‘minimal width’ representation convention is: for an integer x to rendered in base base, produce n digits, where n is the smallest integer such that x is in range(-base ** n / 2, base ** n / 2).

This leads onto the rejected alternatives.

Minimal Width Representation Convention

This idea was fiercely entertained only due to its lossless behavior, however it is a obstacle to ergonomics in every candidate use case. These arguments about the aesthetics of string rendering are not irrational or about personal taste, but rather they are crucial in how information is communicated to the end user.

In a program in which signed-ness of integers is critical to communicate, any implementation of z should not be used, as the average user will be expecting to see a negative sign -. The alternative of using minimal width representation convention requires one to be uncomfortably vigilant looking for leading digits of numbers belonging to the upper half of the base’s range whenever a negative number is present (1 for binary, 4-7 for octal, and 8-f for hex). Any end user that is not aware of this de facto convention, and even those who are but are not expecting it to be present in a program, would have a hard time:

The formatting of 128 and -128 using f"{x:z#.2x}" would produce '0x080' and '0x80' respectively. It is the PEP author’s opinion that there is a 0% chance that '0x80' is being read as negative 128 under normal conditions. Furthermore the hideous rendering of positive 128 as '0x080' is useless for a program that should produce a uniformly spaced hexdump of bytes, agnostic of whether they are signed or unsigned; all bytes should be rendered in the form '0xNN'. See the examples section on how modulo-precision handles bytes in the correct sign-agnostic way.

Contrapositively therefore z’s purpose is to be used in environments where signed-ness is not critical, and more likely than not where it is even encouraged to treat the integers with respect to the modular arithmetic that arises in two’s complement hardware of fixed register sizes. In the example above 128 and -128 are the same modulo 256, and the respectable rendering is '0x80'. In general the purpose of z is to treat integers modulo base ** precision as the same. So too 255 and -1 should both be rendered as '0xff', not '0x0ff' and '0xff' respectively; the truncation is not a hindrance, but the desired behavior. Formally we may say that the formatting should be a well defined bijection between the equivalence classes of Z/(base ** precision)Z and strings with precision digits.

The remaining question is “is there no chance to communicate this truncation to the user?” as a concern for the ‘loss of information’ arising from the effectively left-truncated strings. We reject this question’s premise that there ever is such a case of unintentional loss of information, by considering the two cases of hardware-aware integers and otherwise:

With respect to hardware-aware integers we have so far played around with examples of integers in range(-128, 256), the union of the signed and unsigned ranges for bytes. The virtues of formatting x and x - 256 as the same are clearly established. In these contexts that one expects to find z, any erroneous integers corresponding to bytes that lie outside that range are likely a programming error. For example if a library sets a pixel brightness integer to be 257, and prints out '0x01' instead of '0x101' via f"{x:z#.2x}", that’s not our problem or doing; string formatting shouldn’t raise an exception, or even a SyntaxWarning as an invalid escape sequence "\y" would, because ValueError: bytes must be in range(0, 256) will be raised by bytes when trying to serialize that integer via bytes([257]); let the appropriate ‘layer’ of code raise the exception, as that is more indicative of a defect in the library, not our string formatting.

In the case of non-hardware aware integers, one would have to intentionally opt to use z, in which modular arithmetic is the chosen desired effect. It is for this reason also that we shall not raise a SyntaxWarning or ValueError for integers lying outside of range(-base ** precision / 2, base ** precision).

Thus we have defended the lossy behavior of z implemented as modulo-precision, and we have exhausted all reasonable use cases of lossless behavior.

A final compromise to consider and reject is implementing z not as a flag contingent on ., but as a flag that can be combined with .. Specifically: z without . would turn on two’s complement mode to render the minimal width representation of the formatted integer, . without z would implement precision as already explained, a minimum number of digits in the magnitude and a sign if necessary, and z combined with . would turn on the left-truncating modulo-precision. This labyrinth of combinations does not seem useful to anyone, as we have already discredited the ergonomics of minimal width representation convention, whence z would rarely be used on its own, and this behavior of two options that individually render a minimum number of digits combining together to render an exact number of digits seems counterintuitive.

Infinite Length Indication

Another, less popular, rejected alternative was for z to directly acknowledge the infinite prefix of 0s or 1s that precede a non-negative or negative number respectively. For example:

>>> f"{-1:z#.8b}"
'0b[...1]11111111'
>>> f"{300:z#.8b}"
'0b[...0]100101100'

This is effectively the minimal width representation convention with an ‘infinite’ prefix attached to it.

In the C programming language the machine-width dependent two’s complement formatting of int data with precision exhibits excessive lengths of prefixes that arise from negative numbers, even those with small magnitude:

printf("%#.2x\n", -19); // 0xffffffed
printf("%#.2llx\n", (long long unsigned int)-19); // 0xffffffffffffffed

This prefix could continue on indefinitely if it were not limited by a maximum machine-width!

Python’s int type is indeed not limited by a maximum machine-width. Thus to avoid printing infinitely long two’s complement strings we could use a similar approach to that of the builtin list’s string formatting for printing a list that contains itself:

>>> l = []
>>> l.append(l)
>>> l
[[...]]

>>> y = -1
>>> f"{y:z#.8b}"
'0b[...1]11111111'

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:

>>> x = 42
>>> f"{x:z#.8b}"
'0b[...0]00101010'
>>> f"{~x:z#.8b}"
'0b[...1]11010101'
>>> f"{x|~x:z#.8b}"
'0b[...1]11111111'
# x | ~x == -1
# x | ~x == x + ~x because of their disjoint bitwise representations
# thus x + ~x == -1
# thus -x == ~x + 1
>>> y = ~x + 1
>>> f"{y:z#.8b}"
'0b[...1]11010110'
>>> y == -x
True

Its use case is just too narrow, and modulo-precision outshines it.