[issue10357] ** and "mapping" are poorly defined in python docs
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> _______________________________________
participants (4)
-
Fergal Daly -
Giampaolo Rodola'
-
R. David Murray
-
Raymond Hettinger