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.