Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Josverl wants to merge 6 commits into
base: main
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e34cbc7
Update specification for directives for sys.implementation and sys.pl…
Josverl Aug 15, 2026
33c4477
Update docs/spec/directives.rst
Josverl Aug 15, 2026
2c4e700
Clarify language in directives regarding named attribute usage in ver…
Josverl Aug 15, 2026
98e3697
spec/directives: Process review comments.
Josverl Aug 15, 2026
4ca8fd6
spec/directives: Process additional review comments.
Josverl Sep 8, 2026
c0639dd
spec/directives: Process additional review comments.
Josverl Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
spec/directives: Process additional review comments.
  • Loading branch information
@Josverl
Josverl committed Sep 8, 2026
commit 4ca8fd6399cde04dcd7996dcbdc8605b71ebdd39
9 changes: 6 additions & 3 deletions docs/spec/directives.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ Type checkers should support the following comparison patterns:
* ``sys.version_info < <2-tuple>``

Comparison checks are only supported against the first two elements of the version tuple.
It should be noted that type checkers may choose to also support the 3-tuple ``sys.version_info >= <3-tuple>``.
Type checkers may choose to also support the 3-tuple ``sys.version_info >= <3-tuple>``.
Type checkers are not expected to support comparisons with named attributes of `sys.version_info`.

.. code-block:: python
Expand All @@ -199,6 +199,9 @@ Type checkers should support the following comparison patterns:
* ``sys.platform == <string literal>``
* ``sys.platform != <string literal>``
* ``sys.platform.startswith(<string literal>)``
* ``sys.platform in <tuple of string literals>``
* ``sys.platform not in <tuple of string literals>``

@jorenham jorenham Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jorenham jorenham Aug 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@carljm carljm Aug 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ty already supports sys.platform.startswith; I don't have any objection there.

Supporting set literals will be a little tricky in ty, but should be doable, and I'm not opposed to requiring support for it. I don't think the performance motivation of PLR6201 typically applies much to sys.version_info comparisons, but it is awkward if this rule is generally being applied in a codebase and has to be specifically ignored for sys.version_info checks.

@Josverl Josverl Aug 15, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change to set and added sys.platform.startswith(<string literal>)

@carljm carljm Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, I think that both tuple and set literals should be specified as supported -- it would be surprising IMO if sets work and tuples don't.

This is perhaps an argument against supporting sets -- it opens a bit of a slippery slope: why not lists? etc

@Josverl Josverl Aug 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

my original proposal was tuples, as that is one of the core building blocks of Python.
I don't think that for this scale sets have a real benefit over tuples.

I'd like it to be straight and narrow though ,
requiring tuple + set = is still ok , though I notice that ruff mentions 'This rule is unstable and in preview.'
adding lists would start to 🛝

Pausing edits until there is consensus

@carljm carljm Sep 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After considering it more, I think we should just leave sets out entirely. I wouldn't even mention them as optional: there's no point, since type checkers are always free to support anything they want beyond the spec.

I don't believe there is any actual performance benefit at this scale, and it's not necessary to add complexity to the spec or to type checkers when comparing to a tuple is perfectly usable and functional. The ruff rule is unstable and I think if this spec change is merged, the ruff rule should just be updated to specifically exclude these typing-supported comparisons, so there is no conflict. I don't think the ruff rule should motivate adding sets to the spec.

Type checkers may also support the following comparison patterns:
* ``sys.platform in <set of string literals>``
* ``sys.platform not in <set of string literals>``

Expand Down Expand Up @@ -247,7 +250,7 @@ sys.implementation.version checks

``sys.implementation.version`` is a tuple, in the same format as sys.version_info. However it represents the version of the Python implementation
Comment thread
Josverl marked this conversation as resolved.
Outdated
rather than the version of the Python language. This has a distinct meaning from the specific version of the Python language to which the currently
running interpreter conforms. For CPython this is the same as `sys.version_info`.
running interpreter conforms. For CPython (``sys.implementation.name == "cpython"``) this is the same as `sys.version_info`.

@carljm carljm Sep 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
running interpreter conforms. For CPython (``sys.implementation.name == "cpython"``) this is the same as `sys.version_info`.
running interpreter conforms. For CPython (``sys.implementation.name == "cpython"``) this is the same as ``sys.version_info``.


Type checkers should support the following comparison patterns:
Comment thread
Josverl marked this conversation as resolved.
* ``sys.implementation.version >= <2-tuple>``
Expand Down Expand Up @@ -292,7 +295,7 @@ Therefore checkers are **not required** to understand obfuscations such as:
Configuration
^^^^^^^^^^^^^

Type checkers must provide configuration or CLI options to specify target ``sys.version``, ``sys.platform``, ``sys.implementation.name`` and ``sys.implementation.version``.
Type checkers must be able to retrieve the information from the python implementation's runtime environment, or provide configuration or CLI options to specify target ``sys.version``, ``sys.platform``, ``sys.implementation.name`` and ``sys.implementation.version``.

@carljm carljm Sep 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be sys.version_info, not sys.version.

Also word-wrap to 80 columns (throughout).

@Josverl Josverl Sep 21, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected to version_info

In order to blanace width with readability, I have wrapped the table at 110 columns, which is still slightly narrower than the HTML render.
Wrapping to 80 would leave less than 1 word per line for the 4th column


================================ ========================== ============== ===========================================================================
Symbol Suggested Format Example Suggested Default
Expand Down