
On Fri, 3 Dec 2021 at 00:10, Shantanu Jain <hauntsaninja@gmail.com> wrote:
@Paul
... missing resource is a central set of typing documentation that includes examples, FAQs and best practices as well as reference materials
Like Sebastian, I agree, and this is something we're making progress on.
That's great to know - it's easy for me to say "we need more docs" but I know it's hard to produce them. I'm glad it's on the radar :-)
... easy way of testing that the stubs are correct
mypy ships with a tool called stubtest. It's what typeshed uses to validate itself against CPython. I recently wrote up documentation for it, see here: https://mypy.readthedocs.io/en/latest/stubtest.html
Thanks, I wasn't aware of that. Although TBH I like the suggestion of using typeshed as a kind of staging point for interested users to develop annotations, which can then be moved back into the library once they've been proven stable. I'm still surprised that mypy doesn't check stub files though. If I write stubs for my external API, and then later decide I want to add types to my internal functions, to do static checking on my library, am I therefore required to move the annotations out of the stub file into the main code? What if I want to avoid the runtime overhead of importing the typing module? Or I want to keep the source code clear, by not making function definitions into multi-line monsters because of type declarations?
A lot of the frustration I see being expressed here (including my own) seems to come from the fact that it's so difficult to actually take that sort of "I can ignore it if I don't use it"
Thanks for not staying quiet and helping us make typing better. In particular, I think one takeaway from this thread is that a lot of our documentation is focussed on "how to get started with typing my code", and not much addressed at library authors with limited time to deal with typing questions (like "what is a PEP 561" and "if my type hints are incomplete does that cause problems for my users")
That's a good point that I hadn't spotted - thanks for picking up on it! Paul