Typesheds

C programming, build, interpreter/VM.
Target audience: MicroPython Developers.
hlovatt
Posts: 59
Joined: Thu Aug 15, 2019 3:52 am
Location: Sydney

Typesheds

Post by hlovatt » Sat Jul 25, 2020 4:31 am

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.

User avatar
jimmo
Posts: 2232
Joined: Tue Aug 08, 2017 1:57 am
Location: Sydney, Australia
Contact:

Re: Typesheds

Post by jimmo » Mon Jul 27, 2020 5:29 am

hlovatt wrote:
Sat Jul 25, 2020 4:31 am
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
Posts: 49
Joined: Thu Aug 25, 2016 2:43 am

Re: Typesheds

Post by tannewt » Tue Aug 18, 2020 12:31 am

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

User avatar
aivarannamaa
Posts: 109
Joined: Fri Sep 22, 2017 3:19 pm
Location: Estonia
Contact:

Re: Typesheds

Post by aivarannamaa » Tue Aug 18, 2020 7:00 am

@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.
Aivar Annamaa
https://thonny.org

User avatar
deshipu
Posts: 1385
Joined: Thu May 28, 2015 5:54 pm

Re: Typesheds

Post by deshipu » Wed Aug 19, 2020 7:45 pm


User avatar
aivarannamaa
Posts: 109
Joined: Fri Sep 22, 2017 3:19 pm
Location: Estonia
Contact:

Re: Typesheds

Post by aivarannamaa » Thu Aug 20, 2020 5:04 am

@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.
Aivar Annamaa
https://thonny.org

hlovatt
Posts: 59
Joined: Thu Aug 15, 2019 3:52 am
Location: Sydney

Re: Typesheds

Post by hlovatt » Tue Aug 25, 2020 1:29 am

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.

User avatar
aivarannamaa
Posts: 109
Joined: Fri Sep 22, 2017 3:19 pm
Location: Estonia
Contact:

Re: Typesheds

Post by aivarannamaa » Sun Jan 24, 2021 8:09 am

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? :)
Last edited by aivarannamaa on Sun Jan 24, 2021 8:17 am, edited 1 time in total.
Aivar Annamaa
https://thonny.org

stijn
Posts: 568
Joined: Thu Apr 24, 2014 9:13 am

Re: Typesheds

Post by stijn » Sun Jan 24, 2021 8:17 am

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

User avatar
aivarannamaa
Posts: 109
Joined: Fri Sep 22, 2017 3:19 pm
Location: Estonia
Contact:

Re: Typesheds

Post by aivarannamaa » Sun Jan 24, 2021 8:19 am

stijn wrote:
Sun Jan 24, 2021 8:17 am
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.
Aivar Annamaa
https://thonny.org

Post Reply