Repository navigation
Improve printf-style formatting docs for non-built-in types #142108
Description
Activity
For
__format__, Decimal is formatted with the highest possible precision.It's just not true. Only when precision is omitted in f/e/g formats. This is documented.
For % formatting, Decimal is converted to float before formatting.
This is not specific to Decimal's at all:
>>> class A: ... def __int__(self): ... return 42 ... def __float__(self): ... return 1.25 ... >>> "%.10f" % A() '1.2500000000' >>> "%d" % A() '42'
Old-style formatting is documented here: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting
Maybe rules are obvious, yet they aren't documented. N.B.: implementation is in the Objects/unicode_format.c
I'd like to work on this. I'll add clarification about Decimal's formatting behavior to the format specification docs.
When we have a
pendinglabel, usually this means that we still don't know whether this is triaged. AFAICT, what the OP described as an issue was not an issue. IMO, there is nothing to do (unless @skirpichev had something precise in mind?)Sorry, perhaps I wasn't clear.
Documentation for printf-style formatting lacks description of rules to format non-builtin types. @picnixz, if such rules are obvious for you - perhaps there is no issue.
Oh if for non-built-in types, we don't document
%-format, then yes I'm fine with documenting them. But I don't really where we would put them. I think we can amend theprintf-style sections forstrandbytesto say something like:For non built-in types, for instance,
%dcalls the__int__method of the value to convert to get itsintrepresentation to format.The above sentence is clearly not perfect and I would rather have something equivalent and better but that convenes this intent (that is, we have an implicit conversion).
- changed the title
[-]Add a description about how Decimal behaves differently with __format__ and % formatting[/-][+]Improve `printf`-style formatting for non-built-in types[/+]on Nov 30, 2025 - changed the title
[-]Improve `printf`-style formatting for non-built-in types[/-][+]Improve `printf`-style formatting docs for non-built-in types[/+]on Nov 30, 2025 But I don't really where we would put them.
We have a dedicated section for
%-formatting: https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting%d calls the
__int__method of the value to convert to get its int representation to format.Yes, something like that. Though, logic is much more complex, e.g. for integer formatting types:
cpython/Objects/unicode_format.c
Lines 297 to 317 in 229ed3d
(For floats it's more close to
float(obj)for non-stringobj's.)For
%o& co, it's actually documented inobject.__index__but it's honestly better if we were to indicate this in the printf-style section. So I'm in favor of having something that really explains the logic at the same place (I guess the entire thing is documented but probably in differnt places which makes it very hard to search)I discovered the formatting difference while investigating #142019
I found this document first:
https://docs.python.org/3/library/string.html#format-specification-mini-language.When I tried to find another document, I searched for '% format'
and '% formatting' but found nothing related to
https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting.I misunderstood that there is only one document about formatting,
and that the basic functionalities of the format-specification mini-language are also applicable to % formatting,
except for some additional functions.Perhaps a note could be added at the beginning of
https://docs.python.org/3/library/string.html#format-specification-mini-language
stating that this is not suitable for % formatting, along with a link back to
https://docs.python.org/3/library/stdtypes.html#printf-style-string-formattingFor %o & co, it's actually documented in
object.__index__Not, unless I misread it:
Called to implement operator.index(), and whenever Python needs to losslessly convert the numeric object to an integer object (such as in slicing, or in the built-in bin(), hex() and oct() functions).
But you are right, in sense that we could reference to this logic in formatting docs.
Perhaps a note could be added at the beginning of https://docs.python.org/3/library/string.html#format-specification-mini-language stating that this is not suitable for % formatting
I don't think we need this.
I don't think we need this.
Why? Because this old formatting syntax is not encouraged to be used?
Format specifications and printf-style are different. One is for
fmt % value, the other is forformat()orstr.format.I don't think this is issue is very newcomer friendly actually. It requires quite a deep knowledge in the subtle terms as well as knowledge in the implementation. I would suggest either @skirpichev or me to document this but I don't have much time.
Not, unless I misread it:
It's not explicitly stated, but I would have assumed that mention to
bin/hex/octcombined with "whenever Python needs to losslessly convert the numeric object to an integer object" actually covered this. Actually theoctdocs say:Convert an integer number to an octal string prefixed with “0o”.
[...]
If you want to convert an integer number to an octal string either with the prefix “0o” or not, you can use either of the following ways.'%#o' % 10, '%o' % 10 ('0o12', '12') format(10, '#o'), format(10, 'o') ('0o12', '12') f'{10:#o}', f'{10:o}' ('0o12', '12')So I guess we could say it's documented, though maybe a bit hard to find.
Reacted by Sergey B KirpichevWhy?
Because we can't clutter docs with notes each time someone misread them in some way.
I would suggest either @skirpichev or me to document this but I don't have much time.
I think it's a good opportunity to learn. There is an open pr, lets see if @Yashp002 will read discussion thread and address review comments.
If not, I'll try to finish this.
BTW,
'%#o' % 10, '%o' % 10
Side story. Should we promote old-style formatting in usual examples? I don't think so.
I believe there should at least be a link to #printf-style-string-formatting in #format-specification-mini-language.
Or maybe replace the literal %-formatting in #format-examples by a linkThis section contains examples of the str.format() syntax and comparison with the old %-formatting.
I didn't realize #printf-style-string-formatting exists, until @skirpichev mentioned it.
When I tried to find another document, I searched for '% format'
and '% formatting' but found nothing related to
https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting.The built-in document search engine is basically useless when it comes to searching for symbols and multiple keywords.
I guess it doesn't hurt to also backreference
%-style informat-style with a single sentence at the end of the first paragraph. "For old-style formatting, see [...]".Side story. Should we promote old-style formatting in usual examples? I don't think so.
Personally, I use old-style formatting because it's easier to me to read. There is a real visual benefit IMO where I can more easily parse
%tokens rather than{varname}. So while I understand that people don't always like old-style formatting I do use it myself if needed (it's especially useful for double-formatting;(fmt % args).format(after), which happens when you want to pre-compute the width of your field (it's possible to do it with f-strings but it's unreadable to me honestly).Or maybe replace the literal %-formatting in #format-examples by a link
Seems fine.
I didn't realize #printf-style-string-formatting exists
It depends on how you read the docs. Starting from the Tutorial here you will quickly navigate to both pages.
Hi, I attempted a PR but realized after review that I may have misunderstood the scope of this issue.
The issue title mentions "printf-style formatting" (% operator) but the linked doc section is about the Format Specification Mini-Language (format / f-strings / .format()).
Could you clarify:
- Should the documentation changes be in the printf-style docs instead? (https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting)
- Or is the goal to document Decimal's behavior in the Format Spec section and clarify the % vs format difference there?
- Or is this already documented elsewhere and no changes are needed?
Add a description about how Decimal behaves differently with format and % formatting in https://docs.python.org/3/library/string.html#format-specification-mini-language
For __format__, Decimal is formatted
with the highest possible precisionas it is.For % formatting, Decimal is converted to float before formatting.
These behaviors have not changed since they were added.
Compare:
sys.version'%f' % 11111111111111111111.0'%f' % Decimal('11111111111111111111.0')Decimal('11111111111111111111.0').__format__('f')'%e' % 0.0'%e' % Decimal('0.0')Decimal('0.0').__format__('e')'%.20e' % 11111111111111111111.0'%.20e' % Decimal('11111111111111111111.0')Decimal('11111111111111111111.0').__format__('.20e')'%.20g' % 11111111111111111111.0'%.20g' % Decimal('11111111111111111111.0')Decimal('11111111111111111111.0').__format__('.20g')Linked PRs