On 2020-12-30 19:26, Christopher Barker wrote:
The trick here, in this context, is that something doesn't need to be a fully functioning Mapping to be unpacked.
But there are a handful of places where a subset of the Mapping API is needed (apparently .keys() and __getitem__, with a particular relationship). So It is good to (a) be consistent about that -- which I think is the case today, and (b) document it -- which is not the case.
Given that where the iteration protocol is described is under built in types, it makes sense to me to t put it there -- maybe call it the "mapping unpacking protocol" (better ideas welcome!).
I don't think that is a good place for it, because it is not a builtin type. It is a protocol which some builtin types happen to implement.
As I mentioned before, the place I would put it is in the documentation for the `for` statement, because the most common reason to implement the iterator protocol is to create an object that works with the `for` statement, and because the protocol describes iteration as a mechanism (not any individual type) so is most naturally placed with the description of that mechanism.
Steven D'Aprano suggested that the protocl docs could be somewhere else and linked to from places that rely on it, and I think that idea has merit as well. But if we do that, I would say the place where the iterator protocol and other such protocols are documented should be a separate section of the documentation for something like "protocols which implement Python concepts" (although of course that's a terrible name). I think the current placement of this information about the protocol )in the builtin types section) is terrible. The builtin types section is the place for the kind of see-also thing that Steven mentioned --- give the documentation for lists with their methods and so on, and say "lists implement the iterator protocol (link)".