You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e34cbc7
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -154,23 +154,141 @@ left undefined by the typing spec at this time.
154
154
Version and platform checking
155
155
-----------------------------
156
156
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``
159
162
160
-
import sys
163
+
Type checkers should support combining these checks with:
164
+
* A ``not`` unary operator
165
+
* An ``and`` or ``or`` binary operator
161
166
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.
166
169
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.
171
171
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"notin 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.
0 commit comments