Add options to tkinter widgets

[Akuli]

Tkinter options now have type hints that describe which values are valid when setting the options. For example, tkinter.Label(relief='sunkenn') now creates a mypy error. The correct types for the options come from Tk's manual pages as described in __init__.pyi. This affects __init__, config, configure, cget, __setitem__ and __getitem__ methods because those are the methods that deal with widget options.

Looking up the value of an option always returns Any, because tkinter doesn't make much effort to ensure that the return values have consistent type. In practice, they can be pretty much anything in funny corner cases, and figuring out which of the possible types actually come up frequently enough for type hints would be a lot of work.

In tkinter, widget['foo'] = bar and widget.config(foo=bar) do the same thing, but they type-check differently: the widget['foo'] = bar syntax allows 'foo' to be any string (e.g. a variable, not necessarily a Literal) and bar to be any object, while widget.config(foo=bar) checks the existence of the option and the type of bar. Similarly, cget takes a Literal argument but __getitem__ takes a string. This is done because:

• It halves the amount of required copy/pasta in stubs files.
• The type of a variable defined with foo = 'sunken' is str rather than Literal['sunken'], so fixing code that does widget.config(relief=foo) can be done without a # type: ignore comment by changing it to widget['relief'] = foo.
• Similarly, setting bar = 'relief' and doing widget[bar] = 'sunken' works.

This also includes a script that checks whether the types of widget options actually work at runtime (stubtest doesn't work well with the generous **kwargs usage in tkinter) and the travis configuration to make that part of the CI build. Usually it takes about 22 seconds to run, which is a lot quicker than any of the other CI things. The script creates tkinter widgets, parses a small subset of type hint syntax with ast, creates possible values of the options based on those type hints and tries to set the options of the widgets.

Some classes in tkinter/ttk.py inherit from other classes and break the Liskov substitution principle by not having all the widget options of the base class. In those cases, I made the stubs not inherit and instead used method = BaseClass.method.

I added a --verbose option to tests/pytype_test.py for finding pytype issues more easily, but that's disabled in the travis config.

This pull request contains a lot less copy/pasta than I initially thought it would contain, but there's still a lot of it. The copy/pasta is quite readable even though I used a script to initially generate it. The script is not included in this pull request because I think the copy/pasta is maintainable as is, and learning to use my script to maintain it would be more work than with copy/pasta. I added comments about the trickiest options to the stubs.

[Akuli]

@Hawk777 What do you think about the difference between __setitem__ and config? Is it too confusing or surprising?

[Akuli]

Rebasing on top of latest master because there's not yet any conversations that could be lost by doing that

[Hawk777]

I’m uncertain how I feel about the configure-vs-__setitem__ and cget-vs-__getitem__ thing. It does have a nice technical benefit that, if you’re not doing any indirection (i.e. you’re using literals), you can just always use configure and cget and you get awesome type checking, and if you are doing indirection, well, there’s still a way to do that. I think there are two big concerns though. First, as far as I can tell (and I could very well be wrong as I’m not a Typeshed expert), it seems like most of Typeshed is developed with the intention of reflecting reality as accurately as possible within the type hint system; in other words, Typeshed seems to try not to be super-opinionated about how people write their code, rather some theoretical “perfect Typeshed” would be one where every valid program is accepted and every invalid program is rejected. This is definitely a change of direction, since it’s saying, “even though it’s totally legal to pass a non-literal string to cget, even though it will work properly at runtime, and even though we could have made your program typecheck if you do that, we chose to reject it instead.”

Second, I worry about discoverability; where would all these Typeshed-specific rules be documented? You have this stronger type checking, but how will people ever know that it exists? Certainly not from reading the Python documentation for tkinter, which explicitly states that __getitem__ and cget are exactly the same thing. What’s even going to prompt people to look for special tkinter-specific, Typeshed-specific documentation where they learn that they can get this extra type-checking?

Neither of these is necessarily a reason to reject, but I think they need to be thought through.

[Akuli]

Tkinter stubs have other things that need documentation too:

• which widget class to use: https://github.com/Akuli/typeshed/blob/cbeab827a3e6afd1e09c8684c51b729e99b22344/stdlib/3/tkinter/__init__.pyi#L17-L22
• tkinter.Event is generic and bind callbacks should return None or Optional[Literal['break']] or Literal['break'] (make tkinter.Event generic and add missing type hints to bind methods #4347)

I think having to look up these things from typeshed pull request and issues history would be pretty bad. Has there been similar "type hints of this library need documentation" problems with other libraries in the past? If so, has the documentation went to docs.python.org, someone's unofficial username.github.io site, comments in stub files, or just nowhere?

[Akuli]

Looking at tkinter documentation on docs.python.org, there's already a big list of references that people should look at, and maybe another item in the list for using type hints with tkinter would be a good idea. Who should maintain that though? I don't think that akuli.github.io/tkinter-type-hints or something is a good idea.

[Akuli]

Maybe I'll mention another idea: put a markdown file into this typeshed repo and link to that from python docs. Maybe that would be a little weird, but it would be very easy to keep it updated as pull requests get merged to typeshed.

[Akuli]

Even though this pull request requires some conversation before getting merged, I'd like to make progress with this. The tkinter stubs won't be usable to me before this (or some similar pull request) gets merged.

@srittau @hauntsaninja It's been quiet for a while, and CONTRIBUTING.md seems to say that it's ok to ping after "more than a few days".

[Akuli]

I created #4453 to fix _FontDescription because that's already on master and not really related to this PR. Everything else is done.

[hauntsaninja]

Thanks again for your hard work and patience! You've been exceptionally thorough; the test script and the real world testing both give a lot of confidence. I did some more spot checking and things look good. If there are more improvements to be made, let's make them on master :-)