** and "mapping" are poorly defined in python docs

[FergalDaly]

BPO	10357
Nosy	@rhettinger, @giampaolo, @bitdancer

^{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 = 'https://github.com/rhettinger'
closed_at = <Date 2011-01-08.23:51:54.761>
created_at = <Date 2010-11-08.13:16:24.868>
labels = ['type-bug', 'docs']
title = '** and "mapping" are poorly defined in python docs'
updated_at = <Date 2011-01-08.23:51:54.759>
user = 'https://bugs.python.org/FergalDaly'

bugs.python.org fields:

activity = <Date 2011-01-08.23:51:54.759>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2011-01-08.23:51:54.761>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2010-11-08.13:16:24.868>
creator = 'Fergal.Daly'
dependencies = []
files = []
hgrepos = []
issue_num = 10357
keywords = []
message_count = 5.0
messages = ['120739', '120761', '120817', '120819', '125809']
nosy_count = 5.0
nosy_names = ['rhettinger', 'giampaolo.rodola', 'r.david.murray', 'docs@python', 'Fergal.Daly']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue10357'
versions = ['Python 2.7']

[FergalDaly]

According to the index, the only place that mentions ** in argument lists is

http://docs.python.org/tutorial/controlflow.html#index-1099

and gives no indication of what an object must support to allow **.

When you attempt to ** an object the real attribute exception is suppressed and you get a message

"argument after ** must be a mapping"

"mapping" is quite loosely defined. There are 3 definitions, the glossary entry seems the most complete

http://docs.python.org/library/stdtypes.html#index-625
http://docs.python.org/reference/datamodel.html#index-842
http://docs.python.org/glossary.html#term-mapping

But even the glossary entry doesn't tell you what you need for **.

Only by reading the C source code did I discover that to be usable in **, an object must implement .keys() and .__getitem__().

The docs either should add .keys() to the definition of mapping or the code should use some other term or simply allow the original exception to reach the user.

[bitdancer]

I think the Glossary entry needs to be updated to point to the authoritative source for 'mapping' methods:

http://docs.python.org/library/collections.html#abcs-abstract-base-classes

(and yes, I realize that info is not located in a particularly intuitive location!)

I wonder, however, if the code should be updated to use a dictionary iterator rather than 'keys'.

[FergalDaly]

Even if the glossary pointed to collections.html, there are far more methods specified there than are needed to be **able.

The code just calls into the same code as dict.update(dict) (although
.update can also work on a sequence of twouples).

dict.update's doc string is explicit about what it requires from the argument:

| update(...)
| D.update(E, **F) -> None. Update D from dict/iterable E and F.
| If E has a .keys() method, does: for k in E: D[k] = E[k]
| If E lacks .keys() method, does: for (k, v) in E: D[k] = v
| In either case, this is followed by: for k in F: D[k] = F[k]

[rhettinger]

Even if the glossary pointed to collections.html,
there are far more methods specified there than
are needed to be **able.

That is an implementation detail and is subject to
change. If someone supplies an argument satisfying
collections.Mapping, that should be sufficient across
all implementations.

dict.update's doc string is explicit about what
it requires from the argument:

Duck-typing is still allowed when explicit requirements
have been exposed (we do this a lot with .readline() for
example). For the most part though, we want to specify
"needs a Mapping" in the sense of collections.Mapping.

[rhettinger]

Clarified what it means to be a mapping in r87871 and r87872.