How to override the aioble pyi stub files in Visual Studio code

[brianreinhold]

When installing the latest version of Micropython on the PICO W, the bluetooth aioble library is included (however it is in byte code form). VS Code has a set of pyi stub files in the .vscode directory (actually its a short cut to the massive AppData directory). However, the type of the variables in the stubs are Incomplete which does not help me understand what the variables/classes. etc are. The source code, on the other hand, does contain types for many of these values and I have downloaded that source. Being relatively inept when it comes to Python programming (and especially configuration) what I would like to do is to configure VS code such that statements like 'import aioble' point to the source and not the stubs.

Does anyone know now to do this? Would it be as straight forward as replacing the aioble stub directory contents with the aioble source? Somehow I have a feeling that would create a hidden disaster. I tried replacing the code in the AppData folder and after restarting VS code, it appears to work but I don't know what the side effects might be.

[Josverl]

A few points of explanation:

• MicroPython is modeled after CPython - but there are differences in implementation, and in interface.
• The type-stubs included with the VSCode Python (or more precisely Pylance) add-in are created to be used with CPython.
• therefore i created the Micropython-stub to override the CPython stubs with the MicroPython versions, and provide some documentation in the for of docstrings that I can correlate in an automated manner.
• Pylance in some cases falls back to its own included fallback stubs (.vscode\extensions\ms-python.vscode-pylance-2023.12.1\dist\typeshed-fallback)
  In none of the many of such configuration I have seen, is this a shortcut to App Data, but you or one of your add-ins may have added that inadvertently.
• Python type-stubs, by design and definition, should not include the implementation.( Several PEPs on that)
• Python type-stubs must use Python syntax , but can use newer Python syntax that the code that is described. So while MicroPython is mostly based on Python. 3.4, however the MicroPython-stubs (and the docs) frequently use notation that is only valid in Python 3.8+.
• The micropython-stubs that you find in the [yourproject]/.vscode folder, are put there by the MicroPico Add-In, or can be installed in a typing folder. These micropython-stubs also do not have the implementation, only the interface.
• You are correct that aioble is compiled to bytecode and included in the firmware image.
  The source code for the aioble module is stored in the micropython-lib repo in the micropython/bluetooth/aioble folder

I would expect that your project's .vscode folder looks somewhat like this, if not , can you please share some more details here :

what I would like to do is to configure VS code such that statements like 'import aioble' point to the source and not the stubs.

While this is not the intended configuration, the simplest way is to:

1. clone the micropython-lib repo,
2. clean/delete the your_project\.vscode\Pico-W-Stub\aioble folder
3. copy the micropython-lib\micropython\bluetooth\aioble\aioble folder to your_project\.vscode\Pico-W-Stub\aioble ( note the 2x aioble in the first path)
4. In VSCode press F1 > Python: Restart Language Server.
   This will restart Pylance and cause it to discover the new .py files that it will accept in stead of the .pyi files
5. If you now select goto defention, or goto, type definition , it will take you to the full source instead.

You can do this for any module that is written in MicroPython. This method will not work for C modules _ such as _onewire.pyi or '_rp2.pyi' so you may want to take care to keep these.

No harm will de done, no kittens will be hurt, and pythons will continue to hatch eggs, but type checking will run (a bit) slower.
If this helps in your learning, go for it.
The only risk that I can think of is that there may be some confusion between:

• your actual code,
• and the 'code' that is used as a reference for the static tape checker,

Now you may ask, if this can be done, then why not do this already in the stubs ?

• Its not according to the definition and intent of stub-only-packages.
• I would not be able to publish on PyPi
• Not all tools /IDEs are as flexible as VSCode / Pylance , and some will fail or not be able to use the stubs
• The size of the stub distribution packages would increase significantly
• Typecheckers would run slower

I have been trying to grok the inner workings of python type-checking for years, and still continue to learn each month, and meanwhile type checking also continues to evolve and grows new capabilities with each Python version.

Please let me know if this helps and If you think I should I should add this to the documentation at https://micropython-stubs.readthedocs.io/

[brianreinhold]

I will mark this as an answer as that is what I did (although I did it only for the aioble part of the stubs as it is the bluetooth I am interested in). I renamed the stub version and copied in the actual source code, restarted VS Code and it worked! Now when I look for function definitions and variables pylance takes me there. However, a vast majority of the aioble source is still not typed and almost all fields are set to None/Unknown. I have been slowly going through the source and typing those variables and function parameters I can figure out. This makes it easier for me to link the code (which I do not understand) to the Bluetooth LE (which I do understand). I have set pylance to strict so the code is full of red squiggles!

Again, this is for trying to understand what is going on - it does not change what is sitting on the PICO W.

I think in the future your are going to see a drift to having enforced typing in python as it makes the code so much easier to read, especially for large complex programs. This has definitely happened in Angular typescript (also a dynamically typed language from the start). The latest Angular version defaults to strict and unlike python, types are enforced if done. It took 17 versions for that to happen but it finally has.

[andrewleech]

There's some vscode guidance on the wiki here: https://github.com/micropython/micropython/wiki/VS-Code
It'd be great to extend that with some more of this info @Josverl !