Initial implementation of type stubs (mypy/PEP484)

[ksunden]

PR Summary

Closes #20504

This is a massive PR and I realize that... I don't fully expect anyone to read every single line of the newly added stub files. That said, these files have zero effect at run time for the library, so even if there are things that are wrong about them, they won't cause running code to fail. I'd like to get this in early in the 3.8 cycle to allow downstream libraries to test out the type hints with sufficient time to fix them before final release.

When reviewing, read enough of the stub files to get a sense of how they work, and to understand common patterns.
I attempted to be as complete and correct as I could be, but that is mostly reliant on existing docstrings being complete and correct (and some amount of fallback to variable names).

Highlighted changes to library code:

• __all__ added to matplotlib.__init__
  • mypy was not happy about some things being implicitly exported (things that were imported but other places use in the mpl top level namespace)
  • This makes explicit that all mpl defined things are publically accessible from the mpl namespace
  • Happy to add/subtract from the list
• Pyplot has type hints inline
  • boilerplate.py updated to gather annotations
  • because of the syntax rules of the return annotation (cannot line break on ->) the textwrap based line wrapping has been removed and replaced with a clean-up step after writing of running black
  • This makes some of the other behaviors (such as putting null bytes to avoid line wrapping the data kwarg) obsolete, but at the cost of a new dev (and testing) dependency on black
  • The handwritten portions of pyplot are wrapped with # fmt: off/on comments, so only the autogenerated portion of the file is actually run through black
• Some type aliases for commonly used types:
  • Names are negotiable, mostly just tacked on Type to the idea I was representing to avoid occluding a name we might want to use
  • These are included in the .py files such that downstream users can use them as type hints
    • In the earlier days of this work, they were in a _typing.pyi stub file that only worked while type checking, but redistributed to more natural homes and avoided that complexity.
  • colors.Color (str or 3/4-tuple of floats)
    • may wish to rename, especially if we want to be able to create a real Color class to handle things like comparisons, which has been proposed recently.
  • markers.MarkerType(str, Path, MarkerStyle), markers.FillStyleType (Literal of strings)
  • lines.LineStyleType (str or tuple for dashes), lines.DrawStyleType (Literal of strings), lines.MarkEveryType (many types possible)

For most of the library, stub files are used rather than inline type hints.
This has the advantage of not touching literally every public signature line in one PR, but does carry a tradeoff of direct utility of mypy and some other tools in the typing space.
mypy will trust the pyi files and disregard the actual implementation, meaning that if a parameter is added/removed, but the pyi file is not updated, mypy will use the outdated signature to type check.

The two exceptions where inline type hints are used are tests and pyplot.
Tests use inline typehints, but do so relatively minimally, only when mypy complains explicitly. It doesn't make a lot of sense to write stub files for tests, which are not called by downstream libraries (who the stub files are actually mostly for) but running type checking on tests makes a fair amount of sense as it is more representative of what downstream users will see.

Pyplot uses inline type hints because it is autogenerated, and it was easier to inject the type hints into the existing autogenerated code than it would be to do parallel lookup and write two files. The hand written portions of pyplot also do have type hints.
Since pyplot has inline type hints, mypy will actually check the implementation of the functions for type consistency, which can find certain errors.

There are some tools to help discover those problems, but I have found that they are too noisy and not configurable enough to be useful to us (yet).
See this comment for a round up of some of the other type checking tools that are available and why I don't fully support them yet.
I may end up writing a script to find the most commonly anticipated discrepancies, but for getting started, the heuristic is "if a signature is touched, make sure to update the pyi file" (which are already a higher bar of review/etc as anything that changes a signature is an API change which should carry a release note.)
Most specifically, added/removed functions/methods which are not reflected in the pyi and signature changes.

There are some areas left for followup PRs as they are a) relatively complicated ideas that should get particular attention on review that would be lost in this massive PR or b) ideas that can be added incrementally

