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 expands and clarifies the specification for version, platform, and Python implementation checks:

Adds checks for sys.implementation.name and sys.implementation.version.
Specifies supported comparisons, including in / not in with literal tuples, sets, and lists, and sys.platform.startswith().
Covers combining checks with and, or, and not.
Distinguishes required forms from optional extensions.
Adds examples and guidance on target configuration and defaults.

References :

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

All commit authors signed the Contributor License Agreement.

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.

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

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.

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.

Josverl · 2026-08-10T21:40:51Z

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

…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>

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

Josverl · 2026-08-15T20:57:06Z

Again thanks for the feedback and suggestions to improve the spec.

I processed the comments and suggestion - and commented or marked them as resolved to keep track.
Please feel free to Unresolve or add additional comments as needed.
I have extended the Configuration section to help clarify how a type checker could be configured including default values or approaches for defaults.

Open topics.

1. 2-Tuple or 3-Tuple version comparisons.
see comments

requirement is for 2-Tuple checks
type checkers are allowed to also process 3-Tuple checks

2. Should in / not in membership checks use tuple, set or list.
intent was tuples, was updated to set , now waiting for consensus

* ``sys.platform in <tuple/set/list of string literals>``
* ``sys.platform not in <tuple/set/list of string literals>``
* ``sys.implementation.name in <tuple/set/listof string literals>``
* ``sys.implementation.name not in <tuple/set/list of string literals>``

3. Scope
as raised by @AlexWaygood
Is the scope of this change too large (it has grown since that comment) and should there be a implementation timeline / staged implementation.
I have refrained from answering this - as I am not the one that can do the implementation.

I think the commits should be squashed when merging - I've kept them separate for now.

carljm · 2026-08-17T21:16:26Z

We could eliminate open-question (2) and at least partially address (3) by just considering containment checks as out of scope to specify for now. Considering they don't add any new capability, just allow writing more concise code, they aren't really necessary. We could leave this out of the spec / conformance suite for now and up to individual type checkers. Similarly maybe for startswith. Leaving it out doesn't prevent type checkers from supporting it. And including it in the spec / conformance suite doesn't guarantee type-checker support, either, so it's unclear how soon some of these difficult-to-support patterns will be usable in practice anyway, even if they are included here.

Josverl · 2026-08-17T21:43:07Z

I think that we should keep startswith.

Is there any type checker that support this currently?

AlexWaygood · 2026-08-17T21:43:56Z

I think that we should keep startswith.

Is there any type checker that support this currently?

ty

carljm · 2026-08-17T22:15:59Z

At least for ty, startswith support is trivial (already there!), don't know how difficult for other type checkers. Point taken that (unlike containment checks) it really does introduce a new (and sometimes needed capability).

Regarding containment checks, for ty tuples are trivial (also already supported!) but mutable types are not. ty handles this quite differently from other type checkers: we use full type inference, not special-cased AST-matching. This makes some thing a lot easier, and some things harder. For mutable container types, we would normally not infer e.g. ["foo", "bar"] as list[Literal["foo", "bar"]] but as list[str] (same for set), so we normally would lose the literal precision. It should be doable, just not straightforward and I'm not sure how quickly we'd prioritize it. (But once we did support it, we would support it for all containment checks of a literal type against a literal list/set of literal types, not just for sys.platform and friends specifically.)

I suspect that for type checkers that do AST matching, containment checks for tuple/list/set should all be equally straightforward.

jorenham · 2026-08-17T22:23:56Z

Regarding containment checks, for ty tuples are trivial (also already supported!) but mutable types are not. ty handles this quite differently from other type checkers: we use full type inference, not special-cased AST-matching.

Would frozenset help?

carljm · 2026-08-17T22:43:57Z

Would frozenset help?

Not much. It would require that we implement astral-sh/ty#2280, which probably mostly requires the same machinery. (The problem here is that frozenset doesn't have a literal syntax, so first you have to build a literal container of some other kind, and then pass it to the frozenset constructor, so we still end up promoting literals in that process.)

To be clear, I don't want you to weight this ty implementation issue too much -- I'd rather first hear from other typing council members what they think a good scope is here.

Josverl · 2026-08-28T13:34:53Z

Gentle reminder for additional feedback.

See python/typing#2173

See python/typing#2173.

