Description

erlend-aasland

opened on May 1, 2023

Issue body actions

Feature or enhancement

Gradually add type hints to clinic.py.

Pitch

Adding type hints to clinic.py will make it easier to debug, fix bugs, do code review, add new features, and triage. IMO, the churn is worth the effort in the long run.

Previous discussion

Since adding typing to the CPython code base has been a slightly controversial topic (obviously controversial for Lib/), I created a topic on Discourse and asked for feedback. So far, I have not received any discouragements :)

Linked PRs

• gh-104050: Run mypy on clinic.py in CI #104421
• gh-104050: Add basic typing to CConverter in clinic.py #104538
• gh-104050: Don't star-import 'types' in Argument Clinic #104543
• gh-104050: Add more annotations to Tools/clinic.py #104544
• gh-104050: Add typing to Argument Clinic converters #104547
• gh-104050: Add type hints to Argument Clinic converter keywords #104588
• gh-104050: Add type annotations to sentinels in Argument Clinic #104589
• gh-104050: Improve some typing around defaults and sentinel values #104626
• gh-104050: Add more type annotations to Argument Clinic #104628
• gh-104050: Add more type annotations to Argument Clinic #104631
• gh-104050: Argument clinic: Add annotations to the LandMine class #104648
• gh-104050: Add basic type hints to Argument Clinic DSL parser #104704
• gh-104050: Add basic type hints to Argument Clinic clinic class #104705
• gh-104050: Annotate Argument Clinic return converters #104706
• gh-104050: Add more type hints to Argument Clinic DSLParser() #106343
• gh-104050: Add more type hints to Argument Clinic DSLParser() #106354
• gh-104050: Annotate Argument Clinic DSLParser attributes #106357
• gh-104050: Annotate more Argument Clinic DSLParser state methods #106376
• gh-104050: Annotate Argument Clinic parameter permutation helpers #106431
• gh-104050: Annotate toplevel functions in clinic.py #106435
• gh-104050: Partially annotate Argument Clinic CLanguage class #106437
• gh-104050: Argument Clinic: Annotate the Block class #106519
• gh-104050: Argument clinic: Annotate the Destination class #106655
• gh-104050: Argument Clinic: Annotate nested function parser_body() in the CLanguage class #106699
• gh-104050: Argument Clinic: Annotate output_templates() #106732
• gh-104050: Argument Clinic: Annotate BlockParser #106750
• gh-104050: Argument Clinic: Annotate Clinic.parse() #106760
• gh-104050: Improve Argument Clinic type annotation coverage #106810
• gh-104050: Argument Clinic: Annotate CLanguage.render_option_group_parsing() #106929
• gh-104050: Argument Clinic: Increase CConverter typing coverage #106932
• gh-104050: Argument Clinic: Annotate the IndentStack class #106934
• gh-104050: Argument Clinic: Annotate the BufferSeries class #106935
• gh-104050: Argument Clinic: Increase typing coverage #107074
• gh-104050: Argument Clinic: annotate main() #107192
• gh-104050: Argument clinic: annotate format_docstring() #107200
• gh-104050: Argument clinic: misc improvements to type annotation coverage #107206
• gh-104050: Argument Clinic: Annotate CRenderData.__init__ #107207
• gh-104050: Argument clinic: improve typing around adding C converters #107209
• gh-104050: Argument clinic: more misc typing coverage improvements #107210
• gh-104050: Argument clinic: annotate post_parsing() and cleanup() #107225
• gh-104050: Argument clinic: more misc typing improvements #107264
• gh-104050: Argument clinic: improve typing around parse_arg() methods #107288
• gh-104050: Argument clinic: Complete get_destination_buffer annotations #107293
• gh-104050: Argument clinic: Annotate str_converter_key() #107294
• gh-104050: Argument clinic: complete type annotations #107399
• gh-104050: Argument clinic: enable mypy's --warn-return-any setting #107405

Reacted by Alex Waygood, Kirill Podoprigora and Ken Jin

Activity

1. erlend-aasland

   added

   type-featureA feature request or enhancementA feature request or enhancement

   topic-typing

   on May 1, 2023
2. erlend-aasland

   self-assigned this

   on May 1, 2023
3. erlend-aasland commented on May 1, 2023

   

   erlend-aasland

   on May 1, 2023

   ContributorAuthor

   More actions

   Since I've been ignorant to typing until now, I'd like to give this a shot myself; it'll be a nice opportunity to learn some new tricks.

   EDIT:
   Don't take this too serious; I don't want to block anybody from contributing. Please fire up PRs if you want (I appreciate if you tag me, though!)

   Reacted by Jelle Zijlstra, sunmy2019, Jacob Nilsson and Ken Jin
