Proposal to Enhance Type-Checkers for MicroPython-Specific Code and Port Differentiation

[Josverl]

Context

I intend to propose the below the the Python Typing community and council, as I run into challenges with defining stubs for micropython that are both detailed and correct across the different ports of MicroPython, and wanted to check in for feedback , and possibly support, in this community first.

My questions to this forum:

• would you support this
• should the proposal only focus on the ability for typecheckers to identify MicroPython , or also include ports
• are there other things that you think should be considered ( boards , MicroPython version, or a more generic approach )

Related discussions :

• https://discuss.python.org/t/call-for-suggestions-nominate-python-packages-for-typing-improvements/80186
• Options for shorthand for sys.platform checks python/typing#1953
• Python Type Annotations: Tooling/Gaps/Pain Points pyscript/pyscript#2316

Introduction

The Python typing community has made significant strides in improving type-checking capabilities across various Python implementations. However, there is a growing need to address the unique requirements of MicroPython, especially in distinguishing MicroPython-specific code and differentiating type stubs for various ports. This proposal aims to introduce enhancements to type-checkers to better support MicroPython and its diverse platform values.
Current platform checks by type checkers are intentionally limited in the typing spec: https://typing.python.org/en/latest/spec/directives.html#version-and-platform-checking

Current Challenges
MicroPython utilizes approximately 12 additional sys.platform values, such as esp32, esp8266, mimxrt, nrf, renesas-ra, rp2, samd, stm32, unix, webassembly, windows, and zephyr. Currently, developers need to write long and repetitive boilerplate code to handle these platform checks, which is both cumbersome and error-prone.

For example:

if sys.platform == "esp32" or sys.platform ==  "esp8266" or sys.platform ==  "mimxrt" or sys.platform ==  "nrf" or sys.platform ==  "renesas-ra" or sys.platform ==  "rp2" or sys.platform ==  "samd" or sys.platform ==  "stm32" or sys.platform ==  "unix" or sys.platform ==  "webassembly" or sys.platform ==  "windows" or sys.platform ==  "zephyr" : 
     @overload
     def sleep_ms(delay: float) -> None: ...

Additionally, while MicroPython defines sys.implementation.name as 'micropython', a condfitional such as if sys.implementation.name == "micropython": does not work as expected with type-checkers as the use of this attribute is not part of the typing spec.

Proposed Solution
To address these challenges, I propose the following enhancements to the Python typing specification and type-checkers:

1. Support using sys.implementation.name in type checkers:

   Ensure that type-checkers correctly process sys.implementation.name for MicroPython, allowing type stub authors to use if sys.implementation.name == "micropython": or if sys.implementation.name == "pypy": to simplify stub authoring.

2. Enhanced sys.platform Checks:

   Introduce support for more detailed sys.platform checks, allowing patterns such as if sys.platform in ('esp32', 'esp8266', 'mimxrt', 'nrf', 'renesas-ra', 'rp2', 'samd', 'stm32', 'unix', 'webassembly', 'windows', 'zephyr'):. This would significantly reduce boilerplate code and improve readability.

Benefits

Implementing these enhancements will provide several benefits:

• Reduced Boilerplate Code: Developers will no longer need to write long and repetitive platform checks, leading to cleaner and more maintainable code.
• Improved Type-Checking Accuracy: Type-checkers will be able to accurately distinguish MicroPython, or PyPy specific code and differentiate type stubs for various ports, improving overall type-checking accuracy.

[andrewleech]

These proposals seem very logical to me, I think they're good clear suggestions. Looping in the likes of pypi is sensible to broaden the appeal too!

I do very much like the idea of being able to include ports in this, I presume long-term this could mean that just one stubs package could be built/distributed that covered all the ports?

Similarly version support could work towards this goal though I can also see that making the stubs code ever-increasingly complex; perhaps keeping it one package for one version of micropython makes more sense here.

[Josverl]

Similarly version support could work towards this goal

Looking at the CPython stubs, version branches are often used. I guess it would be the same for MicroPython or PyPy.
Perhaps the ability to set and use a platform's version to a constant is worth the effort as that significantly simplifies both use and maintenance.