Skip to content

Commit c0639dd

Browse files
committed
spec/directives: Process additional review comments.
Also : - wrapped lines to ~85 characters - tables to 110 characters - Improved .rst formatting and markup The Intent is for these commits allow tracability of review comments, but to be squashed to a single commit during merge. Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>
1 parent 4ca8fd6 commit c0639dd

1 file changed

Lines changed: 128 additions & 82 deletions

File tree

‎docs/spec/directives.rst‎

Lines changed: 128 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -154,88 +154,111 @@ left undefined by the typing spec at this time.
154154
Version 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

163165
Type 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

172178
sys.version_info checks
173179
^^^^^^^^^^^^^^^^^^^^^^^^
174180

175181
Type 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

198208
Type 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

227244
Type 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

255287
Type 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

Comments
 (0)