Consider adding type hints to clinic.py

Core Development
1

I’ve done a handful of PRs on the 5367 lines[1] long Tools/clinic/clinic.py, and every time I touched that file, I had to use considerable amounts of time to figure out all the single-letter named parameters and variable names. I often find myself thinking that clinic.py would have been so much easier to maintain if it only had had type hints. So here the crazy idea: let’s add type hints to clinic.py. Hypothesis: it will make it easier to triage clinic issues, review clinic PRs, fix clinic bugs and implement new clinic features.

Thoughts?

  1. 2023-04-29, HEAD at 85c7bf5bc ↩︎

5 Likes
2

From a typing perspective the code seems rather straightforward. Just need to add types to function signatures and empty list/dict/set assignments.

I can’t say anything about why it’s not typed yet, but if it ends up happening I can join the effort.

3

Adding type hints to Python source code in the CPython code base has been a controversial issue, which is why I brought it up here. However, since Argument Clinic is part of Tools/, and not a part of the standard library (Lib/), I expect it to be less of a controversial issue. For example, Tools/build/check_extension_modules.py is typed.

4

Prior discussion:

As I said earlier, tooling is a less controversial topic.

1 Like
5

FWIW, I don’t think any of the points I made in that^ thread apply to things outside the Lib/ directory :slightly_smiling_face:

I don’t know much about clinic.py, so I can’t comment on how much adding type hints is likely to help or hinder development of the code! But I’m (obviously) generally pro-typing, and a believer that it generally makes code easier to read and reason about. Happy to help out if you need a hand on anything.

There are tools such as autotyping that might be worth trying, which can add an initial layer of type hints to the code automatically.

Would we run a type checker on clinic.py to validate that the type hints are correct, or would they just be for human readers? (I’d advocate using a type checker, as it’s very easy for type hints to go out of date otherwise. If you configure the settings correctly, you should be able to use “gradual typing” — the type checker will only emit errors on functions with type annotations, and will ignore all other functions. This allows you to incrementally add more annotations to the code.)

1 Like
6

I think it’s fine to add type hints to clinic. FWIW, the cases generator used in Python 3.12’s interpreter generator is almost fully type hinted cpython/Tools/cases_generator at main · python/cpython · GitHub

2 Likes
7

Sound like something we’d want as a non-required check in our CI.

1 Like
8

Based on the feedback so far, I’ll create an issue for this. Since I’m in the «typing-ignorant-camp» of core devs, I’d like to try to come up with a PR for this. Who knows, maybe I end up in the pro typing camp :slight_smile:

Thanks for your input, Tushar, Alex, and Ken.

5 Likes
9

… and now, 44 PRs later, Argument Clinic is fully typed. Big thanks to everyone involved! It’s been fun :smiley:

7 Likes
10

Oh, for the record: I did.

3 Likes