New submission from Fergal Daly fergald@gmail.com:
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.
---------- assignee: docs@python components: Documentation messages: 120739 nosy: Fergal.Daly, docs@python priority: normal severity: normal status: open title: ** and "mapping" are poorly defined in python docs versions: Python 2.7
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
Changes by Giampaolo Rodola' g.rodola@gmail.com:
---------- nosy: +giampaolo.rodola
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
R. David Murray rdmurray@bitdance.com added the comment:
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'.
---------- nosy: +r.david.murray, rhettinger stage: -> needs patch type: -> behavior
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
Changes by Raymond Hettinger rhettinger@users.sourceforge.net:
---------- assignee: docs@python -> rhettinger
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
Fergal Daly fergald@gmail.com added the comment:
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]
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
Raymond Hettinger rhettinger@users.sourceforge.net added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
Raymond Hettinger rhettinger@users.sourceforge.net added the comment:
Clarified what it means to be a mapping in r87871 and r87872.
---------- resolution: -> fixed status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue10357 _______________________________________
-
Fergal Daly -
Giampaolo Rodola'
-
R. David Murray
-
Raymond Hettinger