Document how to test type annotations #1071
Conversation
This is a slightly broader refactor than just testing. It also consolidates information about checking type coverage/completeness. This originates from a thread on the mypy tracker [1]. In terms of presentation, the goal is to present guidance and offer up several options, many of which were proposed by contributors to that thread. Several of the goals from that thread were not achieved here, including documentation covering stubgen and monkeytype, stubtest, and potentially more. However, the document is written such that it should be possible to add a section on "Generating Annotations" as was planned earlier. [1]: python/mypy#11506
|
Thanks! What you wrote looks good, but it's highly mypy-specific, so it may be a better fit for the mypy docs. |
|
I agree. The original issue proposed an addition to the mypy docs, but I was asked (by a pyright maintainer, FWIW) to put it here instead. I don't really care where the doc goes. I just know that when I realized my published types were incorrect, there was no guidance I could find on testing my fixes. |
|
Eric did say "I guess it depends on how mypy-specific it is." :) You might also be interested in https://mail.python.org/archives/list/typing-sig@python.org/thread/MITFQ6Z45RRMXY3HNM66IC3XXS3TA3JN/ |
You're right. I may have taken a more forceful meaning from his comment than I should have. 😅 It's mostly mypy-centric because that's what I know best. Does your feeling about where this belongs change if I were to add a 30-second intro to Aside: I find the |
|
@sirosen, thanks for writing this. Although it is mypy-centric, I think it's still good to post on this site. Other contributors can then extend it to include tips based on functionality in other tools. |
|
I agree with @erictraut. I'd rather see this here and extended in the future than in the mypy docs. Are you okay with that, @JelleZijlstra? |
|
Sure, let's do that. |
- one minor typo fix - rename the doc to "quality" and re-title - switch to inline links and remove References
|
I've applied the review suggestions. I think this is good to go now, but I'm happy to do more rounds of review if there are still issues.
I also was very impressed by it, which is why I put it first in the doc! Credit to @ikonst for explaining it in the original mypy issue. If I'd known about or thought of that approach first, I might never have written my elaborate |
The goal of this PR is to resolve python/mypy#11506 and document how to test type annotations.
In terms of presentation, the goal is to present guidance and offer up several options, many of which were proposed by contributors to that issue. I have attempted to present all of the information without bias, and everyone in that prior conversation deserves credit for their thoughts and input.
This is a broader refactor than just testing, though testing is the primary content.
It also consolidates information about checking type coverage/completeness.
Several of the goals from that thread were not achieved here, including documentation covering stubgen and monkeytype, stubtest, and potentially more. However, the document is written such that it should be possible to add a section on "Generating Annotations" as was planned earlier.