JelleZijlstra · 2026-08-29T17:40:52Z

Here's a summary of what type checkers already support (courtesy of Codex):

Proposed behavior	mypy	Pyright	ty	Pyrefly
sys.version_info >= (M, m) and < (M, m)	Yes	Yes	Yes	Yes
sys.platform == literal and != literal	Yes	Yes	Yes	Yes
sys.platform.startswith(literal)	Yes	No	Yes	Yes
sys.platform in tuple	No	No	Yes	Yes
sys.platform not in tuple	No	No	Yes	Yes
sys.implementation.name == / !=	No	No	No	No
sys.implementation.name in / not in	No	No	No	No
sys.implementation.version >= / <	No	No	No	No
Combining recognized checks with not, and, and or	Yes	Yes	Yes	Yes
Configure target Python version	Yes	Yes	Yes	Yes
Configure target sys.platform	Yes	Partial	Yes	Yes
Configure implementation name or version	No	No	No	No

So nobody supports any sys.implementation checks. Support for slightly more advanced sys.platform checks is a bit varied. I had Codex look through past GitHub issues and it wasn't able to find much demand for in/not in checks, which makes me think that part is maybe not worth the trouble. On the other hand, ty and Pyrefly already support those (in Pyrefly's case, apparently as a result of some of the discussion around this PR), and it doesn't seem like an onerous feature to add.

This is proposed for the spec in python/typing#2173. It is trivial to support in mypy and seems useful, so let's add it.

Also : - wrapped lines to ~85 characters - tables to 110 characters - Improved .rst formatting and markup The Intent is for these commits allow tracability of review comments, but to be squashed to a single commit during merge. Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>

Inline list and set membership tests now preserve the values of their individual elements, allowing ty to determine when a condition is always true or false. With the target platform set to Linux, both `sys.platform in ["linux", "windows"]` and `sys.platform in {"linux", "windows"}` select only the matching branch, so an assignment there is inferred as `Literal[1]`. Reuse the precise element extraction used for iteration and membership narrowing without changing the inferred container type. Lists and sets use the existing tuple membership equality evaluator, including its identity-or-equality behavior. For sets, assume equality is an equivalence relation and equal objects have equal hashes. Checking reflexive equality across union alternatives also improves existing tuple membership inference. Context is that in python/typing#2173 people are wanting to specify that `sys.platform in ["linux", "windows"]` should work. This makes it work in ty so that we can be fine with any outcome of that specification change. ## Test plan Mdtests cover platform-dependent branch reachability; positive and negative membership in inline lists and sets; inferred literal values and unions; fixed-length unpacking; stored mutable containers; custom equality and identity; comparison chains; and preservation of enum-set narrowing. ## Ecosystem report The comparison for head `90111f10da9359722abb903351b89aaae0f9bcba` adds four `redundant-condition-strict` warnings. The paasta and SciPy warnings correctly identify disjoint membership checks. The dd-trace-py warning exposes existing limitations in modeling dynamic `setattr`; the Scrapy warning exposes existing attribute narrowing across method calls and `await`. Equivalent equality checks already exhibit both limitations on the base revision. These existing limitations are accepted for this change. See the [full ecosystem report](#28676 (comment)) for minimized examples and exact comparison details.

Josverl · 2026-10-07T21:35:17Z

Just to avoid unneeded waiting:
I think I have responded to all review comments; but have not marked them as resolved (as earlier I was to eager to close)
Please let me know if further clarifications or updates are requested, or that things are clear.

Josverl · 2026-10-19T21:35:25Z

@carljm,
Sorry for the delay in addressing your latest suggestions & comments.

CI also seems to have forgotten that I did sign the CLA with all my identities, re-signing is not possible either.
Not sure what I can do about that.

carljm

I think the CLA signing failure is because your latest commit (unlike the previous ones) is authored by Jos_Verlinde@hotmail.com, which GitHub can't associate with your GitHub account. If you can amend that commit with a recognized email address and force push, I suspect the CLA signing check will pass.

Barring my two nits below, I think this PR is ready for conformance tests. @jorenham @davidhalter @JelleZijlstra @rchen152 any objections to the spec updates here, before @Josverl writes conformance tests?

jorenham · 2026-10-20T08:19:44Z

I'll try to take a look this evening