4. erlend-aasland

   added

   topic-argument-clinic

   on May 1, 2023
5. sobolevn commented on May 3, 2023

   

   sobolevn

   on May 3, 2023

   Member

   More actions

   @erlend-aasland feel free to ask for help/reviews :)

   Reacted by Erlend E. Aasland
6. hauntsaninja commented on May 4, 2023

   

   hauntsaninja

   on May 4, 2023

   Contributor

   More actions

   A good place to start is by switching the instance fields in CConverter to use variable annotations. This is the cause of most of the existing mypy complaints.

   As you add types, the type checker will become more useful. Once you've gotten a number of types in, I recommend upgrading to mypy --check-untyped-defs, and then possibly mypy --strict.

   I'm biased, but I think mypy docs are a generally useful reference: https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html

   Reacted by Erlend E. Aasland

   Reacted by Erlend E. Aasland
7. erlend-aasland commented on May 12, 2023

   

   erlend-aasland

   on May 12, 2023

   ContributorAuthor

   More actions

   As recommended by @AlexWaygood, we should probably start by adding a minimal type check to the CI. (We really don't want to increase CI minutes too much.) In the beginning, perhaps an allow-list is the most manageable path forward. When that list starts to grow, we can consider switching to using a deny-list instead. Thoughts? PRs welcome :)
8. AlexWaygood commented on May 12, 2023

   

   AlexWaygood

   on May 12, 2023

   Member

   More actions

   Here's a PR to add a mypy check in CI, checking only the Tools/clinic directory: #104421. The check completed in 20 seconds (and will only run on PRs that touch files in Tools/clinic/), so I doubt it will increase our use of CI minutes too much!

   Reacted by Erlend E. Aasland

   Reacted by Erlend E. Aasland
9. AlexWaygood

   added a commit that references this issue on May 15, 2023

   gh-104050: Run mypy on `clinic.py` in CI (#104421)

   9d41f83
10. carljm

    added 2 commits that reference this issue on May 15, 2023

    Merge branch 'main' into supermon

    343867a

    Merge branch 'main' into cached_property_docs

    452d9f5
11. erlend-aasland

    added 2 commits that reference this issue on May 16, 2023

    pythongh-104050: Add basic typing to CConverter in clinic.py

    3fa5ea0

    pythongh-104050: Don't star-import 'types' in Argument Clinic

    4dd703d
12. sobolevn

    added a commit that references this issue on May 16, 2023

    pythongh-104050: Add more annotations to `Tools/clinic.py`

    8020dbd
13. 81 remaining items
14. jtcave

    added 10 commits that reference this issue on Jul 27, 2023

    pythongh-104050: Argument clinic: annotate `format_docstring()` (pyth…

    dbf6f44

    pythongh-104050: Argument clinic: misc improvements to type annotatio…

    14ab264

    pythongh-104050: Argument Clinic: Annotate `CRenderData.__init__` (py…

    1c597eb

    pythongh-104050: Argument clinic: improve typing around adding C conv…

    2675e87

    pythongh-104050: Argument clinic: more misc typing coverage improveme…

    7e2906e

    pythongh-104050: Argument clinic: more misc typing improvements (pyth…

    3a4bb49

    pythongh-104050: Argument clinic: annotate `post_parsing()` and `clea…

    594b324

    pythongh-104050: Argument clinic: improve typing around `parse_arg()`…

    0388b96

    pythongh-104050: Argument clinic: Complete `get_destination_buffer` a…

    78db31b

    pythongh-104050: Argument clinic: Annotate `str_converter_key()` (pyt…

    97da968
15. AlexWaygood

    added a commit that references this issue on Jul 28, 2023

    gh-104050: Argument clinic: complete type annotations (#107399)

    55ed85e
16. AlexWaygood

    closed this as completedin #107405on Jul 29, 2023
17. AlexWaygood

    added a commit that references this issue on Jul 29, 2023

    gh-104050: Argument clinic: enable mypy's `--warn-return-any` setting (…

    87de2fb
18. AlexWaygood commented on Jul 29, 2023

    

    AlexWaygood

    on Jul 29, 2023

    Member

    More actions

    44 merged PRs later, and clinic is now 100% fully typed! 🚀

    Reacted by Erlend E. Aasland
19. erlend-aasland commented on Jul 29, 2023

    

    erlend-aasland

    on Jul 29, 2023

    ContributorAuthor

    More actions

    A big thanks to everyone involved! 🎉❤️

    Reacted by Alex Waygood and sobolevn

Issue actions