huh, odd, I don't get those sphinx warnings locally... not a huge deal, just odd

I make fairly heavy use oftyping.Literal. There may be some places where that is more unwieldy than we'd like and it should be str, but for the most part it has a reasonable correspondence to where we use _api.check_in_list (and its similar siblings). There may also be places where I went more generic but we can be more specific by using Literal.

I wonder if_api.check_in_list should be changed/reproduced as a decorator that can check theLiteral signature to avoid duplication. Or perhaps that it too much work.

Now it is probably not worth it, but I still would like to point outhttps://github.com/microsoft/python-type-stubs/tree/main/matplotlib that you may or may not be aware of...

@oscargus I was aware, they were a valuable resource in this exercise, though are not fully complete nor correct (I believe many of the hints in that repo are extracted from inspecting running code, but there are many cases where the type is wider than it saw, e.g. zorder can be any float, but is most often set to int)

My first attempt was to simply start with those, but that had enough warnings so as to be overwhelming, so I started by doing minimal changes to make mypy happy enough to start and adding single files at a time (that is actually why the branch is calledmypy-gradual because my first one was justmypy, but I wanted to take it slower/more methodically).

I wonder if_api.check_in_list should be changed/reproduced as a decorator that can check the Literal signature to avoid duplication. Or perhaps that it too much work.

I think that may be interesting longer term... though probably not as a straight replacement.

• Cases wherecheck_in_list include dynamic usage which does not work for type hints (e.g. register)
• Probably requires inline type hints (as the pyi type hints are not included at runtime)

I have added at least some documentation, though perhaps more is warranted (though that may be follow up as we start to get used to using this and know more about what needs to be documented).

From my perspective the biggest questions prior to merge are:

• Do we want amatplotlib.typing module? (where type aliases/unions/perhaps some literals get shoved)
• What are the feelings about "figure number" which are not numbers and can/should type hints narrow that expectation?

I think there are the following tasks, which are relatively uncontroversial but relate to thempl.typing module if it exists:

• subplot mosaicHashableList type hint
• renameColor toColorType (possibly with aliasColourType if we so desire)

The latest commit fixes the recent mypy identified errors by adding additional error handling.

Decisions re open questions above:

• Yes do atyping module as a public module, but be very clear about provisional status and reserve right to change at any time without warning or deprecation (in API docs and release notes).
• Retain stricter type hints for Gcf to start, if they need to be expanded because a usecase is found and advocated for, we can do so at that time.
• Ensure mypy is happy on 3.9 (revert/add__future__ import changes that affect 3.9)
  • remove explicitTypeAlias (3.10+ feature, leave comment intyping.py to add when 3.9 is dropped)
  • Ensure__future__ import works for| andtype[] notations

I have added a tools script for checking type hints... it's still a bit rough , but largely functional.

It does a series of checks of the AST of the py file vs the pyi file:

• Set of defined items (note that stubs are sometimes a different AST node type, so here we are only checking for missing or extra values in the module)
  • Note that this check doesnot apply to class members, because inheritance and instance attrs set in__init__ complicate the expected sets
• Function signatures:
  • differences in in pos-only args, args, vararg, kwonlyargs, varkwarg, each separately ignorable

There are a handful of errors that are suppressed:

• __init__ suppresses "missing implementation" errors because of__version__ (etc) being set inclass __getattr__ or inside of a context manager
• Two instances of a baseclass specifying simply**kwargs while subclasses specify particular kwargs.
  • for type hints, the base class does not have**kwargs for mypy to be happy

The front end/configuration and adding cli args instead of editing the__main__ remains needed, but once set up and better tested I intend add a CI check (and maybe even looking to get reviewdog-style inline comments, if it's easy to do)

Seee4cedb1 for an example of the kinds of errors identified and fixed by running this tool.

I do not consider getting this fleshed out to be a firm blocker for this PR.

As I've just looked into typing for another project: how does this work out with pyright? My experience from the other project is that pyright is somewhat easier to make happy... Not that it should be an argument to select one, but it would be nice if it worked well with both (as pyright is more often used for type hinting in IDEs if I am not wrong).

@oscargus here was what I found when I first looked into alternate toolsksunden#1 (comment) (I made a PR to my own fork at first to sort out initial CI things without messing with the main repo, used that as a place to put some thoughts at the time)

In my experience, pyright is actually pickier, mostly because it checks otherwise untyped code with the inferred types by default. While I think this behavior is configurable, I was not super happy with the config.

I see mypy as the "standard" tool in the ecosystem (being Guido's project helps with that assessment, to be fair, but also not the biggest of fans of pyright bringing in npm/typescript/javascript... its at least pip installable these days, so not something that most users actually need to worry about, but if non-python is involved in the tool to inspect python source, I'd lean towards something compiled into a static executable...).

For reference, pyright with a similar configuration to to mypy (i.e. excluding the same subfolders, but using defaults otherwise) finds 10752 errors, when mypy finds 0.

If I additionally exclude thetests subfolder, that does go down to 2998 errors.

Many of these are probably do to overly narrow inferred types in code that we do not provide explicit type hints for.
I think if we more fully embrace type hints going forward for internal code (the stub files are still primarily for external/downstream code moreso than for ourselves) then I think addressing these (perhaps more slowly or something like GSOC in a future year) would likely be beneficial for maintaining consistent typed code over time.

There are likely configuration options that could narrow down to a more manageable subset and then incrementally add from there.

I guess my opinion is pyright may be easier to keep happy in the extreme of "everything is typed", but I don't think it is easier in the "I'm adding type hints to a larger extant codebase"

the script I added to tools essentially is doing a subset of what mypy'sstubtest does, but I could not configure stubtest to be less noisy.

@oscargus I was aware, they were a valuable resource in this exercise, though are not fully complete nor correct (I believe many of the hints in that repo are extracted from inspecting running code, but there are many cases where the type is wider than it saw, e.g. zorder can be any float, but is most often set to int)

I created those stubs; they were a mix of using the docstrings and monkeytype execution traces. It was my hope that they might help stimulate an effort like yours, so I am very pleased you are doing this.

🎉 Thank you@ksunden for getting this done!

I expect there is going to be a bunch more iteration on these as they actually get used (initially by people running of the main branch and then a much wider audience when we get 3.8 out).

As I've just looked into typing for another project: how does this work out with pyright? My experience from the other project is that pyright is somewhat easier to make happy... Not that it should be an argument to select one, but it would be nice if it worked well with both (as pyright is more often used for type hinting in IDEs if I am not wrong).

You are not wrong; pyright is used in many editors that use language server protocol (and provides the main type evaluation engine for pylance in Visual Studio Code). Use in editors requires speed and laziness, which pyright has. Pyright can do some amount of type inference, but type inference in Python is hard, which is why we (Microsoft) love it when packages have type annotations or stubs :-) That provides a much better user experience.

@ksunden This is awesome work! Author of stubtest here, please open an issue on the mypy repo and tag me if there's anything I can help with! :-)

PR to improve the allowlist documentation here:python/mypy#15008