Incomplete documentation of zero preceding width in format specification

The current description of zero preceding width in format is the following:

When no explicit alignment is given, preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types, excluding complex. This is equivalent to a fill character of '0' with an alignment type of '='.

This is not complete. Consider the next code snippet:

formats = (
    ' <+#20.0f',
    '<+#20.0f',
    '+#20.0f',

    ' <+#020.0f',
    '<+#020.0f',
    '+#020.0f',
    )

for fmt in formats:
    print(f'Format {fmt!r:>12}: {format(1, fmt)!r}')

It has the following output:

Format  ' <+#20.0f': '+1.                 '
Format   '<+#20.0f': '+1.                 '
Format    '+#20.0f': '                 +1.'
Format ' <+#020.0f': '+1.                 '
Format  '<+#020.0f': '+1.00000000000000000'
Format   '+#020.0f': '+000000000000000001.'

The first three lines do not precede width of 20 with zero, remaining three do. Lines 4 and 5 show that one can precede width with zero even if alignment is specified. Specifically:

1. If both fill char and alignment are present, then zero is ignored.
2. If only alignment is present, then zero sets omitted fill char to 0 (omitting fill char by default uses space as demonstrated by line 2).

Those two cases are not covered; line 6 shows the case covered by docs.

Present docs excludes complex numbers, but it is a bit tricky. One can precede width with zero only if both fill char and alignment are present (i.e., when it is ignored), otherwise an exception is raised. This case can be completely omitted as the same exception also happens when fill char itself is zero (f'{1+1j:0<+#20.0f}'). Instead, the fact that complex numbers cannot be zero-padded should be added to the description of fill char.

Linked PRs

• gh-132149

从 issue 中描述的格式规范文档开始，将其中关于零宽度的措辞与提供的 Python 示例进行比较。更新对显式填充字符和对齐组合的说明，并明确复数的限制，然后验证文档中的案例是否与所示输出一致。