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

serhiy-storchaka · 2025-11-29T11:11:48Z

This affects string formatting as well as bytes and bytearray formatting.

For errors in the format string, always include the position of the start of the format unit.
For errors related to the formatted arguments, always include the number or the name of the argument.
Suggest more probable causes of errors in the format string (stray %, unsupported format, unexpected character).
Provide more information when the number of arguments does not match the number of format units.
Raise more specific errors when access of arguments by name is mixed with sequential access and if * is used with a mapping.
Add tests for some uncovered cases.

Issue: Improve TypeError hints for %-formats #142037

This affects string formatting as well as bytes and bytearray formatting. * For errors in the format string, always include the position of the start of the format unit. * For errors related to the formatted arguments, always include the number or the name of the argument. * Suggest more probable causes of errors in the format string (stray %, unsupported format, unexpected character). * Provide more information when the number of arguments does not match the number of format units. * Raise more specific errors when access of arguments by name is mixed with sequential access and if * is used with a mapping. * Add tests for some uncovered cases.

vstinner · 2025-12-01T14:00:36Z

Lib/test/test_format.py

+        test_exc_common("abc %Id", 1, ValueError,
+                        "unsupported format %I at position 4")
+        test_exc_common("abc %'d", 1, ValueError,
+                        "stray % at position 4 or unexpected format character ''' at position 5")


