Typesheds

[hlovatt]

Hi all,

Is there an interest in adding typesheds (type hint interfaces) to MicroPython to help IDEs that understand types and/or show documentation: PyCharm, VSCode, etc.?

So far I have generated `pyb.pyi` and `uarray.pyi`, the files are at https://github.com/hlovatt/PyBoardTypeshed and the code used to generate them is at https://github.com/hlovatt/PyBoardTypeshedGenerator. The generating code parses the current documentation, `.rst`, files.

Is this something of interest to officially include in MicroPython (i.e. to add a top level `typeshed` folder containing `.pyi` files)?

Howard.

PS If typesheds were available for the whole of MicroPython then in the future instead of generating typesheds from `.rst`, the `.rst` could be generated from the typesheds!

`.rst` from typeshed would lead to improved documentation by having type information in it, more complete, and also having a standard Python structure. The current documentation is in places unstructured (e.g. "Hardware Note" for `Accel`) and incomplete (e.g. no definition of `board` nor `cpu` in `pyb`). The typesheds generated using the generator code referenced above fix some of these issues.

[jimmo]

Is this something of interest to officially include in MicroPython (i.e. to add a top level `typeshed` folder containing `.pyi` files)?

This sounds really good. I don't know anything at all about typesheds but from what you've put together there it looks like a much better way to maintain the documentation. I'll have to investigate further!

[tannewt]

In CircuitPython we used to convert our RST to pyi but now we have pyi directly. The autoapi extension is useful to generate the docs from the pyi: https://github.com/readthedocs/sphinx-autoapi

[aivarannamaa]

@tannewt, where can find or read more about those pyi-s? I'd try to use them for auto completion in the next Thonny release.

[deshipu]

You can look at https://www.python.org/dev/peps/pep-0484/#id44 and also https://github.com/python/typeshed

[aivarannamaa]

@deshipu, I know about stub files in general. I wanted to know from where to get CircuitPython's stub files.

I suppose Scott doesn't read this forum often, so I'll better ask at CP-s forum.

[hlovatt]

Mote typesheds, LCD160CR and machine, at https://github.com/hlovatt/PyBoardTypeshed. Also the README contains:

1. How the typesheds perform in PyCharm.
2. How to add the typesheds to PyCharm.

[aivarannamaa]

I'm preparing the next major update (4.0) of Thonny IDE and one of the themes is more robust and comprehensive code completion and inline API documentation (both for CPython and MicroPython).

Here are some of my dreams releated to MicroPython:

• Each built-in C module (or a group of them) gets a PyPI distribution with corresponding typeshed package with types and api documentation, with distribution version matching the MicroPython version (eg. micropython-machine-stubs==1.14).
• When adding a frozen Python module to MicroPython, the developer can (and is supposed to) specify the name and version of the corresponding (stubs) distribution at PyPI (eg. micropython-my-lcd-driver==3.2.1).
• MicroPython has an API for querying the information about these stubs (eg. sys.stubs_info: List[str])
• Users (or tools) keep a requirements.txt next to their main.py on the device (or in their project directory at local disk), listing the (direct) dependencies installed (or to be installed) onto the flash (/lib).

With this, the IDE could generate a local virtual environment, install all the required stubs and/or whole source distributions and use it for comprehensive code completions and inline documentation.

I know that distributions meant for upip can't be installed with pip, but the developers could add a pip compatible whl. upip needs a small tweak to support this, though.

Also, I know that MicroPython is currently undermanned and I now that there is a tension related to PyPI vs micropython.org/pi, but we can still dream, right?

[stijn]

What is the use of an API for querying stub information?

[aivarannamaa]

What is the use of an API for querying stub information?

The IDE uses this info for installing the stubs to an automatically created virtual environment, which will be the base for code completions. For example, the jedi code completion library can be configured to offer completions from a virtual environment.