@@ -154,23 +154,224 @@ left undefined by the typing spec at this time.
154154Version 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