''' is not very readable. Would it be possible to format it as U+HHHH or 0xHH?

vstinner · 2025-12-01T14:02:10Z

Lib/test/test_format.py

+        test_exc_common('%(x)r', 1, TypeError,
+                        "format requires a mapping, not int")
+        test_exc_common('%*r', 3.14, TypeError,
+                        "* requires int, not float")


Without context, it's uneasy to understand that the error comes from a format string. Maybe write %* instead?

Suggested change

"* requires int, not float")

"%* requires int, not float")

It is perhaps better to remove this test, because the example is incorrect in more than one way. If * is used, then we need more than one argument, and in that case we will get "format argument N" in the error message, like in the following line..

Lib/test/test_format.py

vstinner · 2025-12-01T14:06:00Z

Lib/test/test_format.py

+                        "format argument 1: too big for precision")
        test_exc_common('%d', '1', TypeError,
-                        "%d format: a real number is required, not str")
+                        "a real number is required for format %d, not str")


is it really a real number which is expected, or an integer?

Yes. It will be truncated to integer.

vstinner · 2025-12-01T14:08:53Z

Lib/test/test_format.py

+        test_exc('%c', 2**128, OverflowError,
+                 "%c argument not in range(0x110000)")
+        test_exc('%c', 3.14, TypeError,
+                 "%c requires an integer or a unicode character, not float")


Suggested change

"%c requires an integer or a unicode character, not float")

"%c requires an integer or a Unicode character, not float")

This is used in many other places. We should do all such changes at once -- either capitalize "unicode", or remove it.

vstinner · 2025-12-01T17:58:04Z

Objects/unicode_format.c

                         (int)arg->ch, arg->fmtstart);
        }
-        else if (arg->ch >= 32 && arg->ch < 127) {
+        else if (arg->ch >= 32 && arg->ch < 127 && arg->ch != '\'') {


Maybe ignore also the quote character in Py_UNICODE_ISPRINTABLE() test below?

…on into str-format-errors

Lib/test/test_bytes.py

Lib/test/test_peepholer.py

serhiy-storchaka

I currently consider an idea of using "%x expected an integer, got float" instead of "%x requires an integer, not float". What do you think?

Lib/test/test_peepholer.py

Lib/test/test_bytes.py

vstinner

LGTM. I left minor comments.

Lib/test/test_bytes.py

vstinner · 2026-01-23T12:37:41Z

Lib/test/test_format.py

+                 "format argument: %c requires an integer or a unicode character, not float")
+        test_exc('%c', (3.14,), TypeError,
+                 "format argument 1: %c requires an integer or a unicode character, not float")
+        test_exc('%(x)c', {'x': 3.14}, TypeError,
+                 "format argument 'x': %c requires an integer or a unicode character, not float")
+        test_exc('%c', 'ab', TypeError,
+                 "format argument: %c requires an integer or a unicode character, not a string of length 2")
+        test_exc('%c', ('ab',), TypeError,
+                 "format argument 1: %c requires an integer or a unicode character, not a string of length 2")
+        test_exc('%(x)c', {'x': 'ab'}, TypeError,
+                 "format argument 'x': %c requires an integer or a unicode character, not a string of length 2")
+        test_exc('%c', b'x', TypeError,
+                 "format argument: %c requires an integer or a unicode character, not bytes")


Since we are changing error messages, I suggest to write Unicode with an uppercase U.

This is a different issue. "unicode character" is used in other error messages which this error message was based on.

vstinner · 2026-01-23T12:41:48Z

Lib/test/test_str.py

-        self.assertRaisesRegex(TypeError, '%i format: a real number is required, not complex', operator.mod, '%i', 2j)
-        self.assertRaisesRegex(TypeError, '%d format: a real number is required, not complex', operator.mod, '%d', 1j)
-        self.assertRaisesRegex(TypeError, r'%c requires an int or a unicode character, not .*\.PseudoFloat', operator.mod, '%c', pi)
+        self.assertRaisesRegex(TypeError, '%x requires an integer, not float', operator.mod, '%x', 3.14)


I would prefer to check also the format argument: prefix.

I am not sure that it is related to the purpose of this test, but I'll do this. Although it make the lines obscenely long.

Objects/bytesobject.c

serhiy-storchaka requested a review from vstinner November 29, 2025 11:11

bedevere-app bot added the awaiting core review label Nov 29, 2025

bedevere-app bot mentioned this pull request Nov 29, 2025

Improve TypeError hints for %-formats #142037

Closed

vstinner reviewed Dec 1, 2025

View reviewed changes

serhiy-storchaka added 2 commits December 1, 2025 17:00

Merge branch 'main' into str-format-errors

8d9d009

Improve error message for '.

c52feb2

vstinner reviewed Dec 1, 2025

View reviewed changes

serhiy-storchaka added 2 commits December 2, 2025 00:33

Try another format.

0e43000

Try another format.

c015d6a

serhiy-storchaka force-pushed the str-format-errors branch from 0e43000 to c015d6a Compare December 2, 2025 14:53

Merge branch 'str-format-errors' of github.com:serhiy-storchaka/cpyth…

4e5538b

…on into str-format-errors

vstinner reviewed Jan 12, 2026

View reviewed changes

Lib/test/test_bytes.py Show resolved Hide resolved

Lib/test/test_peepholer.py Show resolved Hide resolved

serhiy-storchaka commented Jan 12, 2026

View reviewed changes

Lib/test/test_peepholer.py Show resolved Hide resolved

Lib/test/test_bytes.py Show resolved Hide resolved

Add prefix "format argument: " for a single argument.

cb7ea11

vstinner approved these changes Jan 23, 2026

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Jan 23, 2026

serhiy-storchaka added 2 commits January 24, 2026 12:43

Address review comments.

380157d

Merge branch 'main' into str-format-errors

8aa1920

serhiy-storchaka enabled auto-merge (squash) January 24, 2026 11:11

serhiy-storchaka merged commit 012c498 into python:main Jan 24, 2026
47 checks passed

bedevere-app bot removed the awaiting merge label Jan 24, 2026

	"%c requires an integer or a unicode character, not float")
	"%c requires an integer or a Unicode character, not float")

Uh oh!

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

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

Conversation

serhiy-storchaka commented Nov 29, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

serhiy-storchaka commented Nov 29, 2025 •

edited by bedevere-app bot

Loading