Hi Barry & Luciano, Barry Warsaw wrote: > Actually, I think it’s time for a comprehensive guide to type annotations. > Just anecdotally, I was trying to annotate a library of mine and was having > an impossible time of it, until a chat with Guido lead me to > @typing.overload. That solved my problem intuitively and easily, but I just > didn’t know about it. Right now, there’s information spread out all over the > place, the stdlib documentation, tool documentation, StackOverflow :D etc. > It’s a complicated topic that I think a comprehensive guide, a tutorial, etc. > could really help with. > One of my favorite frameworks for thinking about documentation on a topic > such as this is: > https://documentation.divio.com/ > I really think that would help people get into Python type annotations, both > casually and deeply. > > I volunteer to help with a "Typing HOWTO". For the next few months, I > > can offer to review if someone else writes it. In the second semester, > > I could write it myself, if the experts on typing and the type > > checkers would be willing to review it. > > I don’t know whether I’ll have time to *start* something any time soon, but > > I would also volunteer to be a reviewer and/or provide some content.
I'm also interested in helping with this. I think the first question to answer is, are the current mypy docs (https://mypy.readthedocs.io/en/stable/) insufficient for this purpose, and why? They do include both tutorial-style "getting started" paths as well as reference documentation. If they are not serving this purpose, why not? Is it due to their content or structure, or just because they are framed as "the mypy docs" and not "a typed Python HOWTO", so they don't find the right audience? If we do need to write something new, one resource I can offer is an "intro to typed Python" talk I gave at PyCon 2018: https://www.youtube.com/watch?v=pMgmKJyWKn8 I've received feedback from many people without previous experience with typing that this talk was useful to them in understanding both the why and the how. If it seems useful I'd potentially be willing to adapt and update the content and code examples from this talk into written form as a starting point. Carl _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/MEZRNWGXAQ5PCVYTOFTOLS7XHORLVMCB/ Code of Conduct: http://python.org/psf/codeofconduct/
