@@ -154,88 +154,111 @@ left undefined by the typing spec at this time.
154154Version and platform checking
155155-----------------------------
156156
157- Type checkers should understand code paths as definitely reachable or not reachable due to comparison tests against these symbols:
158- * ``sys.version_info ``
159- * ``sys.platform ``
160- * ``sys.implementation.version ``
161- * ``sys.implementation.name ``
157+ Type checkers should understand code paths as definitely reachable or not reachable
158+ due to comparison tests against these symbols:
159+
160+ * ``sys.version_info ``
161+ * ``sys.platform ``
162+ * ``sys.implementation.version ``
163+ * ``sys.implementation.name ``
162164
163165Type checkers should support combining these checks with:
164- * A ``not `` unary operator
165- * An ``and `` or ``or `` binary operator
166166
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.
167+ * A ``not `` unary operator
168+ * An ``and `` or ``or `` binary operator
169+
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.
169174
170- The comparison patterns for these variables are described in more detail in the following paragraphs.
175+ The comparison patterns for these variables are described in more detail in the
176+ following paragraphs.
171177
172178sys.version_info checks
173179^^^^^^^^^^^^^^^^^^^^^^^^
174180
175181Type checkers should support the following comparison patterns:
176- * ``sys.version_info >= <2-tuple> ``
177- * ``sys.version_info < <2-tuple> ``
178182
179- Comparison checks are only supported against the first two elements of the version tuple.
180- Type checkers may choose to also support the 3-tuple ``sys.version_info >= <3-tuple> ``.
181- Type checkers are not expected to support comparisons with named attributes of `sys.version_info `.
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+ Comparison checks are only supported against the first two elements of the version
189+ tuple. Type checkers may choose to also support the 3-tuple
190+ ``sys.version_info >= <3-tuple> ``. Type checkers are not expected to support
191+ comparisons with named attributes of ``sys.version_info ``.
182192
183193.. code-block :: python
184- :caption: Example ` sys.version_info`
185- :emphasize- lines: 2
194+ :caption: Examples of `` sys.version_info`` checks
195+ :emphasize- lines: 2 , 4
186196
187197 import sys
188- if sys.version_info >= (3 , 12 ):
189- # Python 3.12+
190- elif sys.version_info >= (3 , 11 ):
191- # Python 3.11
192- else :
198+ if sys.version_info >= (3 , 13 ):
199+ # Python 3.13+
200+ elif sys.version_info < (3 , 11 ):
193201 # Python 3.10 and lower
202+ else :
203+ # Python 3.11, 3.12
194204
195205 sys.platform checks
196206^^^^^^^^^^^^^^^^^^^
197207
198208Type checkers should support the following comparison patterns:
199- * ``sys.platform == <string literal> ``
200- * ``sys.platform != <string literal> ``
201- * ``sys.platform.startswith(<string literal>) ``
202- * ``sys.platform in <tuple of string literals> ``
203- * ``sys.platform not in <tuple of string literals> ``
204- Type checkers may also support the following comparison patterns:
205- * ``sys.platform in <set of string literals> ``
206- * ``sys.platform not in <set of string literals> ``
207209
208- Common values: ``"linux" ``, ``"darwin" ``, ``"win32" ``, ``"emscripten" ``, ``"wasi" ``
210+ * ``sys.platform == <string literal> ``
211+ * ``sys.platform != <string literal> ``
212+ * ``sys.platform.startswith(<string literal>) ``
213+ * ``sys.platform in <tuple of string literals> ``
214+ * ``sys.platform in <set of string literals> ``
215+ * ``sys.platform in <list of string literals> ``
216+ * ``sys.platform not in <tuple of string literals> ``
217+ * ``sys.platform not in <set of string literals> ``
218+ * ``sys.platform not in <list of string literals> ``
219+
220+ Common values: ``"linux" ``, ``"darwin" ``, ``"win32" ``, ``"emscripten" ``,
221+ ``"wasi" ``
209222
210- The membership checks ``in `` and ``not in `` only support simple containment testing with a set of literal strings.
223+ The membership checks ``in `` and ``not in `` only support simple containment
224+ testing with a tuple, set, or list of literal strings.
211225
212226.. code-block :: python
213- :caption: Example ` sys.platform`
214- :emphasize- lines: 2 ,4
227+ :caption: Examples of `` sys.platform`` checks
228+ :emphasize- lines: 2 ,4 , 6 , 8
215229
216230 import sys
217- if sys.platform == ' win32' :
218- # Windows specific definitions
219- if sys.platform in (" linux" , " darwin" ):
231+ if sys.platform == " win32" :
232+ # Windows- specific definitions
233+ elif sys.platform in (" linux" , " darwin" ):
220234 # Platform-specific stubs for Linux and macOS
221- ...
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
222239
223240
224241 sys.implementation.name checks
225242^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
226243
227244Type checkers should support comparison patterns:
228- * ``sys.implementation.name == <string literal> ``
229- * ``sys.implementation.name != <string literal> ``
230- * ``sys.implementation.name in <set of string literals> ``
231- * ``sys.implementation.name not in <set of string literals> ``
232245
233- Default value: ``"cpython" ``, unless configured otherwise.
234- Common values: ``"cpython" ``, ``"pypy" ``, ``"micropython" ``, ``"graalpy" ``, ``"jython" ``, ``"ironpython" ``
246+ * ``sys.implementation.name == <string literal> ``
247+ * ``sys.implementation.name != <string literal> ``
248+ * ``sys.implementation.name in <tuple of string literals> ``
249+ * ``sys.implementation.name in <set of string literals> ``
250+ * ``sys.implementation.name in <list of string literals> ``
251+ * ``sys.implementation.name not in <tuple of string literals> ``
252+ * ``sys.implementation.name not in <set of string literals> ``
253+ * ``sys.implementation.name not in <list of string literals> ``
254+
255+ Default value: ``"cpython" ``, unless configured otherwise.
235256
257+ Common values: ``"cpython" ``, ``"pypy" ``, ``"micropython" ``, ``"graalpy" ``,
258+ ``"jython" ``, ``"ironpython" ``
236259
237260.. code-block :: python
238- :caption: Example ` sys.implementation.name`
261+ :caption: Examples of `` sys.implementation.name`` checks
239262 :emphasize- lines: 2 ,4
240263
241264 import sys
@@ -248,66 +271,89 @@ Type checkers should support comparison patterns:
248271 sys.implementation.version checks
249272^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
250273
251- ``sys.implementation.version `` is a tuple, in the same format as sys.version_info. However it represents the version of the Python implementation
252- 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
253- running interpreter conforms. For CPython (``sys.implementation.name == "cpython" ``) this is the same as `sys.version_info `.
274+ The value of ``sys.implementation.version `` is a tuple, in the same format as
275+ ``sys.version_info ``. However, it represents the version of the
276+ *Python implementation * rather than the version of the *Python language *. This has
277+ a distinct meaning from the specific version of the Python language to which the
278+ currently running interpreter conforms.
279+
280+ For CPython (``sys.implementation.name == "cpython" ``) this is the same as
281+ ``sys.version_info ``.
282+ For other Python implementations the value of ``sys.implementation.version `` may
283+ differ and must be specified according to the type checkers'
284+ configuration options. If it is not specified, type checkers should issue a warning
285+ or error if it is used in a type-checking context.
254286
255287Type checkers should support the following comparison patterns:
256- * ``sys.implementation.version >= <2-tuple> ``
257- * ``sys.implementation.version < <2-tuple> ``
258288
259- Comparison checks are only supported against the first two elements of the implementation version tuple.
260- Type checkers are not required to support comparisons against named attributes of `sys.implementation.version `.
289+ * ``sys.implementation.version >= <2-tuple> ``
290+ * ``sys.implementation.version < <2-tuple> ``
291+
292+ Comparison checks are only supported against the first two elements of the
293+ implementation version tuple. Type checkers are not required to support comparisons
294+ against named attributes of ``sys.implementation.version ``.
261295
262296.. code-block :: python
263- :caption: Example ` sys.implementation.version`
297+ :caption: Examples of `` sys.implementation.version`` checks
264298 :emphasize- lines: 2 ,4
265299
266300 import sys
267301 if sys.implementation.name == " pypy" and sys.implementation.version >= (7 , 3 ):
268302 # PyPy version 7.3 and above
269- if sys.implementation.name == " micropython" and sys.implementation.version >= (1 , 24 ):
303+ elif sys.implementation.name == " micropython" and sys.implementation.version >= (1 , 24 ):
270304 # MicroPython version 1.24 and above
271305
272306
273- No support for complex expressions
274- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
307+ Required forms and optional extensions
308+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275309
276- Type checkers are required to support the above patterns, and are not required to evaluate other comparisons or other syntax variants.
277-
278- Therefore checkers are ** not required ** to understand obfuscations such as :
310+ Type checkers must support the forms described above. They may support additional
311+ comparisons and syntax forms, but are not required to recognize them. For example,
312+ type checkers are not required to support the following forms :
279313
280314.. code-block :: python
281- :caption: Examples of unsupported or overly complex version / platform checks
282- :emphasize- lines: 4 ,6 ,8
315+ :caption: Examples of forms that type checkers are not required to support
316+ :emphasize- lines: 4 ,6 ,8
283317
284- import sys
285- from sys import platform
318+ import sys
319+ from sys import platform
286320
287- if " " .join(reversed (sys.platform)) == " xunil" :
288- # Typecheckers will not be required to understand this obfuscated check
289- if platform == " linux" :
290- # Typecheckers will not be required to understand this import alias for sys.platform
291- if " win" not in sys.platform:
292- # Typecheckers will not be required to understand this reversed membership check
321+ if " " .join(reversed (sys.platform)) == " xunil" :
322+ # Comparison using a computed value
323+ if platform == " linux" :
324+ # Comparison using an imported alias
325+ if " win" not in sys.platform:
326+ # Substring membership test against sys.platform
293327
294328
295329 Configuration
296330^^^^^^^^^^^^^
297331
298- 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 ``.
299-
300- ================================ ========================== ============== ===========================================================================
301- Symbol Suggested Format Example Suggested Default
302- ================================ ========================== ============== ===========================================================================
303- ``sys.version `` string ``"major.minor" `` ``"3.11" `` The version of the Python interpreter used to run the type checker.
304- ``sys.platform `` lowercase string ``"linux" `` The platform of the Python interpreter used to run the type checker.
305- ``sys.implementation.name `` lowercase string ``"cpython" `` ``"cpython" `` unless configured otherwise.
306- ``sys.implementation.version `` string ``"major.minor" `` ``"3.14" `` The value used for ``sys.version `` unless configured otherwise.
307- ================================ ========================== ============== ===========================================================================
308-
309- The configuration options should allow users to specify the target values for these symbols, so that type checkers can evaluate the version and platform checks correctly.
310- The exact mechanism and name for these configuration options is implementation-specific, and defined by each type checker.
332+ Type checkers must be able to retrieve the information from the Python
333+ implementation's runtime environment, or provide configuration or CLI options
334+ to specify target ``sys.version ``, ``sys.platform ``,
335+ ``sys.implementation.name `` and ``sys.implementation.version ``.
336+
337+ ============================== ======================== ============= =====================================
338+ Symbol Suggested Format Example Suggested Default
339+ ============================== ======================== ============= =====================================
340+ ``sys.version_info `` string ``"major.minor" `` ``"3.11" `` The version of the Python interpreter
341+ used to run the type checker.
342+ ``sys.platform `` lowercase string ``"linux" `` The platform of the Python interpreter
343+ used to run the type checker.
344+ ``sys.implementation.name `` lowercase string ``"cpython" `` ``"cpython" `` unless configured
345+ otherwise.
346+ ``sys.implementation.version `` string ``"major.minor" `` ``"3.14" `` On CPython, default to the value used
347+ for ``sys.version ``. On other
348+ implementations, the value must be
349+ provided according to the type
350+ checker's configuration options.
351+ ============================== ======================== ============= =====================================
352+
353+ The configuration options should allow users to specify the target values for these
354+ symbols, so that type checkers can evaluate the version and platform checks
355+ correctly. The exact mechanism and names for these configuration options are
356+ implementation-specific and defined by each type checker.
311357
312358.. _`deprecated` :
313359
0 commit comments