> they all overlap a bit in purpose. And "protocols" seem to be the least
> clearly specified. Indeed, the "iteration protocol" is well known and
> talked about, but not well documented in the standard docs:
No offense to anyone here, but I don't really see that as a valid
excuse.
It was an explanation, not an excuse -- this is an open source project -- you have better ideas for documentation, submit a PR -- or process, there are places to contribute there as well.
Documentation can evolve too. It's fine if the protocols and
so on overlap, but the nature of that overlap needs to be documented.
And I made some suggestions for that -- but the Duck Typing is tricky to document, it's by definition not clearly defined.
Is there
any ongoing project to bring the official documentation up to date with
regard to the kinds of issues you describe?
not that I know of -- great place to volunteer, though.
> Maybe something along the lines of:
>
> "When a Mapping type is required in python (e.g. dict.update, **
> unpacking), .keys() and __getitem__ are the minimum required to meet
> the Mapping protocol."
Even that isn't sufficiently explicit, to my mind. It needs to be
something more like:
When an object is unpacked with ** unpacking, its .keys() method is
called to get the available keys, and its __getitem__ is called to
obtain the value for each key.
Ah, but that's different -- I was attempting to document the "mapping protocol" such as it is, not ** behavior. And where THAT should be doucmented isn't clear to me, but maybe here:
where it says:
"A double asterisk ** denotes dictionary unpacking. Its operand must be a mapping."
With "mapping" being a lnk to the Glossary. So either there, or somewhere linked to there could be a defintion of what a minimal"mapping" is.
If dict.update internally uses .keys() and that's relevant
for stuff like subclassing dict, that should be in the dict documentation.
That's actually the one place I could find where it IS documented.
In other words, every operation that uses .keys() needs to be defined
to use .keys() where that operation it is defined. Or, if there is a
"dict protocol" (like maybe the Mapping ABC) then there should be a
separate doc page about that protocol, which gives a COMPLETE list of
all methods that are part of the protocol
This is what I'm getting at: there is an informal protocol for "reading" a mapping. and it should be documented. but the COMPLETE list is simply .keys() and .__getitem__ :-)
along with a COMPLETE list of
the language features that make use of that protocol.
That is pretty much impossible -- that's kind of the point of a protocol -- it can be used in arbitrary places in arbitrary code.
would you expect a COMPLETE list of all the language features that use the iteration protocol?
> Otherwise, the Mapping ABC is clearly defined, but not, in fact,
> required in most of the contexts that expect a Mapping.
> you have to actually give a complete list of
situations when it's going to be implicitly called, and update that list
if needed as the language evolves.
I don't "have" to do anything, nor does anyone else contributing to the development or documentation of Python.
But tone aside, I think you're pushing pretty hard for something that doesn't really fit Python -- again, Duck typing is not a set of hard and fast rules.
If you have specific ideas for how the documentation can be improved, by all means make them.
-CHB