Update specification for directives for sys.implementation and sys.platform checks. by Josverl · Pull Request #2173 · python/typing

Josverl · 2026-02-12T17:25:30Z

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 :

python-cla-bot · 2026-02-12T17:25:36Z

All commit authors signed the Contributor License Agreement.

erictraut · 2026-02-14T07:00:47Z

+
+* Equality: ``sys.platform == "linux"``
+* Inequality: ``sys.platform != "win32"``
+* Membership: ``sys.platform in ("linux", "darwin")``


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.

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.

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.

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 · 2026-02-14T07:03:15Z

+
+* Equality: ``sys.implementation.name == "cpython"``
+* Inequality: ``sys.implementation.name != "cpython"``
+* Membership: ``sys.implementation.name in ("pypy", "graalpy")``


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

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 · 2026-02-21T19:15:59Z

+
+    Supported patterns:
+        * ``sys.platform <comparison> <string literal>``
+        * ``sys.platform in <tuple of string literals>``


Or not in?

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

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

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 · 2026-02-22T13:00:56Z

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 · 2026-03-30T19:57:37Z

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.

…atform checks. Signed-off-by: Jos Verlinde <Jos.Verlinde@Microsoft.com>

Formatting improvements. Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

…sion comparisons. Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>

Josverl · 2026-08-09T19:58:39Z

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

jorenham · 2026-08-09T20:09:35Z

+    * ``sys.platform in <tuple of string literals>``
+    * ``sys.platform not in <tuple of string literals>``


Ruff (PLR6201) will report an error for this tuple membership check, and I tend to agree with ruff that a set literal would be more idiomatic here.

In the wild I've seen things like sys.platform.startswith("freebsd") a couple of times, because in this case there's also a version number in the platform string (e.g. "freebsd8"). So how about we also allow sys.platform.startswith(<string literal>)?

jorenham · 2026-08-09T20:12:27Z

+    * ``sys.version_info >= <2-tuple>``
+    * ``sys.version_info < <2-tuple>``
+
+Comparisons checks are only supported against the first two elements of the version tuple. 


As I mentioned a while back in https://discuss.python.org/t/proposal-to-improve-support-for-other-python-platforms-in-the-typing-specification/91877/13, there are genuine use cases for also comparing against the patch version, e.g. in typeshed: https://github.com/python/typeshed/blob/4f84ac178fb23541475f9038840c5b149834374f/stdlib/heapq.pyi#L9-L11

So I propose we loosen this restriction to also allow for 3-tuples.

jorenham · 2026-08-09T20:14:54Z

+   else:
+       # Python 3.11 and lower


It might be good to include elif in this example, so that it's clear that elif is also expected to be supported, and not just if and else. For example as:

Suggested change

else:

# Python 3.11 and lower

elif sys.version_info >= (3, 11):

# Python 3.11.*

else:

# Python 3.10 and lower

jorenham · 2026-08-09T20:24:57Z

+Configuration
+^^^^^^^^^^^^^
+
+Type checkers should provide configuration or CLI options to specify target sys.version, sys.platform, sys.implementation.name and sys.implementation.version. 


Suggested change

Type checkers should provide configuration or CLI options to specify target sys.version, sys.platform, sys.implementation.name and sys.implementation.version.

Type checkers should provide configuration or CLI options to specify target ``sys.version``, ``sys.platform``, ``sys.implementation.name`` and ``sys.implementation.version``.

davidhalter · 2026-08-09T21:57:25Z

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.

Josverl mentioned this pull request Feb 12, 2026

Spec Change : Additional detail and option for platform checks. python/typing-council#52

Open

4 tasks

carljm requested changes Feb 12, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst

erictraut requested changes Feb 14, 2026

View reviewed changes

srittau added the topic: typing spec For improving the typing spec label Feb 20, 2026

Josverl force-pushed the specs/sys.implementation.name branch 2 times, most recently from 4151e84 to d7fbb9e Compare February 21, 2026 17:09

JelleZijlstra reviewed Feb 21, 2026

View reviewed changes

Josverl force-pushed the specs/sys.implementation.name branch from d7fbb9e to 62d90dc Compare February 22, 2026 12:56

Josverl force-pushed the specs/sys.implementation.name branch from 62d90dc to ff338e3 Compare February 22, 2026 13:08

AlexWaygood reviewed Feb 22, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

Josverl commented Feb 22, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

JelleZijlstra reviewed Mar 30, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

Josverl and others added 3 commits April 3, 2026 21:21

Update specification for directives for sys.implementation and sys.pl…

5d84766

…atform checks. Signed-off-by: Jos Verlinde <Jos.Verlinde@Microsoft.com>

Update docs/spec/directives.rst

8116891

Formatting improvements. Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Clarify language in directives regarding named attribute usage in ver…

c951b00

…sion comparisons. Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>

Josverl force-pushed the specs/sys.implementation.name branch from c575c15 to c951b00 Compare April 3, 2026 19:21

Josverl requested review from carljm and erictraut April 3, 2026 19:23

Merge branch 'main' into specs/sys.implementation.name

b3b76c1

jorenham reviewed Aug 9, 2026

View reviewed changes

		* ``sys.platform in <tuple of string literals>``
		* ``sys.platform not in <tuple of string literals>``

-   else:
-       # Python 3.11 and lower
+   elif sys.version_info >= (3, 11):
+       # Python 3.11.*
+   else:
+       # Python 3.10 and lower

	Type checkers should provide configuration or CLI options to specify target sys.version, sys.platform, sys.implementation.name and sys.implementation.version.
	Type checkers should provide configuration or CLI options to specify target ``sys.version``, ``sys.platform``, ``sys.implementation.name`` and ``sys.implementation.version``.

Uh oh!

Conversation

Josverl commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexWaygood Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Josverl commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josverl commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JelleZijlstra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Josverl commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidhalter commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Josverl commented Feb 12, 2026 •

edited

Loading

python-cla-bot Bot commented Feb 12, 2026 •

edited

Loading

AlexWaygood Feb 22, 2026 •

edited

Loading

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

Josverl commented Feb 22, 2026 •

edited

Loading

Josverl commented Mar 30, 2026 •

edited

Loading

Josverl commented Aug 9, 2026 •

edited

Loading

davidhalter commented Aug 9, 2026 •

edited

Loading