Text formatting error: '=' alignment not allowed in string format specifier

The error message occurs because '=' alignment has been implied by the format specifier.

The str.format format spec mini-language parser has decided on the alignment specifier “=” because:

Preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types. This is equivalent to a fill character of '0' with an alignment type of '='.

So by specifying 0N as the “zero-padding to N width”, you have implied both “the input is a numeric type”, and “the zeros should go between the sign and the digits”. That latter implication is what is meant by '=' alignment.

Since the value "1" is not numeric, the “=”-alignment handling code raises that exception. The message is written expecting you know what it's talking about because you requested (by implication) the “=” alignment.

Yes, I think that error message needs to be improved. I've raised an issue for that.

str.__format__ doesn't know what to do with your 03 part. That only works with numbers:

>>> "{num:03}".format(num=1)
'001'

If you actually want to zero-pad a string, you can use rjust:

>>> "1".rjust(3, "0")
'001'

A workaround is to use '>' (right justify) padding, which is with the syntax:

[[fill]align][width]

with align being >, fill being 0 and width being 3.

>>> "{num:0>3}".format(num="1")
'001'

The problem was that there is a different 0 in the format specification:

format_spec     ::=  [[fill]align][sign][#][0][width][grouping_option][.precision][type]
#                                          ^^^ This one

That zero just makes fill default to 0 and align to =.

= alignment is specified as:

Forces the padding to be placed after the sign (if any) but before the digits. This is used for printing fields in the form ‘+000000120’. This alignment option is only valid for numeric types. It becomes the default when ‘0’ immediately precedes the field width.

Source (Python 3 docs)

This expects the argument to be an int, as strings don't have signs. So we just manually set it to the normal default of > (right justify).

Also note that 0 just specifies the default values for fill and align. You can change both or just the align.

>>> # fill defaults to '0', align is '>', `0` is set, width is `3`
>>> "{num:>03}".format(num=-1)
'0-1'
>>> # fill is `x`, align is '>', `0` is set (but does nothing), width is `"3"`
>>> "{num:x>03}".format(num=-1)
'x-1'
>>> # fill is `x`, align is '>', `0` is set (but does nothing), width is `"03"` (3)
>>> "{num:x>003}".format(num=-1)
'x-1'