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 :

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

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

All commit authors signed the Contributor License Agreement.

carljm · 2026-02-12T19:58:44Z

docs/spec/directives.rst


+**Supported patterns:**
+
+* Equality: ``sys.version_info == (3, 10)``


This example doesn't make much sense, since it would never be true at runtime on any actual Python version.

A realistic example that might actually return True would need to look like sys.version_info == (3, 13, 1, "final", 0) -- but how useful is that in practice?

I would suggest not specifying that equality checks should be supported at all; I don't think they are usable for any realistic scenario.

I agree that the specific version should be adjusted, but I don't think that testing for equality should be dismissed, or truncated to an arbitrary number of nodes.

I don't understand what the possible use case is here. Can you elaborate?

To be clear, at runtime equality checks with sys.version_info will never return True unless you provide all five elements of the sys.version_info tuple. Every other equality check will always return False. So this is only usable if you check all five elements, and making that useful requires that type checkers allow specifying the Python version down to "releaselevel" and "serial" level in their configurations.

From a type checker implementer perspective, I feel pretty strongly that we would never implement support for this, because it is a bunch of work and it is not useful in any realistic case. I see this as a blocker for this proposal.

Thank you for the clear feedback,
Do I understand correctly that Major.Minor would be acceptable for comparison?

Yes, I think that all sys.version_info checks should only handle major/minor. That implies that support for inequality/equality checks against all of sys.version_info must be removed from the proposal, because there is no way to perform a useful equality/inequality check against all of sys.version_info (as shown in this example) that only considers major/minor.

I'm fine with supporting sys.version_info[:2] == (3, 14)! So if we are explicit that equality/inequality checks are supported against only the first two elements, but not against the entire tuple, that resolves my objection.

carljm · 2026-02-12T19:59:05Z

docs/spec/directives.rst

+**Supported patterns:**
+
+* Equality: ``sys.version_info == (3, 10)``
+* Inequality: ``sys.version_info != (3, 9)``


I think inequality checks should also not be supported, for the same reason discussed above for equality checks.

carljm · 2026-02-12T20:04:02Z

docs/spec/directives.rst

+* Tuple slicing: ``sys.version_info[:2] >= (3, 10)``
+* Element access: ``sys.version_info[0] >= 3``


I think for these cases (and even for the basic comparison case) it's also important to specify which elements of the tuple are supported. For example, are type checkers expected to support sys.version_info[2] == 1 (where sys.version_info[2] is the micro version). What about the fourth and fifth elements ("releaselevel" and "serial")?

I think we should be explicit that type checkers should only be expected to have special handling for the first two tuple elements (major and minor version); anything more than that adds a lot of complexity to type checker configuration for little to no gain.

Thanks, I think that is a useful restriction.
Patch level should mean no API level changes, thus no changes in typing.

carljm · 2026-02-12T20:07:29Z

docs/spec/directives.rst

+* Tuple slicing: ``sys.version_info[:2] >= (3, 10)``
+* Element access: ``sys.version_info[0] >= 3``


What about the named attributes? Should type checkers support e.g. sys.version_info.major >= 3?

(I don't think this is useful enough to require, but maybe we should be explicit that support for it is not expected.)

From a MicroPyton perspective I concur, as it does not support named attributes for this, but I don't necessarily want to force that on other implementations.

carljm · 2026-02-12T20:09:24Z

docs/spec/directives.rst

+Configuration
+^^^^^^^^^^^^^
+
+Type checkers should provide configuration to specify target version, platform, and implementation. The exact mechanism is implementation-defined.


Target version to what granularity?

Fair point, I think; as you suggested; Major.Minor

carljm · 2026-02-12T20:16:59Z

docs/spec/directives.rst

+* Membership: ``sys.platform in ("linux", "darwin")``
+* Negative membership: ``sys.platform not in ("win32", "cygwin")``
+
+sys.implementation.name checks


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

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.

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

368e820

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

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


		Supported patterns:

		* Equality: ``sys.version_info == (3, 10)``

		* Tuple slicing: ``sys.version_info[:2] >= (3, 10)``
		* Element access: ``sys.version_info[0] >= 3``

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carljm Feb 12, 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!

Choose a reason for hiding this comment

Uh oh!

carljm Feb 12, 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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Josverl commented Feb 12, 2026 •

edited

Loading

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

edited

Loading

carljm Feb 12, 2026 •

edited

Loading

carljm Feb 12, 2026 •

edited

Loading