Pylance-release: Ship pandas and matplotlib stubs as separate downloadable packages

[blumu]

Please make the typing stubs downloadable as a separate package.

The Pylance VSCode extension currently comes with a bundle of type stubs for matplotlib, numpy and pandas, but because those stubs are not available as a separate downloadable package (e.g. as a pip package), this prevents consistent type checking across tooling and causes CI/CD running Pyright/mypy to break.

[jakebailey]

Just to give some history about these bundled stubs: We intended them to provide a reasonable experience for libraries where we know our analysis doesn't obtain perfect results. Pandas, matplotlib, django, etc, are all difficult to analyze in their own ways, due to decorators, dynamic behavior, compiled code, and so on. We shipped with these stubs to help tide that over for users without type checking (the default mode of Pylance is "off", which suits the vast bulk of users who aren't familiar / don't care about typing and matches MPLS's behavior in nearly all cases).

Our intentions are for these stubs to make it back upstream to the libraries or to typeshed (or for these projects to become annotated or stubbed themselves), and to end up not having to bundle any at all (pending ongoing discussions regarding stub distribution in general).

Due to the history of the stubs as a way to improve simple things like completions/hover, we aren't 100% confident in their quality for type checking and are wary about distributing them in the wrong context. Also note that these bundled stubs contain docstrings, which are currently disallowed in places like typeshed, but for our use case are required to not have to figure out where in the real code to find them. For libraries like pandas which generate docstrings at runtime, providing any docs at all can be challenging if not impossible.

Other stubs we've written have already gone back to typeshed, but the ones you're listing in particular are some of the largest and hardest to type libraries in Python. 🙂

[erictraut]

This is effectively a duplicate of https://github.com/microsoft/pyright/issues/861.

I think the main issue here is the lack of consistency between pylance and the CLI version of pyright. We have tried very hard to make the results consistent, and the presence of these bundled stubs is breaking that consistency.

I can think of a couple of options here:

1. Add a setting to pylance to disable the use of bundled stubs. Users who value consistency more than the language service features enabled by these stubs can disable their use.
2. Ship the bundled stubs with pyright. This could be done by itself or in conjunction with 1.
3. Unbundle the bundled stubs entirely and allow them to be downloaded separately. This would create a big hurdle for the majority of pylance users who don't care about type checking and instead just want language services to work.
4. Conditionally disable the use of the bundled stubs in pylance if the typeCheckingMode is set to "basic" or "strict".

[blumu]

@jakebailey Thank you for providing the historical context. I understand your point about those stubs being incomplete, which is not surprising given the intrinsic difficulty of providing types for python modules after the fact. (I really wish Python had the concept of typing and type inference ala OCaml/F# baked-in, that would avoid all this typing stubs craziness.) That said, however incomplete they are, they do provide significant values. It would be awesome indeed if those could be contributed back upstream to the libraries packages (just like what numpy has done recently). But perhaps in the meanwhile they could be open-sourced here for people who want consistent typing with their CI/CD?

For those of us who do want to leverage Python typing for matplotlib and pandas, the mismatch between the library typing used in VSCode and those used in command-line tooling creates friction. E.g. VSCode tells you your code passes type-checking but then it breaks in the CI/CD.

[blumu]

@erictraut For option 3, could we perhaps bundle the stubs as a separate package (e.g. pip package) and also have Pylance ship with them? Or alternatively have the Pylance plugin propose the user to download the stubs for improved typing experience? (Just like how VSCode proposes me to automatically download Pylint and other packages for me when I open python files.)

[jakebailey]

Consistency is definitely a goal. I think we can at least offer (1) to try and make the two environments line up. I'm a bit unsure about shipping all of these in pyright as well without them being airtight (for fear of misaligning with other type checkers and existing stubs for things we include or override for docstrings), but that could work.

RE: downloading, we don't really want to be executing pip from the LS; the core extension implements this with a big UI to make sure the user has really accepted the action, plus logic to handle all of the different package managers that aren't pip. A better future solution would be caching stubs pulled directly from PyPI, but that's an ongoing thing that needs a lot more design.

I'm iffy on trying to officially publish any of these stubs quite yet as they are currently still restricted to the scope of Pylance, but that might work in the future. The catch though is that if we deem them "good enough" to want people to use in type checking or "officially maintain" (for some definition of that), that would seem to imply that they are "good enough" for upstreaming.

[FranklinChen]

What is the relationship of these special stubs to https://github.com/predictive-analytics-lab/data-science-types which I have been using with MyPy?

[jakebailey]

No relation. Our stubs were created independently with different goals, and we can't use those stubs due to licensing restrictions. You can install them into your environment and they should be used.

[judej]

closing old issue. Please reopen if necessary

[jakebailey]

https://github.com/microsoft/python-type-stubs now holds these stubs. Packaging discussions could happen there, but I believe this is more of a staging ground for what we have with the hope of upstreaming.