How to roll your own stubs.

[ewerybody]

Hello. I'd like assemble an in-depth documentation on providing own stub files. Tips on how to format, have a list of common mistakes and methods to debug all this. How to write them in general seems easy: https://mypy.readthedocs.io/en/stable/stubs.html

But how to make them work within VS Code through Pylance seems a bit of a mystery so far.

Side by Side stubs

Having a .pyi next to your .py file seems to work:

• code.py
• stubbed.py
  • def somefunc(): ...
• stubbed.pyi
  • def somefunc() -> bool:
    • docstring

Having a stubs directoy

There is something built-in already:

• a settings entry:
  
• the according entry via settings.json:
  "python.analysis.stubPath": "typings"
• an entry on the Pylance main page:
  • python.analysis.stubPath
    Used to allow a user to specify a path to a directory that contains custom type stubs. Each package's type stub file(s) are expected to be in its own subdirectory.
    Default value: ./typings

But where IS typings?

or ./typings it's the same right? And I guess it's in the workspace root? Seems so:

• If you open up the Output Ctrl+Shift+U and
• select Python Language Server from the drop down menu
• enter something inexisting into the Stub Path setting:
• then you see it trying to look up the path
  [Error - 3:25:30 PM] stubPath c:\Users\eric\code\projectx\typingss is not a valid directory.
  (Would actually be nice to have a hint about that in the Settings UI directly)

Note: using /, \ or \\ does not seem to make a difference! nice!
And leaving out the ./ is also fine.
A slash at the start without a dot makes it an absolute path tho.

Let Pylance do it!

During the development of Pylance you might have seen the Type Checking Mode enabled by default (If I remember correctly) and seeing your code light up like a cristmas tree. Now it's Off by default. Pcheew. But this also disabled a quite handy feature I just discovered writing this: There is a 💡 Quick Fix to create stub files! What you need:

• have Type Checking Mode set to strict (basic does not enable this 🤷‍♀️)
• put your cursor to a module of yours missing a stub file

Now strict should already highlight any modules that are missing stubs with reportMissingTypeStubs linking you to another piece of useful documentation: Pyright Configuration

Putting your cursor to such a highlighted module will give you the lightbulb thingy 💡 and Voilà: If you click it or hit Ctrl+. there is an option:

• Create Stub file for "modulename"

A notification will tell you Type stub was successfully created for 'modulename'. and Ctrl+Clicking the module name will no longer bring you to your code (hopefully resolved soon #65) but to the new stub file in the given Stub Path directory!

I just checked with another project and there it seems this does not offer this solution that easily. So far I don't know whats wrong. It would be super nice to have this functionality more available. Maybe like from the command palette as well for the current file.

How to format

Looking at the json module there are a couple hints to make your documentation popus look nice via Pylance:

• ticks ` can be used to mark things like so in markdown. This looks the same with double ticks ``
• double colon blocks in the front are ignored tho:

This subclass of :class:`~.QtWidgets.QApplication` ensures that only a

This subclass of ~.QtWidgets.QApplication ensures that only a ...

• .. note:: - blocks are ignored (rst style?)
• URLs with http:// or https:// in front are clickable as well as [email protected] addresses
• - in front makes a bullet list. (* does not work, unlike md here)
• # in various amounts up to ###### make headlines

What else?

I wanted to make this a discussion to actually find out what are issues and what experiences other people might have.

[gvanrossum]

No discussion of this topic is complete without a reference to a draft PEP (no number assigned yet) that several core contributors to typeshed are preparing: https://github.com/srittau/type-stub-pep/blob/type-stub-pep/pep-9999.rst

[erictraut]

You can also find some additional documentation in the pyright repo. Pylance is built on top of pyright.

Creating your own type stubs is not for the faint of heart. The stub creation mechanism in Pylance/Pyright will create a "first draft" based on available information it can find, but improving that first draft to make it usable often requires significant work. Some libraries are written in languages other than Python, and the stub generator won't work for those.

[ewerybody]

Super nice link! Thanks!

Well, I think I should be Python-seasoned enough to pull this off. 🤓
This first draft already helps so much! First of all to see this working at all! From there one can iterate.
I'd look into generating more of this... Writing it by hand really seems like too much work.