Error Messages for methods (original) (raw)

In issue #130821 there was a proposal to unify error messages and @storchaka recommended opening a discuss here, so I’ll explain:
We decided to add a type before the method name so the messages will be updated anyway. And it would be convenient to make one template for such errors at the same time. There are several variants:
{TYPE}.__method__ should return ..., (...) (current state in parentheses)
{TYPE}.__method__ should return ..., not ... (or must return)

Here are some examples of such error messages:

__bool__ returned non-bool (type %T)
__index__ returned non-int (type %T)
__int__ returned non-int (type %T)
%.50s.__float__ returned non-float (type %.50s)
__buffer__ returned non-memoryview object
__annotate__ returned non-dict of type '%.100s'
__len__() should return >= 0
__hash__ method should return an integer
__init__() should return None, not '%.200s'
__sizeof__() should return >= 0
__getnewargs_ex__ should return a tuple, not '%.200s'
__getnewargs_ex__ should return a tuple of length 2, not %zd
__length_hint__() should return >= 0
__length_hint__ must be an integer, not %.100s
read() should return bytes
readall() should return bytes
decoder should return a string result, not '%.200s'
encoder should return a bytes object, not '%.200s'
iterator should return strings, not %.200s (the file should be opened in text mode)

barry-scott (Barry Scott) March 6, 2025, 2:16pm 2

In RFC docs should means optional, must mean mandatory.

Changing the should’s to must’s could be considered at the same tine.

franklinvp (Franklinvp) March 6, 2025, 2:34pm 3

It is nice to see what was given, but sometimes there might not be a way to represent the state, or doing so can unnecessarily cause more errors.

For example, in those that should return >=0, it is clear that if the error is emitted, then what was given doesn’t satisfy that condition. If the return value were -2**9999999, it might not be nice nor useful to try to represent it.

srittau (Sebastian Rittau) March 6, 2025, 4:44pm 5

donBarbos (Semyon Moroz) April 30, 2025, 12:03am 6

Thanks everyone for the comments, I suggest the final version of message:

{TYPE}.__method__() must return ..., not ...

I think the , not ... part can be optional and situation dependent, but it’s fine for type errors.

storchaka (Serhiy Storchaka) April 30, 2025, 6:40pm 7

Something is bothering me. Saying {TYPE}.__int__() must return int is a great understatement, because every __int__() method must return int. But it is useful also to inform what __int__() returns a wrong type. It may not be important, but is there a way to say this in English more naturally while still keeping the message concise?

uranusjr (Tzu-ping Chung) June 15, 2025, 2:47am 8

Personally I feel {TYPE}.__int__() must return int is fine. Yes, all __init__() must return int, but the user only needs to care about {TYPE}.__int__() specifically right now.