• data arg preprocessor
• typing shapes and dtypes of arrays (most everything is ArrayLike or np.ndarray, but these types do support being more specific. Using the full power that seems to be available is not as well documented as I would have liked, so may wish to reach out to somebody who knows more about this (and encourage/possibly write the docs that I think should exist for typing with numpy)
• Some methods (e.g. tri*, streamplot, etc) are defined outside of the Axes class, and so the pyplot generation code does not currently get their type hints. The code could be updated to be smarter about looking at attributes and getting their type hints, but that would make it more complicated, so cover the 90% case first.

Additionally, we may wish to be more relaxed or more specific in certain areas.

Dask has an interesting set of guidelines that perhaps we should adopt some or all of.
In particular, for this pass I was being as complete as I could, but they recommend things like "if the return type is a union of things, don't actually type it, because that can be more burdensome to downstream users than just saying Any"
Also some places where we specify callback functions may be overly specified or hard to follow with the full specification, so relaxing the type hint may aid readability.

I certainly don't follow every one of those guidelines yet, but I think they are mostly well reasoned and perhaps we should adopt them/go through and clean up (things like the return annotation on __init__ or importing collections.abc over typing may be better as followup PRs.

I make fairly heavy use of typing.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.

Some types, particularly things like tuple[float, float, float, float] are a little unwieldy and may be better understandable replaced by a type alias (e.g. RGBA or RectangleSpec (names negotiable), because despite being the same type, their usage is logically different).
Also, tuple types are sometimes used when what we really mean is "unpackable thing with N elements" but the type system doesn't handle that super well at this time (though perhaps ArrayLike can get us there...). I also think it is fair in those cases that we say "you should give us a tuple, and for the best guarantee of forward compatibility, maybe cast it to one just to be sure".

The sphinx build is mostly unaffected, as sphinx does not read pyi stub files (yet)... though pyplot does get all of the info in the signature lines, and required some things to be added to the list of ignored warnings (for now, at least... perhaps we could improve their ability to link at some point)

Todos before merge:

• Move items from _typing.pyi to their more natural homes, and document them. This was a bit of a catchall, that ended up not having all that many things in it, but I wanted to be able to use the types and move them later. It is part of why sphinx is unhappy, since these are not documented.
• Fix sphinx build
• Add documentation, especially of expectations moving forward (e.g. keeping these up to date)
• Write release note[s]

PR Checklist

Documentation and Tests

• Has pytest style unit tests (and pytest passes)
• Documentation is sphinx and numpydoc compliant (the docs should build without error).
• New plotting related features are documented with examples.

Release Notes

• New features are marked with a .. versionadded:: directive in the docstring and documented in doc/users/next_whats_new/
• API changes are marked with a .. versionchanged:: directive in the docstring and documented in doc/api/next_api_changes/
• Release notes conform with instructions in next_whats_new/README.rst or next_api_changes/README.rst

[ksunden]

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

[QuLogic]

I've only looked at the .py files and lightly skimmed the .pyi to get a general feel for things.

[QuLogic]

As said elsewhere, I'm still not 100% certain why we can't autogenerate in the right manner in the first place.

Also, the move to 88 wrap might alleviate the problem?

[ksunden]

Certainly it is possible, but the tradeoff would be that the generation code would be less readable (and possibly the output code as well, though in a more subjective way)

If I were to write it, I would probably at least start with black-style (even if generated ourselves) for the signatures, rather than using textwrap (but perhaps keeping textwrap for the method bodies)... with type hints each variable (and the return annotation ) being on a separate line is much more readable, as it is often less obvious where a new variable starts, especially with types that include commas. (I would probably still try to compress to a single line if it'll fit, but that is relatively rare with the added length of the annotations).
While relatively rare, "one line per parameter" is not always itself sufficient to guarantee short enough lines, so that requires additional handling.
I'm not over the moon about how black handles these cases. I think it is a weak point of black's style. But it's probably still better at handling these edge cases than most formatting code that is itself readable/short enough to not be totally lost in formatting weeds.

The fact of the matter is that I was apprehensive about writing it even with the list of edge cases I saw quickly, and I'm sure I would discover at least a few more while implementing. black was quite honestly the quickest answer to the problems I had at hand, so I went with it.

I don't think the bump to 88 will significantly impact whether textwrap will do the trick... there are far too many of these calls that span multiple lines and so while it will shift which ones get cut off on the ->, I doubt it will get rid of them (and certainly even if we get lucky, it will be fragile to future change)
It is more likely to ensure that more of the type hints fit on a single line, but still won't get some of the larger Unions/parameters with Callable type hints.
I can also think of other ways textwrap is fragile that are more likely to be problematic with type hints. For example, if a string with a space appears in the signature (not something we commonly do, but some of the positioning code for things like legend take strings like "upper right", so if we decided to encode that into a Literal type or use that as the default, there would be nothing preventing the textwrap based code formatting from breaking on that space, which is not syntactically valid.
We could probably get away without addressing these edge cases for quite a long time, but eventually are likely to need something more syntax aware in more and more ways.

In any case, the move to black for pyplot was primarily one of not wanting to get lost in minutia of how autogenerated code is formatted while retaining correct syntax.
I think the generation code is easier to understand, as I was able to get rid of some of the other workarounds (like using a \0 to avoid breaking on the data arg dict unpacking, which I could also just do something similar for -> if my only goal was "<X characters and syntactically valid")

It now has in the generation code with only the "syntactically valid" code and then a clean up at the end to do both "<X characters" and "mostly readable", without breaking "syntactically valid". Those are precisely the goals of black(we can argue about the degree to which it achieves it, but it is the goal).
While readability is less useful for autogenerated code than handwritten code, I'd argue that it still matters, especially for signatures.

Wow, that got away from me a bit more than I expected when I started writing... tl;dr yes black is perhaps overkill, but type hints complicate signatures in ways that invite formatting edge cases, so I expect any solution that doesn't involve an extra dependency to be more fragile and harder to follow and update the generation code.

[QuLogic]

Suggested change

	class direct_repr:
	class DirectRepr:

[ksunden]

I was style matching to value_formatter which does similar repr tricks. not opposed to camel-casing, just was doing similar things to existing code.

[tacaswell]

Given that this is internal code, I think we should merge as-is and then clean up both later.

[QuLogic]

This isn't true if the axis has units, no?

[ksunden]

Ultimately, this comes down to axis.Axis.set_ticks being documented as list of floats... I apparently translated that to Iterable[float] there(/in Axes), and for some reason slightly narrowed back to Sequence[float] for pyplot. The MS type stubs just typed it as ArrayLike, which is broader.

Units are a particular case for typing that I haven't gone through and found all of the places where they would apply/expand types. This was partly because they were not being noisy in mypy and partly because I see that as an easier to review change as a perturbation rather than included in full here. (units.py and associated files like dates and category are not actually type hinted yet at all, they don't have any warnings raised and so are separable in that sense, though of course do interweave in many places in Axes/Axis)

So in short, even if it is technically not 100% correct, I think this is a change better made as a follow up. It is consistent with docstrings, so if it should change, the change is likely more than only type hints. (I've been trying to keep this PR hemmed in by that where possible, though a handful of places where mypy warns were addressed)

[QuLogic]

According to https://stackoverflow.com/a/53845083, you should be able to annotate the recursive list now (the linked mypy issue there is fixed.)

[ksunden]

I'll try it out, though I suspect it may be harder to parse as a human than just seeing Any plus the docstring (and will require some additional named types, since you can't do a forward reference inline in a function where there is no type name)

[ksunden]

It does in fact work, and isn't as hard to read as I feared:

    HashableList = list[Hashable | "HashableList"]
    def subplot_mosaic(
        self,
        mosaic: str | list[HashableList],

(tested in the figure.pyi version of this function)

It does require the stringified forward reference, which is otherwise mostly not needed in pyi files or py files with the __future__ import, so there's a mild confusion potential from that, but not actually that bad.

Holding off on committing this as HashableList is something that might go in the mpl.typing module as it is purely for typing purposes.

[QuLogic]

Should have os.PathLike as well?

[ksunden]

Possibly, I think it may work.

That said, the docstring is listed as str or file-like and there are isinstance(fname, str) checks in the implementation, so I kept it as the narrower type.

My inclination is to leave it for now, but maybe do a narrower change that enables any os.PathLike and ensures that the implementation matches, the docstring is updated, and the type hint is updated both in image.pyi and in pyplot.py (this is not an autogenerated method)

[tacaswell]

we should support PathLike everythere (even if the docs did not catch up).

[ksunden]

PIL (well, Pillow) doesn't actually cover the full os.PathLike (though the common cases of bytes, str, and pathlib.Path are covered)

They use the following check:

https://github.com/python-pillow/Pillow/blob/583dd3b4245649ddd367c2dcbbf2bf9fb7835017/src/PIL/_util.py#L5-L6

[QuLogic]

I make fairly heavy use of typing.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 the Literal signature to avoid duplication. Or perhaps that it too much work.

[oscargus]

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

[ksunden]

@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 called mypy-gradual because my first one was just mypy, but I wanted to take it slower/more methodically).

[ksunden]

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 where check_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)

[ksunden]

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 a matplotlib.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 the mpl.typing module if it exists:

• subplot mosaic HashableList type hint
• rename Color to ColorType (possibly with alias ColourType if we so desire)

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

[ksunden]

Decisions re open questions above:

• Yes do a typing 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 explicit TypeAlias (3.10+ feature, leave comment in typing.py to add when 3.9 is dropped)
  • Ensure __future__ import works for | and type[] notations

[ksunden]

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 does not 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 in class __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)

See e4cedb1 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.

[oscargus]

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).

[ksunden]

@oscargus here was what I found when I first looked into alternate tools ksunden#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...).

[ksunden]

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 the tests 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"

[ksunden]

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

[gramster]

@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.

[tacaswell]

🎉 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).

[gramster]

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.

[hauntsaninja]

@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