Improve TypeError hints for %-formats

Bug report

Bug description:

>>> "%.f"%(1+1j)
Traceback (most recent call last):
  File "<python-input-27>", line 1, in <module>
    "%.f"%(1+1j)
    ~~~~~^^~~~~~
TypeError: must be real number, not complex
>>> "%.d"%(1+1j)
Traceback (most recent call last):
  File "<python-input-28>", line 1, in <module>
    "%.d"%(1+1j)
    ~~~~~^^~~~~~
TypeError: %d format: a real number is required, not complex

As you can see, trying to format a complex with .d and .f produces two outputs with the same meaning but different expressions.
Expected: same expressions for same meaning.

CPython versions tested on:

3.14

Operating systems tested on:

Windows

Linked PRs

I'm quite confident that this issue hasn't been submitted yet; at least I haven't found any related issue in the Issues page

"must be real number" is more general, it is produced in PyFloat_AsDouble(), i.e. it is used in many other cases when a real number is expected and will be implicitly converted to floating-point.

"%d format: a real number is required" is more specific, it is produced in str.__mod__. It contains more information and is similar to error messages for %o and %x which require an integer. So this message is preferable.

We can also use opportunity to improve other error messages.

pythongh-142037: Improve error messages for printf-style formatting

#142081 does much more than bringing the error message for floating point formatting in consistency with others. It adds the number or the name of the argument in the error messages related to arguments and the position of the start of the format unit in the error messages related to the format string, and raise more specific error messages containing more information.

For example (this is only a small part of improved errors):

>>> '%.*f' % (1, '2')
TypeError: format argument 2: a real number is required for format %f, not str
>>> '%.*f' % ('1', 2)
TypeError: format argument 1: * requires int, not str
>>> '%(x)f' % {'x': '1'}
TypeError: format argument 'x': a real number is required for format %f, not str
>>> '%.*f' % (1, 2, 3)
TypeError: not all arguments converted during string formatting (required 2, got 3)
>>> '%.*f' % (999999999999999999999999999999, 2)
OverflowError: format argument 1: too big for precision
>>> '%.999999999999999999999999999999f' % 2
ValueError: precision too big at position 0

gh-142037: Improve error messages for printf-style formatting (GH-142081

The PR introduced a reference leak.

Fix a refleak introduced in pythongh-142037

@encukou

Thank you, @encukou. Should be fixed in #144256.

gh-142037: Fix a refleak introduced in GH-142081 (GH-144256)

pythongh-142037: Improve error messages for printf-style formatting (p…

pythongh-142037: Fix a refleak introduced in pythonGH-142081 (pythonG…

Navigation Menu

Repository navigation

Improve TypeError hints for `%`-formats #142037

Bug report

Bug description:

CPython versions tested on:

Operating systems tested on:

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Improve TypeError hints for %-formats #142037

Description

Bug report

Bug description:

CPython versions tested on:

Operating systems tested on:

Linked PRs

Activity

WFLing-seaer commented on Nov 28, 2025

serhiy-storchaka commented on Nov 28, 2025

serhiy-storchaka commented on Nov 29, 2025

encukou commented on Jan 26, 2026

serhiy-storchaka commented on Jan 26, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Improve TypeError hints for `%`-formats #142037