Skip to content

Commit e612515

Browse files
committed
Update specification for directives for sys.implementation and sys.platform checks.
Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>
1 parent d06c5dd commit e612515

1 file changed

Lines changed: 214 additions & 13 deletions

File tree

‎docs/spec/directives.rst‎

Lines changed: 214 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -154,23 +154,224 @@ 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 understand code paths as definitely reachable or not reachable
158+
due to comparison tests against these symbols:
159159

160-
import sys
160+
* ``sys.version_info``
161+
* ``sys.platform``
162+
* ``sys.implementation.version``
163+
* ``sys.implementation.name``
161164

162-
if sys.version_info >= (3, 12):
163-
# Python 3.12+
164-
else:
165-
# Python 3.11 and lower
165+
Type checkers should support combining these checks with:
166166

167-
if sys.platform == 'win32':
168-
# Windows specific definitions
169-
else:
170-
# Posix specific definitions
167+
* A ``not`` unary operator
168+
* An ``and`` or ``or`` binary operator
171169

172-
Don't expect a checker to understand obfuscations like
173-
``"".join(reversed(sys.platform)) == "xunil"``.
170+
Type checkers are only required to support the fully qualified form
171+
(e.g., ``sys.platform``). Support for aliases or import variants
172+
(e.g., ``from sys import platform``) is not required, though type checkers may
173+
choose to support them.
174+
175+
The comparison patterns for these variables are described in more detail in the
176+
following paragraphs.
177+
178+
sys.version_info checks
179+
^^^^^^^^^^^^^^^^^^^^^^^^
180+
181+
Type checkers should support the following comparison patterns:
182+
183+
* ``sys.version_info >= <2-tuple>``
184+
* ``sys.version_info < <2-tuple>``
185+
186+
where ``<2-tuple>`` is a literal tuple of two literal integers.
187+
188+
Required support is limited to comparisons against literal two-element tuples.
189+
Type checkers may choose to also support comparisons against three-element tuple
190+
literals: ``sys.version_info >= <3-tuple>``. Type checkers are not expected to
191+
support comparisons with named attributes of ``sys.version_info``.
192+
193+
.. code-block:: python
194+
:caption: Examples of ``sys.version_info`` checks
195+
:emphasize-lines: 2,4
196+
197+
import sys
198+
if sys.version_info >= (3, 13):
199+
# Python 3.13+
200+
elif sys.version_info < (3, 11):
201+
# Python 3.10 and lower
202+
else:
203+
# Python 3.11, 3.12
204+
205+
sys.platform checks
206+
^^^^^^^^^^^^^^^^^^^
207+
208+
Type checkers should support the following comparison patterns:
209+
210+
* ``sys.platform == <string literal>``
211+
* ``sys.platform != <string literal>``
212+
* ``sys.platform.startswith(<string literal>)``
213+
* ``sys.platform in <literal tuple of string literals>``
214+
* ``sys.platform in <literal set of string literals>``
215+
* ``sys.platform in <literal list of string literals>``
216+
* ``sys.platform not in <literal tuple of string literals>``
217+
* ``sys.platform not in <literal set of string literals>``
218+
* ``sys.platform not in <literal list of string literals>``
219+
220+
Common values: ``"linux"``, ``"darwin"``, ``"win32"``, ``"emscripten"``,
221+
``"wasi"``
222+
223+
The membership checks ``in`` and ``not in`` only support simple containment
224+
testing with a literal tuple, literal set, or literal list of literal strings.
225+
226+
.. code-block:: python
227+
:caption: Examples of ``sys.platform`` checks
228+
:emphasize-lines: 2,4,6,8
229+
230+
import sys
231+
if sys.platform == "win32":
232+
# Windows-specific definitions
233+
elif sys.platform in ("linux", "darwin"):
234+
# Platform-specific stubs for Linux and macOS
235+
elif sys.platform.startswith("freebsd"):
236+
# FreeBSD-specific stubs, including versions such as "freebsd8"
237+
if sys.platform not in ["wasi", "emscripten"]:
238+
# Stubs for platforms other than WASI and Emscripten
239+
240+
241+
sys.implementation.name checks
242+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
243+
244+
Type checkers should support these comparison patterns with
245+
``sys.implementation.name``:
246+
247+
* ``sys.implementation.name == <string literal>``
248+
* ``sys.implementation.name != <string literal>``
249+
* ``sys.implementation.name in <literal tuple of string literals>``
250+
* ``sys.implementation.name in <literal set of string literals>``
251+
* ``sys.implementation.name in <literal list of string literals>``
252+
* ``sys.implementation.name not in <literal tuple of string literals>``
253+
* ``sys.implementation.name not in <literal set of string literals>``
254+
* ``sys.implementation.name not in <literal list of string literals>``
255+
256+
Default value: ``"cpython"``, unless configured otherwise.
257+
258+
Common values: ``"cpython"``, ``"pypy"``, ``"micropython"``, ``"graalpy"``,
259+
``"android"``, ``"ios"``, ``"ironpython"``
260+
261+
.. code-block:: python
262+
:caption: Examples of ``sys.implementation.name`` checks
263+
:emphasize-lines: 2,4
264+
265+
import sys
266+
if sys.implementation.name == "cpython":
267+
# CPython-specific stub
268+
if sys.implementation.name == "micropython":
269+
# MicroPython-specific stub
270+
271+
272+
sys.implementation.version checks
273+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
274+
275+
The value of ``sys.implementation.version`` is a tuple, in a similar format as
276+
``sys.version_info``. However, it represents the version of the
277+
*Python implementation* rather than the version of the *Python language*. This has
278+
a distinct meaning from the specific version of the Python language to which the
279+
currently running interpreter conforms.
280+
281+
For CPython (``sys.implementation.name == "cpython"``) this is the same as
282+
``sys.version_info``.
283+
For other Python implementations the value of ``sys.implementation.version`` may
284+
be specified in the type checker configuration or discovered at runtime.
285+
286+
Type checkers should support the following comparison patterns:
287+
288+
* ``sys.implementation.version >= <2-tuple>``
289+
* ``sys.implementation.version < <2-tuple>``
290+
291+
Required support is limited to comparisons against literal two-element tuples.
292+
Type checkers may choose to also support comparisons against three-element tuple
293+
literals of ``sys.implementation.version``.
294+
Type checkers are not required to support comparisons against named attributes
295+
of ``sys.implementation.version``.
296+
297+
.. code-block:: python
298+
:caption: Examples of ``sys.implementation.version`` checks
299+
:emphasize-lines: 2,4
300+
301+
import sys
302+
if sys.implementation.name == "pypy" and sys.implementation.version >= (7, 3):
303+
# PyPy version 7.3 and above
304+
elif sys.implementation.name == "micropython" and sys.implementation.version >= (1, 24):
305+
# MicroPython version 1.24 and above
306+
307+
308+
os.name checks
309+
^^^^^^^^^^^^^^
310+
311+
Type checkers may optionally support comparisons of ``os.name`` with string
312+
literals.
313+
314+
* ``os.name == <string literal>``
315+
* ``os.name != <string literal>``
316+
317+
.. code-block:: python
318+
:caption: Example of an ``os.name`` check
319+
:emphasize-lines: 3
320+
321+
import os
322+
323+
if os.name == "posix":
324+
# POSIX-specific code
325+
326+
Required forms and optional extensions
327+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
328+
329+
Type checkers must support the forms specified above as required. Support for additional
330+
comparison patterns and syntax forms is optional. For example,
331+
type checkers are not required to support the following forms:
332+
333+
.. code-block:: python
334+
:caption: Examples of forms that type checkers are not required to support
335+
:emphasize-lines: 4,6,8
336+
337+
import sys
338+
from sys import platform
339+
340+
if "".join(reversed(sys.platform)) == "xunil":
341+
# Comparison using a computed value
342+
if platform == "linux":
343+
# Comparison using an imported alias
344+
if "win" not in sys.platform:
345+
# Substring membership test against sys.platform
346+
347+
Configuration
348+
^^^^^^^^^^^^^
349+
350+
Type checkers should be able to retrieve the information from the Python
351+
implementation's runtime environment, or provide configuration or CLI options
352+
to specify target ``sys.version_info``, ``sys.platform``,
353+
``sys.implementation.name`` and ``sys.implementation.version``.
354+
355+
============================== ======================== ============= =====================================
356+
Symbol Suggested Format Example Suggested Default
357+
============================== ======================== ============= =====================================
358+
``sys.version_info`` string ``"major.minor"`` ``"3.11"`` The version of the Python interpreter
359+
used to run the type checker.
360+
``sys.platform`` lowercase string ``"linux"`` The platform of the Python interpreter
361+
used to run the type checker.
362+
``sys.implementation.name`` lowercase string ``"cpython"`` ``"cpython"`` unless configured
363+
otherwise.
364+
``sys.implementation.version`` string ``"major.minor"`` ``"3.14"`` On CPython, default to the value used
365+
for ``sys.version_info``. On other
366+
implementations, the value should be
367+
provided in configuration or
368+
otherwise inferred.
369+
============================== ======================== ============= =====================================
370+
371+
The configuration options should allow users to specify the target values for these
372+
symbols, so that type checkers can evaluate the version and platform checks
373+
correctly. The exact mechanism and names for these configuration options are
374+
implementation-specific and defined by each type checker.
174375

175376
.. _`deprecated`:
176377

0 commit comments

Comments
 (0)