homepage

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.

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'.

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]

> 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.

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