[issue32899] Not documented: key in dict test may raise TypeError
New submission from xitop <reg.bugs@poti.sk>: I'd like to suggest an addition to the documentation of the "key in dict" operation. Current version found at https://docs.python.org/3/library/stdtypes.html#dict says only: --- key in d Return True if d has a key key, else False. --- This is not precise. TypeError is also a possible outcome. It happens when the key is unhashable. Unsure whether the description is incomplete or the membership test has a bug I submitted the issue 32675 in January. The issue was closed with resolution of "not a bug". If it is indded the intended behaviour, I think it needs to be documented in order to prevent further misunderstandings. Before the issue 32675 I believed a membership test is failsafe, because the definition of __contains__ clearly defines the return value as either True or False. ---------- assignee: docs@python components: Documentation messages: 312506 nosy: docs@python, xitop priority: normal severity: normal status: open title: Not documented: key in dict test may raise TypeError type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- nosy: +inada.naoki, rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: In general, Python functions don't document all possible exceptions. One reason is that it would lead to substantial redundancy in the docs. Another reason is that functions generally don't know all the possible exceptions that can be raised because that can be controlled determined by the data itself. Also, the docs try to focus on core functionality and not drown out the message with side details. For comparison, look at str.startswith() or math.cos() which can raise a TypeError if the input type is incorrect. There is no reason to discuss that in the docs because most functions raise a TypeError when the type is incorrect. This is more of a general FAQ than a function by function documentation issue. ---------- resolution: -> rejected stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
xitop <reg.bugs@poti.sk> added the comment: While I do fully agree with not documenting all exceptions, I'd like to point out a major difference in the case of "unhashable in dict". It differs from the general case where an exception means the function is unable to return a meaningful result, beacuse it easily COULD return False as its documentation states. The exception is raised by a design decision, not by necessity. That makes it special. A single sentence like "A hashable key is precondition of all dict operations." would explain the behaviour well. That's all I wanted to say. Thank you. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
INADA Naoki <songofacandy@gmail.com> added the comment: We have it already: https://docs.python.org/3/library/stdtypes.html#mapping-types-dict
A dictionary’s keys are almost arbitrary values. Values that are not hashable, that is, values containing lists, dictionaries or other mutable types (that are compared by value rather than by object identity) may not be used as keys.
---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
xitop <reg.bugs@poti.sk> added the comment: You are right. It is 'key in d', not 'object in d'. (Thanks for you patience. I'm sorry I did not get it right earlier.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue32899> _______________________________________
participants (4)
-
INADA Naoki -
Raymond Hettinger
-
Serhiy Storchaka
-
xitop