#  Approach to collecting stub information

The {ref}`stubs <stub-files>` are used by 3 components.

  1. the VS Code {ref}`Pylance <pylance>` Language Server
  2. the VS Code Python add-in
  3. a linter such as {ref}`pylint <pylint>`

These 3 tools work together to provide code completion/prediction, type checking and all the other good things.
For this the order in which these tools use the stub folders is significant, and best results are achieved when all use the same order. 

In most cases the best results are achieved by the below setup:  

![stub processing order](./img/stuborder_pylance.png)

 1. **Your own source files**, including any libraries you add to your project.
 This can be a single libs folder or multiple directories.
 There is no need to run stubber on your source or libraries.
 2. **The {ref}`CPython <cpython>` common stubs**. These {ref}`stubs <stub-files>` are handcrafted to allow MicroPython script to run on a {ref}`CPython <cpython>` system.
 There are only a limited number of these stubs and while they are not intended to be used to provide {ref}`type hints <type-hints>`, they do provide valuable information. 
Note that for some modules (such as the  `gc`, `time`  and `sys` modules) this approach does not work. 
 3. **{ref}`Frozen stubs <frozen-stubs>`**. Most MicroPython {ref}`firmwares <firmware>` include a number of Python modules that have been included in the firmware as {ref}`frozen modules <frozen-modules>` in order to take up less memory.
 These modules have been extracted from the source code. 
 4. **{ref}`Firmware stubs <mcu-stubs>`** (formerly called MCU stubs; the persisted stub source string remains "MCU stubs" for compatibility). For all other modules that are included on the {ref}`board <board>`, [micropython-stubber] has been used to extract as much information as available, and provide that as {ref}`stubs <stub-files>`. While there is a lot of relevant and useful information for code completion, it does unfortunately not provide all details regarding parameters that the above options may provide.

##  Stub collection process 

* The **CPython common stubs** are periodically collected from the [micropython-lib][] or the [pycopy-lib][].
* The **Frozen stubs** are collected from the repos of [micropython][] + [micropython-lib][] and from the [loboris][] repo.
  The methods to gather these differs per firmware family, and there are differences between versions how these are stored, and retrieved.
  Where possible this is done per port and board, or if not possible the common configuration has been included.
* the **firmware stubs** are generated directly on a MCU running MicroPython.



##  Firmware stubs (formerly MCU stubs) format and limitations 

1. No function parameters are generated 
2. No return types are generated 
3. Instances of imported classes have no type (due to 2)
4. The stubs use the .py extension rather than .pyi (for autocomplete to work) 
5. Due to the method of generation nested modules are included, rather than referenced. While this leads to somewhat larger stubs, this should not be limiting for using the stubs on a PC.  

##  Stub  naming convention 

The firmware naming conventions is most relevant to provide clear folder names when selecting which stubs to use.

for stubfiles: {**firmware family**}-{version}-{port}

for frozen modules : {firmware}-{version}-frozen\{port}\{board}

* ***firmware family***: lowercase 
  * micropython | loboris | pycopy | ...
* ***port***: lowercase , as reported by os.implementation.platform 
  * stm32 | esp32 | linux | win32 | rp2 | samd | ...

* ***board***: used mainly for frozen stubs
  * GENERIC | RELEASE | UM_TINYPICO | GENERIC_512K |  ARDUINO_NANO_RP2040_CONNECT | ...
  
_Note:_ RELEASE appears to be used mainly for CI/CD purposes and is not commonly used on hardware.
  
* ***version*** : digits only , dots replaced by underscore, follow version in documentation rather than semver 
  * v1_13
  * v1_9_4
  * ***build***, only for nightly build, the build nr. extracted from the git tag 
    * Nothing , for released versions
    * 103 
    * Latest

