Skip to content

Commit d2c4133

Browse files
JosverlCopilot
andcommitted
Address review comments and suggestions.
Minor changes to wording and formatting. Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent c0639dd commit d2c4133

1 file changed

Lines changed: 54 additions & 36 deletions

File tree

‎docs/spec/directives.rst‎

Lines changed: 54 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ Type checkers should support combining these checks with:
167167
* A ``not`` unary operator
168168
* An ``and`` or ``or`` binary operator
169169

170-
Type checkers are only required to support the fully-qualified form
170+
Type checkers are only required to support the fully qualified form
171171
(e.g., ``sys.platform``). Support for aliases or import variants
172172
(e.g., ``from sys import platform``) is not required, though type checkers may
173173
choose to support them.
@@ -185,10 +185,10 @@ Type checkers should support the following comparison patterns:
185185

186186
where ``<2-tuple>`` is a literal tuple of two literal integers.
187187

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``.
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``.
192192

193193
.. code-block:: python
194194
:caption: Examples of ``sys.version_info`` checks
@@ -210,18 +210,18 @@ Type checkers should support the following comparison patterns:
210210
* ``sys.platform == <string literal>``
211211
* ``sys.platform != <string literal>``
212212
* ``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>``
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>``
219219

220220
Common values: ``"linux"``, ``"darwin"``, ``"win32"``, ``"emscripten"``,
221221
``"wasi"``
222222

223223
The membership checks ``in`` and ``not in`` only support simple containment
224-
testing with a tuple, set, or list of literal strings.
224+
testing with a literal tuple, literal set, or literal list of literal strings.
225225

226226
.. code-block:: python
227227
:caption: Examples of ``sys.platform`` checks
@@ -241,21 +241,22 @@ testing with a tuple, set, or list of literal strings.
241241
sys.implementation.name checks
242242
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
243243

244-
Type checkers should support comparison patterns:
244+
Type checkers should support these comparison patterns with
245+
``sys.implementation.name``:
245246

246247
* ``sys.implementation.name == <string literal>``
247248
* ``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>``
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>``
254255

255256
Default value: ``"cpython"``, unless configured otherwise.
256257

257258
Common values: ``"cpython"``, ``"pypy"``, ``"micropython"``, ``"graalpy"``,
258-
``"jython"``, ``"ironpython"``
259+
``"android"``, ``"ios"``, ``"ironpython"``
259260

260261
.. code-block:: python
261262
:caption: Examples of ``sys.implementation.name`` checks
@@ -271,7 +272,7 @@ Common values: ``"cpython"``, ``"pypy"``, ``"micropython"``, ``"graalpy"``,
271272
sys.implementation.version checks
272273
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
273274

274-
The value of ``sys.implementation.version`` is a tuple, in the same format as
275+
The value of ``sys.implementation.version`` is a tuple, in a similar format as
275276
``sys.version_info``. However, it represents the version of the
276277
*Python implementation* rather than the version of the *Python language*. This has
277278
a distinct meaning from the specific version of the Python language to which the
@@ -280,18 +281,18 @@ currently running interpreter conforms.
280281
For CPython (``sys.implementation.name == "cpython"``) this is the same as
281282
``sys.version_info``.
282283
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.
284+
be specified in the type checker configuration or discovered at runtime.
286285

287286
Type checkers should support the following comparison patterns:
288287

289288
* ``sys.implementation.version >= <2-tuple>``
290289
* ``sys.implementation.version < <2-tuple>``
291290

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``.
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``.
295296

296297
.. code-block:: python
297298
:caption: Examples of ``sys.implementation.version`` checks
@@ -304,11 +305,29 @@ against named attributes of ``sys.implementation.version``.
304305
# MicroPython version 1.24 and above
305306
306307
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+
307326
Required forms and optional extensions
308327
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309328

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,
329+
Type checkers must support the forms specified above as required. Support for additional
330+
comparison patterns and syntax forms is optional. For example,
312331
type checkers are not required to support the following forms:
313332

314333
.. code-block:: python
@@ -325,13 +344,12 @@ type checkers are not required to support the following forms:
325344
if "win" not in sys.platform:
326345
# Substring membership test against sys.platform
327346
328-
329347
Configuration
330348
^^^^^^^^^^^^^
331349

332-
Type checkers must be able to retrieve the information from the Python
350+
Type checkers should be able to retrieve the information from the Python
333351
implementation's runtime environment, or provide configuration or CLI options
334-
to specify target ``sys.version``, ``sys.platform``,
352+
to specify target ``sys.version_info``, ``sys.platform``,
335353
``sys.implementation.name`` and ``sys.implementation.version``.
336354

337355
============================== ======================== ============= =====================================
@@ -344,10 +362,10 @@ Symbol Suggested Format Example Suggested
344362
``sys.implementation.name`` lowercase string ``"cpython"`` ``"cpython"`` unless configured
345363
otherwise.
346364
``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.
365+
for ``sys.version_info``. On other
366+
implementations, the value should be
367+
provided in configuration or
368+
otherwise inferred.
351369
============================== ======================== ============= =====================================
352370

353371
The configuration options should allow users to specify the target values for these

0 commit comments

Comments
 (0)