[Python-Dev] TypeError messages

[MRAB]

On 2015-02-19 22:50, Serhiy Storchaka wrote:> Different patterns for
TypeError messages are used in the stdlib:
 >
 >       expected X, Y found
 >       expected X, found Y
 >       expected X, but Y found
 >       expected X instance, Y found
 >       X expected, not Y
 >       expect X, not Y
 >       need X, Y found
 >       X is required, not Y
 >       Z must be X, not Y
 >       Z should be X, not Y
 >
 > and more.
 >
 > What the pattern is most preferable?
 >
Stylistically, if the first part is in the active voice, then the
second part should also be in the active voice:

     expected X, but found Y

The active voice tends to be simpler and easier to parse than the
passive voice.

I think that the word "but" adds clarity here.

Strictly speaking, that message is OK only if it's expecting X itself;
if, in fact, it's expecting an instance of X, then you should really be
saying something along the lines of:

     expected X instance, but found Y instance

or:

     expected instance of X, but found instance of Y

 > Some messages use the article before X or Y. Should the article be
 > used or omitted?
 >
Messages tend not to be complete sentences anyway, so I think that it
would be fitting to omit articles.

 > Some messages (only in C) truncate actual type name (%.50s, %.80s,
 > %.200s, %.500s). Should type name be truncated at all and for how
 > limit? Type names newer truncated in TypeError messages raised in
 > Python code.
 >
Truncating type names is probably not a good idea.

 > Some messages enclose actual type name with single quotes ('%s',
 > '%.200s'). Should type name be quoted? It is uncommon if type name
 > contains spaces.
 >
I think that it should be quoted only if it's expecting those
characters, e.g. if it's expecting a closing parenthesis, then it
should say ')'. If, on the other hand, it's expecting a certain type,
then it should give that type unquoted.