Documentation on old-style formatting of dicts is overly restrictive

[KenBasye]

BPO	9805
Nosy	@ericvsmith, @bitdancer
Superseder	bpo-1467929: %-formatting and dicts

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2010-09-09.15:29:46.316>
created_at = <Date 2010-09-08.22:08:36.494>
labels = ['docs']
title = 'Documentation on old-style formatting of dicts is overly restrictive'
updated_at = <Date 2010-09-09.15:29:46.315>
user = 'https://bugs.python.org/KenBasye'

bugs.python.org fields:

activity = <Date 2010-09-09.15:29:46.315>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-09-09.15:29:46.316>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2010-09-08.22:08:36.494>
creator = 'Ken.Basye'
dependencies = []
files = []
hgrepos = []
issue_num = 9805
keywords = []
message_count = 5.0
messages = ['115907', '115910', '115924', '115926', '115949']
nosy_count = 4.0
nosy_names = ['eric.smith', 'r.david.murray', 'docs@python', 'Ken.Basye']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '1467929'
type = None
url = 'https://bugs.python.org/issue9805'
versions = ['Python 2.7']

[KenBasye]

From http://docs.python.org/library/stdtypes.html#string-formatting-operations :

"When the right argument is a dictionary (or other mapping type), then the formats in the string must include a parenthesised mapping key into that dictionary inserted immediately after the '%' character."
(with emphasis on 'must' in the HTML, BTW).

This isn't correct: "%s" % dict() is a perfectly legal expression with a dictionary as the right argument and no mapping key in the formats. Indeed, if the current doc were correct, there would apparently be no way to format an empty dictionary.

How about this one-word fix:

"When the right argument is a dictionary (or other mapping type), then the formats in the string may include ..." and so on into the next sentence, and no emphasis on 'may'.

P.S. Not sure about the Type of this issue, and it's present in both 2.7 and current 3.X doc.

[KenBasye]

If someone's going to fix this, perhaps they might consider also adding the following clarification sentence after 'The mapping key selects the value to be formatted from the mapping.'

The mapping key is interpreted as a string; a key error is raised if the dictionary does not have a matching string key.

I don't think it's worth adding it, but consider this example:
>>> d = {2:2, '2':'two'}
>>> '%(2)s' % d
'two'

[bitdancer]

Python 3.2a2+ (py3k:84613, Sep  7 2010, 19:17:31) 
[GCC 4.4.4] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> "%s %(abc)s" % dict(abc=2)
"{'abc': 2} 2"

I did not expect this result. Looks like a bug to me.

>>> "%s %(abc)s" % (dict(abc=2), 4)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: format requires a mapping
>>> "%d %(abc)s" % dict(abc=2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: %d format: a number is required, not dict
>>> "%s %s %(abc)s" % dict(abc=2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: not enough arguments for format string

So, the only case which "works" (but is arguably buggy) is a single %s mixed in with dict lookups. 'may' does not adequately describe this reality. 'must' is much closer. If it weren't a backward incompatible change I'd suggest making a single dict (i.e.: non-tuple) argument to % with non-dict-lookup patterns an error. As it is, we'll just live with the quirk, and probably with the bug as well.

I'm not sure it is worth explaining all these quirks in the main docs. Perhaps in a footnote?

[ericvsmith]

I think this might be a dupe of bpo-1467929.

[KenBasye]

I think Eric is correct; it's a dupe. And I was wrong about not otherwise being able to format an empty dictionary - "%s" % (d,) will always work and is arguably the right thing to do anyway.