-
-
Notifications
You must be signed in to change notification settings - Fork 7.8k
Initial implementation of type stubs (mypy/PEP484) #24976
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
huh, odd, I don't get those sphinx warnings locally... not a huge deal, just odd |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've only looked at the .py
files and lightly skimmed the .pyi
to get a general feel for things.
tools/boilerplate.py
Outdated
# Run black to autoformat pyplot | ||
subprocess.run( | ||
[sys.executable, "-m", "black", "--line-length=79", pyplot_path] | ||
) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -117,6 +119,17 @@ def __repr__(self): | |||
return self._repr | |||
|
|||
|
|||
class direct_repr: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
class direct_repr: | |
class DirectRepr: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Given that this is internal code, I think we should merge as-is and then clean up both later.
@@ -1805,7 +1903,13 @@ def ylim(*args, **kwargs): | |||
return ret | |||
|
|||
|
|||
def xticks(ticks=None, labels=None, *, minor=False, **kwargs): | |||
def xticks( | |||
ticks: Sequence[float] | None = None, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't true if the axis has units, no?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
lib/matplotlib/pyplot.py
Outdated
subplot_kw=None, gridspec_kw=None, | ||
per_subplot_kw=None, **fig_kw): | ||
def subplot_mosaic( | ||
mosaic: str | list[list[Any]], |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
According to https://stackoverflow.com/a/53845083, you should be able to annotate the recursive list now (the linked mypy issue there is fixed.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -2164,16 +2296,18 @@ def set_cmap(cmap): | |||
|
|||
|
|||
@_copy_docstring_and_deprecators(matplotlib.image.imread) | |||
def imread(fname, format=None): | |||
def imread(fname: str | io.FileIO, format: str | None = None) -> np.ndarray: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should have os.PathLike
as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we should support PathLike everythere (even if the docs did not catch up).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
I wonder if |
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... |
@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 |
e442c0a
to
158188d
Compare
I think that may be interesting longer term... though probably not as a straight replacement.
|
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:
I think there are the following tasks, which are relatively uncontroversial but relate to the
The latest commit fixes the recent mypy identified errors by adding additional error handling. |
09a7a98
to
6225f4c
Compare
Decisions re open questions above:
|
cb3be28
to
e4aa8b7
Compare
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:
There are a handful of errors that are suppressed:
The front end/configuration and adding cli args instead of editing the 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. |
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 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...). |
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 Many of these are probably do to overly narrow inferred types in code that we do not provide explicit type hints for. 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's |
Includes completion of rebase onto matplotlib#25580, fixing type hint
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). |
Introduced by matplotlib#24691, merged shortly before matplotlib#24976 Not totally sold on the name 'RawColorType', but couldn't think of something I like better Noticed that one of the other type aliases was not documented, so fixed that while I was editing these two files
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 |
Could help with e.g. matplotlib/matplotlib#24976
Could help with e.g. matplotlib/matplotlib#24976
The typing PR found that this was returning a generator [1], but this was an error from matplotlib#24000, as 3.6 and earlier returned a list. [1] matplotlib#24976 (comment)
Introduced by matplotlib#24691, merged shortly before matplotlib#24976 Noticed that one of the other type aliases was not documented, so fixed that while I was editing these two files
Apparently they'll be included starting in matplotlib 3.8, but that's not available yet. matplotlib/matplotlib#24976
Introduced by matplotlib#24691, merged shortly before matplotlib#24976 Noticed that one of the other type aliases was not documented, so fixed that while I was editing these two files
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 tomatplotlib.__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)->
) the textwrap based line wrapping has been removed and replaced with a clean-up step after writing of runningblack
# fmt: off/on
comments, so only the autogenerated portion of the file is actually run throughblack
Type
to the idea I was representing to avoid occluding a name we might want to use_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)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
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 importingcollections.abc
overtyping
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 bestr
, 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
orRectangleSpec
(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:
_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.PR Checklist
Documentation and Tests
pytest
passes)Release Notes
.. versionadded::
directive in the docstring and documented indoc/users/next_whats_new/
.. versionchanged::
directive in the docstring and documented indoc/api/next_api_changes/
next_whats_new/README.rst
ornext_api_changes/README.rst