GeezerVison

What's the motivation for the ALLCAPS change here? It looks like shouting to me.

("OK" is fine but I'm not a fan of "ERROR".)

It is intended to draw emphasis to the key contrast these examples are included to illustrate—the first and second are valid, while the third is invalid and produces an error. Also, "OK" is of course the correct, canonical capitalization of "OK", while it is "Error" is ALLCAPSed given the particular importance and best practice of prominently marking bad code as such.

"ERROR" still seems ugly and unnecessary to me; I don't really see the need for a change here.

It also goes against the prevailing style in the typing docs — there are several # error comments, but none of them are ALLCAPS: https://docs.python.org/3/library/typing.html

Personally, I value clarity and explicitness over subjective aesthetic preference, given a stated rationale. Also, I'm not sure how relevant the conventions of the typing stdlib doc are here, given it is a separate document from this one, and those particular choices may or may not have a clear, thought-out rationale.

But what do others think? @ezio-melotti @JelleZijlstra ?

If an all-caps ERROR is simply too objectionable, we can at least give it proper case

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

Sounds good to me.

For inline comments like these I tend to use all lowercase and no full stops at the end, so even ok and error would be fine with me.

Same, I don't add a period at the end either for inline or single-line comments...but I notice you do use period for titles (and commit summary lines), which slightly confuses me :) (To note, I do start them with a capital letter, which follows the examples in PEP 8 and avoids looking (IMO) sloppy—though that latter point is personal aesthetic preference)

FWIW, in this general document, I'd appreciate a subtle indication that this is a typing error -- not a SyntaxError or runtime exception. Perhaps Wrong, in whatever case you prefer.

That's a great point—to be more specific, we could say something like Type check error or Incompatible type