When formatting an integer as a hexadecimal value, the '#' alternate form modifier inserts a preceding '0x'. 
If this is used in combination with padding modifiers, the '0x' is counted as part of the overall width, which does not feel like the natural behaviour as extra calculation is required to get the correct post '0x' precision.

Example:

In [7]: f'{num:04x}'
Out[7]: '0800'

In [8]: f'{num:#04x}'
Out[8]: '0x800'

To get the hexadecimal representation padded to 4 digits, you have to account for the preceding 0x:

In [10]: f'{num:#06x}'
Out[10]: '0x0800'

Yes, the width is the width of the formatted value, not the number of digits.

What is your proposition?

int.__format__ inherits this from %-formatting, which inherits it from C's printf.

There's no way we're going to change this at this point: the breakage would be too great. So, I'm going to reject this.

Now that I re-read this, maybe it was a documentation request, not a functional change? I'd be okay with documenting the existing behavior, so I'll re-open this and change the type. Patches welcome.

The width doesn't mean "the number of bits", it means "the width of the field". In every other case too:

* when we format negative numbers, width includes the minus sign
* when we format decimal numbers, width includes decimal point (or comma)
* when we format strings with !r, width includes the quotes

So, not only would it break too much code, but it would actually be inconsistent to formatting all other types currently.

Given the comments above I appreciate that this is actually due to the padding being the total field width rather than the padding of the digits themselves. Having revised the documentation again, I believe this following line is explaining it:

"When no explicit alignment is given, 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 '='."

(https://docs.python.org/3.8/library/string.html)

I initially read "sign-aware zero-padding for numeric types" to mean the padding would not blindly prepend, and would take into account any signs and pad after (hence initially making this a bug). So maybe as suggested above we should explicitly mention the padding is the total number of characters in the field, rather than just the numbers.

I can look into adding this soon and see what you all think.

It seems that you're confusing two things that really don't have much in common.

* (field) width is a _number_, saying how many characters (at least) should the formatted output take.
* padding is a bool (or maybe a char), saying what should be put inside the leftover space if the default formatted output is shorter than the width

The padding is not the width, and the width is not the padding. Once you start to differentiate those two things, I'm convinced all your confusions will disappear.

New changeset 424e5686d82235e08f8108b8bbe034bc91421689 by Pete Wicken in branch 'master':
bpo-38657: Clarify numeric padding behaviour in string formatting (GH-17036)
https://github.com/python/cpython/commit/424e5686d82235e08f8108b8bbe034bc91421689

New changeset 09db1da63f866afff8a64ae3c60acdcd6bc80501 by Miss Islington (bot) in branch '3.7':
bpo-38657: Clarify numeric padding behaviour in string formatting (GH-17036)
https://github.com/python/cpython/commit/09db1da63f866afff8a64ae3c60acdcd6bc80501

New changeset a2075121217e809c9a5511f6ca225c12f340de0c by Miss Islington (bot) in branch '3.8':
bpo-38657: Clarify numeric padding behaviour in string formatting (GH-17036)
https://github.com/python/cpython/commit/a2075121217e809c9a5511f6ca225c12f340de0c

It looks as though this has been addressed, and can be closed.