Integrate or Merge parameter and return annotations

[Josverl]

There are a few other initiatives that have focus on this topic for MicroPython

Where	What	License
https://github.com/hlovatt/PyBoardTypeshed	Howards' original work, no longer actively maintained	MIT
https://github.com/thonny/thonny/blob/master/thonny/plugins/micropython/	Copy of hlovat	MIT
https://github.com/Gobot1234/PyBoardTypeshed	significant manual update	MIT
https://github.com/JetBrains/intellij-micropython	base hlovat + community updates	Apache 2.0
https://github.com/adafruit/circuitpython/tree/main/tools/extract_pyi.py	Fork of micropython, Manually maintained, Some modules may be the same	MIT

With the new stubber capabilities to merge @Overloads it would be possible to merge the better type info into the docstubs

1. create docstubs from .rst
2. clone / fork one of the above
   • select best options based on quality and license
   • forking and change-commits may be needed to reduce the need for textual fixups
   • these could be hosted / submoduled in micropython-stubs
3. merge in the parameter and return annotations & Overloads
   • import type annotations without overwriting docstrings
   • add @Overloads
   • handle differences in package format
   • will need additional glue imports and typedefs per module
4. Migrate to Python 3.12 notation (simpler)
   • using ruff -U -unsafe ( works well in PoC)
5. then continue the normal process
   • merge with frozen
   • merge firmware stubs
6. incompatible @Overloads
   There are quite a lot (60+) of incompatible / overlapping overloads that need adjustment to bring value
   workaround is to use "typeCheckingMode": "basic",

d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\Flash.pyi
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\Flash.pyi:54:9 - error: Method "ioctl" overrides class "AbstractBlockDev" in an incompatible manner    
    Return type mismatch: base method returns type "int", override returns type "int | None"
      Type "int | None" is incompatible with type "int"
        "None" is incompatible with "int" (reportIncompatibleMethodOverride)
d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\Servo.pyi
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\Servo.pyi:91:9 - error: Overload 3 for "speed" will never be used because its parameters overlap overload 1 (reportOverlappingOverload)
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\Servo.pyi:103:9 - error: Overload 4 for "speed" will never be used because its parameters overlap overload 2 (reportOverlappingOverload)
d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\__init__.pyi
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\__init__.pyi:213:5 - error: Overload 2 for "freq" overlaps overload 6 and returns an incompatible type (reportOverlappingOverload)
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\__init__.pyi:454:5 - error: Overload 2 for "info" overlaps overload 3 and returns an incompatible type (reportOverlappingOverload)
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\pyb\__init__.pyi:559:5 - error: Overload 2 for "mount" will never be used because its parameters overlap overload 1 (reportOverlappingOverload)
d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\rpi\_rp2\Flash.pyi
  d:\mypython\micropython-stubber\scratch\micropython-v1_24_0-docstubs\rpi\_rp2\Flash.pyi:13:9 - error: Method "ioctl" overrides class "AbstractBlockDev" in an incompatible manner
    Parameter 2 name mismatch: base parameter is named "op", override parameter is named "cmd" (reportIncompatibleMethodOverride)

10. integrate with micropython-stdlib-stubs
11. Run regular typing QA tests to determine validity

@hlovatt, I think I have found a way to merge our efforts with a goal to bring the combined results to the MicroPython project. Thanks for all the work you have done.

Also See:
JetBrains/intellij-micropython#336

[Josverl]

Hello @Gobot1234,
your fork of the pyboardtypeshed looks quite interesting. I'd like to understand a bit more about the changes that you committed last year
how did you create and test these?
Was that all manual effort ?

[Gobot1234]

I think it was fairly manual because the generated ones weren't super correct. They were somewhat tested on an ardiuno nano ble but I never got round to testing everything.

[Gobot1234]

Saying all this I don't even remember if these stubs are correct for micropython they were for another microcontroller version of python IIRC

[Josverl]

Thanks for the quick response, would be helpful if you can recall what flavor of (Micro)python that was. The included docs sure look like micropython to me.

[Gobot1234]

Ah just remembered might have been circuit python. I remember this being a pretty big headache, I'll double check