Feature or enhancement

The format.__doc__ currently states

Return value.__format__(format_spec)

format_spec defaults to the empty string.
See the Format Specification Mini-Language section of help('FORMATTING') for
details.

I propose to change this to

Return type(value).__format__(value, format_spec)

Many built-in types implement format_spec according to the
Format Specification Mini-language. See help('FORMATTING').

If type(value) does not supply a method named __format__
and format_spec is empty, then str(value) is returned.
See also help('SPECIALMETHODS').

While I'm at it, I propose to also clarify the docstrings of object.__format__ and int.__format__. (See comment here for current behavior.)

Pitch

I saw this documentation today and it confused me as I tried to understand how to format bytes. The help prompted me to look at help('FORMATTING') which seemed misleading. Only after looking at the C-code of format() did I understand what was going on.

The main clarifications I added here was:

1. no, not all types support this
2. the behavior of object.__format__ and pointer to __format__ documentation.
3. type(value).__format__(...) is returned, not value.__format__(...)

Moreover, I propose to remove "format_spec defaults to the empty string", since this is shown already in "help()" through the function signature.

Previous discussion

• bpo-29526 Add reference to help('FORMATTING') in format() builtin #166
• Documenting format() function #73712

Note: Updated on 2022-09-03 to include @TeamSpen210's remark.
Note: Updated on 2022-09-05 to include @ericvsmith's remark.
Note: Updated on 2022-09-06 to include @TeamSpen210's remark.
Note: Updated on 2022-09-07 to include new findings upon reading the C code.