[docs] [issue13790] In str.format an incorrect error message for list, tuple, dict, set

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Looking further, I noticed that 'string' needed to be changed to 'specification' in the following sentence also. Then I decided that the preceding sentence
 
"Most built-in types implement the following options for format specifications, although some of the formatting options are only supported by the numeric types."

should really follow the one about non-empty format specs. This positioning should make it more obvious that most of the options affect the string representation of the object after, not before, the string is produced, and are therefore applicable to all objects and not just string and number objects. I also propose to modify it so it is shorter and no longer contradictory, to read

"Most built-in types implement various options for such modifications, although some are only supported by the numeric types."

Further on, under "The available string presentation types are:"
I think "``'s'`` String format. This is the default type for strings and may be omitted." should have 'and other non-numeric types ' inserted after strings. New patch i13790b.diff attached

The point of these additional changes is to make it clearer that the default formatting of non-number, non-string objects is to call str() and then apply the options to the resulting string. That makes something like
>>> format(range(5), '-^20s') # same with object.__format__(), 3.3.0a0
'----range(0, 5)-----'
predictable and comprehensible.

I agree with not making a temporary change (but see below ;-).

But it seems that the 3.4 message should at least be
"numeric format string passed to object.__format__" or
"format string with number-only options passed to object.__format__" or
"object.__format__ cannot handle number-only options"
as string formats work fine and, I presume, are not deprecated (?).

However, if the new ValueError message did not specify object.__format__ (which could still be confusing, even if more accurate), the change could be make now. For instance
'Numeric option 'd' for non-number object'.
It would not really matter if it is later raised in object.__format__ instead of str.__format__. I believe *all* of the format codes 'unknown' to str (and by extension, by default, to all other non-number types) *are* number codes.

----------
assignee: docs at python -> terry.reedy
Added file: http://bugs.python.org/file24290/i13790b.diff

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13790>
_______________________________________