Update specification for directives for sys.implementation and sys.platform checks.

[Josverl]

This PR adds additional detail to the specification for Version and Platform checking.
Specificially it aims to add support for typechers to add support for :

• checks on sys.implementation.name
• membership checks (in tuple)
• negative membership checks ( not in tuple)

References :

• https://discuss.python.org/t/proposal-to-improve-support-for-other-python-platforms-in-the-typing-specification/91877/1
• Options for shorthand for sys.platform checks #1953

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[carljm]

I think adding this has does have significant ecosystem costs (as outlined by @erictraut in https://discuss.python.org/t/proposal-to-improve-support-for-other-python-platforms-in-the-typing-specification/91877/3 ).

In the end I think it is probably worth it, because without it, type-checking for alternative implementations of Python seems quite difficult. The cost to type checkers themselves seems relatively low: one new config option, defaulting to "cpython".

[Josverl]

The ecosystem is larger than just one implementation.
But I know I can't properly assess the effort needed to update and maintain the tooling I hope to influence.
So I'll leave the weighing up to those who can.

[erictraut]

I'm not convinced that containment should be supported here. There's already a way to express this in a way that all tools today support. I understand the argument that this is less verbose, but it's not that common for checks to include more than one platform, so I don't think there's a compelling argument to force all tools to support this additional form.

[JelleZijlstra]

For deciding on issues like this it would be helpful to have a little summary of what type checkers currently support (like what I did in https://discuss.python.org/t/spec-change-clarify-that-tuple-should-not-be-prohibited-as-an-argument-to-type/105590/7). I'll gather a few variants and summarize it.

I think part of this change will be codifying what is already supported universally, and another part will be adding support for more features. The first group should be uncontroversial, and in the second group we should only force work on type checker authors if there's a clear use case.

[Josverl]

If possible this would really help with creating readable and maintainable type stubs for MicroPython.
even with the proposed sys.implementation.name check we still see significant API differences due the underlying MCU vendor SDKs being significantly different.
Though MicroPython tries to abstract much of these differences away that is not entirly possible as the underlying SDK or hardware is simply different. This is a common source of errors when code is ported from one MCU architecture to another.
For instance Timers are available on all platforms, but with many different default values.

While the below would work

# machine.pyi 
class Timer():
    """"Timer object"""

    if sys.implementation.name == "micropython" and (sys.platform == "esp32" or sys.platform ==  "mimxrt" or  sys.platform ==  "rp2" or sys.platform ==  "samd" or sys.platform ==  "stm32" or sys.platform ==  "alif" or sys.platform ==  "webassembly"): 
        @overload
        def __init__(
            self,
            id: int,
            /,
            *,
            mode: int = PERIODIC,
            period: int | None = None,
            callback: Callable[[Timer], None] | None = None,
            hard: bool | None = None,
        ):...
    elif sys.implementation.name == "micropython" and (sys.platform == "esp8266" or sys.platform ==  "unix" or  sys.platform ==  "windows"  or sys.platform ==  "zephyr"): 
        @overload
        def __init__(
            self,
            id: int = -1,
            /,
            *,
            mode: int = PERIODIC,
            period: int | None = None,
            callback: Callable[[Timer], None] | None = None,
        ):...

the below is much simpler to understand and maintain.

class Timer():
    """"Timer object"""

    if sys.implementation.name == "micropython" and (sys.platform in ("esp32", "mimxrt", "rp2", "samd", "stm32", "alif", "webassembly")): 
        @overload
        def __init__(
            self,
            id: int,
            /,
            *,
            mode: int = PERIODIC,
            period: int | None = None,
            callback: Callable[[Timer], None] | None = None,
            hard: bool | None = None,
        ):...
    elif sys.implementation.name == "micropython" and (sys.platform in ("esp8266", "unix", "windows", "zephyr")): 
        @overload
        def __init__(
            self,
            id: int = -1,
            /,
            *,
            mode: int = PERIODIC,
            period: int | None = None,
            callback: Callable[[Timer], None] | None = None,
        ):...

I think it would be reasonable to explicitly restrict this to "a tuple of literal strings",assuming that simplies the implementation.
Negative membership option could also be omitted , I think that would still be sufficient.

[AlexWaygood]

I fully agree with Eric here FWIW. Adding support for this will add significant complexity to type checkers, and this is the first time I've seen it requested. If we want to ask type checkers to add support for in/not in comparisons with sys.platform and sys.implementation.name, I think it should be a wholly separate proposal to the proposal that asks type checkers to add initial support for comparisons against sys.implementation.version and sys.implementation.name in the same way that they already do for sys.version_info and sys.platform.

[erictraut]

Here again, I don't think there's good justification for supporting a containment operator.

[Josverl]

I addedd this for consistency, but I'm OK to remove sys.implementation.name in ("pypy", "graalpy") from the spec to simplify the implementation.

[JelleZijlstra]

Or not in?

[Josverl]

the not / and / or are described further down to avoid neededing to repeat then for every possible clause, although != is repeated.
I could move that section to the top if that is clearer.

---

Multiple comparisons can be combined with:
* A not unary operator
* An and or or binary operator

[JelleZijlstra]

That's different, it would allow not (sys.platform in ("a", "b")), not sys.platform not in ("a", "b").

[Josverl]

I see your point, then I think it is clearer to just enumerate all option directly,

Supported patterns:
    * ``sys.platform == <string literal>``
    * ``sys.platform != <string literal>``
    * ``sys.platform in <tuple of string literals>``
    * ``sys.platform not in <tuple of string literals>``

[Josverl]

I have updated the text to better clarify the exact comparisons for each of the supported attributes,
excluded the use of named attributes,
and did some more word-smithing to reduce unneeded verbosity.
I have also added highlighting to the examples, as a raiding aide.

[AlexWaygood]

Suggested change

	Use of named attributes is not supported.
	Use of named attributes is not mandated.

[Josverl]

IIRC @carljm requested that addition.
Agree that not mandated is clearer for the metadata.

< Same on line 238>

[AlexWaygood]

I think "not mandated" is clearer that type checkers are permitted to support something additionally if they wish to, but that they are not required to do so. So in general I prefer "not mandated".

The one exception for me might be comparisons against length-3-or-greater tuples for sys.version_info or sys.implementation.version. I think it's usually actually incorrect for a type checker to support those unless the type checker actually either infers the micro version of the Python install the user has locally or offers a configuration knob for the micro version to be specified. To my knowledge, no type checker currently does. So for comparisons between sys.version_info or sys.implementation.version and tuples of >=3 length, I think the stronger language of "not supported" (or maybe even stronger than that) is probably still appropriate

[Josverl]

@erictraut , @AlexWaygood

Alex proposed elsewhere to change not supported to not mandated

as this section also uses that, I wanted to check if there is a need to change the wording here as well.

Also on the light of Jelle's functionality scan

[Josverl]

Dear TC,
Is there a decision on this PR yet, or have I missed a step in the process?

If so kindly let me know how to proceed.

[JelleZijlstra]

I'm generally supportive but I think this change needs some more editing, and I'd like support in at least some type checkers (at least an open PR) before we start mandating this pattern.