jorenham

Looks good overall, thanks. I left some comments for some minor issues / nits / suggestions.

jorenham · 2026-10-20T19:26:51Z

+Required forms and optional extensions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Type checkers must support the forms specified above as required. Support for additional 


consistency nit

Suggested change

Type checkers must support the forms specified above as required. Support for additional

Type checkers should support the forms specified above as required. Support for additional

I do not think that "should" can be combined with "required" in this sentence.
That would degrade the meaning of the "required" statements in the prior paragraphs, which I think is incorrect.

Minor changes to wording and formatting. Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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

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

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

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

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

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

jorenham reviewed Aug 9, 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

carljm reviewed Aug 10, 2026

View reviewed changes

Josverl and others added 4 commits August 15, 2026 22:15

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

e34cbc7

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

Update docs/spec/directives.rst

33c4477

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

Clarify language in directives regarding named attribute usage in ver…

2c4e700

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

spec/directives: Process review comments.

98e3697

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

Josverl force-pushed the specs/sys.implementation.name branch from b3b76c1 to 98e3697 Compare August 15, 2026 20:18

Josverl reopened this Aug 17, 2026

JelleZijlstra reviewed Aug 29, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst

Comment thread docs/spec/directives.rst Outdated

This was referenced Aug 29, 2026

Support more sys.platform/implementation/etc. conditions JelleZijlstra/typeshed_client#155

Merged

Support more platform/implementation checks JelleZijlstra/pycroscope#551

Merged

JelleZijlstra added a commit to JelleZijlstra/typeshed_client that referenced this pull request Aug 29, 2026

Support more sys.platform/implementation/etc. conditions (#155)

a93fc24

See python/typing#2173

JelleZijlstra added a commit to JelleZijlstra/pycroscope that referenced this pull request Aug 29, 2026

Support more platform/implementation checks (#551)

8e014b9

See python/typing#2173.

JelleZijlstra mentioned this pull request Aug 29, 2026

Support in/not in tests on sys.platform python/mypy#21913

Merged

hauntsaninja pushed a commit to python/mypy that referenced this pull request Sep 1, 2026

Support in/not in tests on sys.platform (#21913)

deda499

This is proposed for the spec in python/typing#2173. It is trivial to support in mypy and seems useful, so let's add it.

spec/directives: Process additional review comments.

4ca8fd6

carljm reviewed Sep 16, 2026

View reviewed changes

carljm mentioned this pull request Sep 17, 2026

[ty] Infer constant membership in inline list and set literals astral-sh/ruff#28676

Merged

carljm reviewed Oct 7, 2026

View reviewed changes

carljm reviewed Oct 20, 2026

View reviewed changes

Comment thread docs/spec/directives.rst Outdated

Comment thread docs/spec/directives.rst Outdated

jorenham reviewed Oct 20, 2026

View reviewed changes

Josverl force-pushed the specs/sys.implementation.name branch from d027211 to bc8965e Compare October 21, 2026 21:13

Address review comments and suggestions.

d2c4133

Minor changes to wording and formatting. Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Josverl force-pushed the specs/sys.implementation.name branch from bc8965e to d2c4133 Compare October 23, 2026 13:19

Josverl mentioned this pull request Oct 23, 2026

conformance: Add conformance tests for implementation and platform checks. #2375

Draft

	Type checkers must support the forms specified above as required. Support for additional
	Type checkers should support the forms specified above as required. Support for additional

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

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!

carljm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josverl commented Aug 10, 2026

Uh oh!

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

Uh oh!

Uh oh!

carljm commented Aug 17, 2026

Uh oh!

Josverl commented Aug 17, 2026

Uh oh!

AlexWaygood commented Aug 17, 2026

Uh oh!

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

Uh oh!

Uh oh!

jorenham commented Aug 17, 2026

Uh oh!

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

Uh oh!

Uh oh!

Josverl commented Aug 28, 2026

Uh oh!

Uh oh!

Uh oh!

Josverl commented Feb 12, 2026 •

edited

Loading

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

edited

Loading

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

Josverl commented Aug 15, 2026 •

edited

Loading

carljm commented Aug 17, 2026 •

edited

Loading

carljm commented Aug 17, 2026 •

edited

Loading

Josverl commented Oct 19, 2026 •

edited

Loading