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.

[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.

[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.

[Josverl]

Dear typing council,
I have been waiting patiently , but there seems to be no progress on this.
As far as I can see I have actioned - or responded - to all feedback,
Reviewers have not responded to the updates they requested. Eric has stepped down for the TC since - so that is understandable.

However now it appears that this PR is in a Catch-22 situation;
Waiting for One or more typecheckers to implement this - but for typecheckers to implement this it should be in the spec.

Lacking response I plan close this in a few weeks

[davidhalter]

Waiting for One or more typecheckers to implement this - but for typecheckers to implement this it should be in the spec.

This is not the case at all. It is very typical for type checkers to implement features even if they are not in the spec. It is very helpful to have feedback from type checker authors to be able to understand potential problems with spec changes.

I think this has worked quite well in the past.and if a feature is useful enough there is usually a type checker that will implement it.

[carljm]

Thanks for your patience, @Josverl. I'm not sure we've fully reached consensus yet on what should be supported here, but I also generally support making this clearly specified. I also think this still needs some editing to give a clear and unambiguous presentation of the requirements.

[carljm]

Suggested change

	Use of named attributes is not supported.
	Support for checks against named attributes of `sys.version_info` is not required.

[carljm]

If the expectation is that and and or boolean expressions are supported, that should be explicitly discussed here. Rather than saying "are not required to evaluate complex expressions" (which is vague), we should simply specify the forms that must be supported, and that no other form is required.

[carljm]

The "reversed" example is an obfuscation, but "win" not in sys.platform is not an obfuscation, and from sys import platform; platform == "linux" is definitely not an obfuscation.

Let's avoid value judgments and just give a clear presentation of the forms that are supported, and some example forms that type checkers are not required to support.

[carljm]

Not sure why we need to give exactly the same examples both in prose and then below in a code snippet.

[Josverl]

Thanks all for the renewed attention and comments.

• I'll try to clarify where I can do
• and keep a list of topics that need a decision one way or another