On Tue, Dec 29, 2020 at 1:51 PM Brendan Barnwell <brenb...@brenbarn.net> wrote:
> > 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: https://docs.python.org/3/reference/expressions.html?highlight=unpacking 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 -- Christopher Barker, PhD Python Language Consulting - Teaching - Scientific Software Development - Desktop GUI and Web Development - wxPython, numpy, scipy, Cython
_______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/OKENWBMJLD67UTYS4JVVZ4ZE3QWF5EY2/ Code of Conduct: http://python.org/psf/codeofconduct/
