Skip to content

Commit e34cbc7

Browse files
committed
Update specification for directives for sys.implementation and sys.platform checks.
Signed-off-by: Jos Verlinde <Jos.Verlinde@Microsoft.com>
1 parent dcffbae commit e34cbc7

1 file changed

Lines changed: 131 additions & 13 deletions

File tree

‎docs/spec/directives.rst‎

Lines changed: 131 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -154,23 +154,141 @@ left undefined by the typing spec at this time.
154154
Version and platform checking
155155
-----------------------------
156156

157-
Type checkers are expected to understand simple version and platform
158-
checks, e.g.::
157+
Type checkers should support narrowing based on:
158+
* ``sys.version_info``
159+
* ``sys.platform``
160+
* ``sys.implementation.version``
161+
* ``sys.implementation.name``
159162

160-
import sys
163+
Type checkers should support combining these checks with:
164+
* A ``not`` unary operator
165+
* An ``and`` or ``or`` binary operator
161166

162-
if sys.version_info >= (3, 12):
163-
# Python 3.12+
164-
else:
165-
# Python 3.11 and lower
167+
Type checkers are only required to support the fully-qualified form (e.g., ``sys.platform``).
168+
Support for aliases or import variants (e.g., ``from sys import platform``) is not required, though type checkers may choose to support them.
166169

167-
if sys.platform == 'win32':
168-
# Windows specific definitions
169-
else:
170-
# Posix specific definitions
170+
The comparison patterns for these variables are described in more detail in the following paragraphs.
171171

172-
Don't expect a checker to understand obfuscations like
173-
``"".join(reversed(sys.platform)) == "xunil"``.
172+
sys.version_info checks
173+
^^^^^^^^^^^^^^^^^^^^^^^^
174+
175+
Type checkers should support the following comparison patterns:
176+
* ``sys.version_info >= <2-tuple>``
177+
* ``sys.version_info < <2-tuple>``
178+
179+
Comparisons checks are only supported against the first two elements of the version tuple.
180+
Use of named attributes is not supported.
181+
182+
.. code-block:: python
183+
:caption: Example `sys.version_info`
184+
:emphasize-lines: 2
185+
186+
import sys
187+
if sys.version_info >= (3, 12):
188+
# Python 3.12+
189+
else:
190+
# Python 3.11 and lower
191+
192+
sys.platform checks
193+
^^^^^^^^^^^^^^^^^^^
194+
195+
Type checkers should support the following comparison patterns:
196+
* ``sys.platform == <string literal>``
197+
* ``sys.platform != <string literal>``
198+
* ``sys.platform in <tuple of string literals>``
199+
* ``sys.platform not in <tuple of string literals>``
200+
201+
Common values: ``"linux"``, ``"darwin"``, ``"win32"``, ``"emscripten"``, ``"wasi"``
202+
203+
The membership checks ``in`` and ``not in``, only support simple containment testing to a tuple of literal strings.
204+
205+
.. code-block:: python
206+
:caption: Example `sys.platform`
207+
:emphasize-lines: 2,4
208+
209+
import sys
210+
if sys.platform == 'win32':
211+
# Windows specific definitions
212+
if sys.platform in ("linux", "darwin"):
213+
# Platform-specific stubs for Linux and macOS
214+
...
215+
216+
217+
sys.implementation.name checks
218+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
219+
220+
Type checkers should support comparison patterns:
221+
* ``sys.implementation.name == <string literal>``
222+
* ``sys.implementation.name != <string literal>``
223+
* ``sys.implementation.name in <tuple of string literals>``
224+
* ``sys.implementation.name not in <tuple of string literals>``
225+
226+
Common values: ``"cpython"``, ``"pypy"``, ``"micropython"``, ``"graalpy"``, ``"jython"``, ``"ironpython"``
227+
228+
.. code-block:: python
229+
:caption: Example `sys.implementation.name`
230+
:emphasize-lines: 2,4
231+
232+
import sys
233+
if sys.implementation.name == "cpython":
234+
# CPython-specific stub
235+
if sys.implementation.name == "micropython":
236+
# MicroPython-specific stub
237+
238+
239+
sys.implementation.version checks
240+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
241+
242+
Type checkers should support the following comparison patterns:
243+
* ``sys.implementation.version >= <2-tuple>``
244+
* ``sys.implementation.version < <2-tuple>``
245+
246+
Comparisons checks are only supported against the first two elements of the implementation version tuple.
247+
Use of named attributes is not supported.
248+
249+
.. code-block:: python
250+
:caption: Example `sys.implementation.version`
251+
:emphasize-lines: 2,4
252+
253+
import sys
254+
if sys.implementation.name == "pypy" and sys.implementation.version >= (7, 3):
255+
# PyPy version 7.3 and above
256+
if sys.implementation.name == "micropython" and sys.implementation.version >= (1, 24):
257+
# MicroPython version 1.24 and above
258+
259+
.. note::
260+
261+
``sys.implementation.version`` is a tuple, in the same format as sys.version_info. However it represents the version of the Python implementation rather than the version of the Python language.
262+
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`.
263+
264+
265+
No support for complex expressions
266+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
267+
268+
Type checkers are only required to support the above patterns, and are not required to evaluate complex expressions involving these variables.
269+
For example, the pattern ``sys.platform == "linux"`` is supported but other syntax variants such as ``platform == "linux"`` and ``"win" not in sys.platform`` are not supported.
270+
271+
Therefore checkers are **not required** to understand obfuscations such as:
272+
273+
.. code-block:: python
274+
:caption: Examples of unsupported or overly complex version/platform checks
275+
:emphasize-lines: 3,5,7
276+
277+
import sys
278+
from sys import platform
279+
if "".join(reversed(sys.platform)) == "xunil":
280+
# Linux specific code
281+
if platform == "linux":
282+
# Linux specific code
283+
if "win" not in sys.platform:
284+
# Non-Windows specific code
285+
286+
287+
Configuration
288+
^^^^^^^^^^^^^
289+
290+
Type checkers should provide configuration or CLI options to specify target sys.version, sys.platform, sys.implementation.name and sys.implementation.version.
291+
The exact mechanism for this is implementation-defined by the type checker.
174292

175293
.. _`deprecated`:
176294

0 commit comments

Comments
 (0)