[issue37145] collections.abc.MappingView mixins rely on undocumented _mapping
New submission from Geoffrey Sneddon <geoffers+pythonbugs@gmail.com>: The mixin methods on MappingView and its subclasses all rely on the undocumented MappingView._mapping (set in the undocumented MappingView.__init__). This should probably be documented at least insofar as Set._from_iterable is. ---------- assignee: docs@python components: Documentation messages: 344447 nosy: docs@python, gsnedders priority: normal severity: normal status: open title: collections.abc.MappingView mixins rely on undocumented _mapping type: behavior versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Change by Karthikeyan Singaravelan <tir.karthi@gmail.com>: ---------- nosy: +rhettinger versions: -Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: The _mapping attribute is a private implementation detail and should remain undocumented. A user of mapping views creates that attribute via the __init__() method. In contrast, _from_iterable is explicitly meant to be overridden because it is the only way to control object creation. Thank you for the suggestion. ---------- resolution: -> not a bug stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Geoffrey Sneddon <geoffers+pythonbugs@gmail.com> added the comment: How do you use ItemsView without: * relying on __init__ and _mapping, which are both private implementation details, or * reimplementing __len__, __contains__, and __iter__? Given you can't use the mixin implementations of __len__, __contains__, and __iter__ without relying on private implementation details, should they actually be considered mixin implementations? Shouldn't they just be abstract methods given you can't actually use them? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: The __init__ method is public. Here is how to use ItemsView:
from collections.abc import ItemsView d = dict(python='snake', ruby='gem', go='board game', c='speed of light') iv = ItemsView(d) ('python', 'snake') in iv True list(iv) [('python', 'snake'), ('ruby', 'gem'), ('go', 'board game'), ('c', 'speed of light')] len(iv) 4 d['python'] = 'language' list(iv) [('python', 'language'), ('ruby', 'gem'), ('go', 'board game'), ('c', 'speed of light')]
Note, there is no direct access to _mapping. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Geoffrey Sneddon <geoffers+pythonbugs@gmail.com> added the comment: Then I guess what I consider a bug is "__init__ is undocumented". ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment:
Then I guess what I consider a bug is "__init__ is undocumented".
No, this just how Python works. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Hit <submit> too early. In Python, the norm is that the class name is documented. When you call the class, the __init__() method gets called automatically (as documented in the language reference and in the tutorial). For example: >>> class A: def __init__(self, seq): self._seq = seq def __len__(self): return len(self._seq) >>> a = A('apple') >>> len(a) 5 In this example, we document that class "A" can be called with a sequence and that len() can be called on instances of A. The "dunder" methods are public, but are called and documented indirectly. The "_seq" attribute is marked as private and would not be documented, since it is an implementation detail and not intended to be accessed directly. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Geoffrey Sneddon <geoffers+pythonbugs@gmail.com> added the comment: You've missed my point: the arguments that MappingView.__init__ takes are undocumented. Nowhere mentions class MappingView(mapping), as I would expect from how initializers are documented elsewhere. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
Geoffrey Sneddon <geoffers+pythonbugs@gmail.com> added the comment: Like, where in the documentation can I learn that MappingView's initializer takes an argument "mapping"? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37145> _______________________________________
participants (3)
-
Geoffrey Sneddon -
Karthikeyan Singaravelan
-
Raymond Hettinger