From e74d9604a5d01c81b9ee3b8392ab4f2efc75c496 Mon Sep 17 00:00:00 2001 From: Rebecca Chen Date: Fri, 9 Aug 2024 01:29:42 -0700 Subject: [PATCH] writing_stubs: add examples of allowed and disallowed language features (#1837) --- docs/guides/writing_stubs.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/guides/writing_stubs.rst b/docs/guides/writing_stubs.rst index 1d1af917..703d9749 100644 --- a/docs/guides/writing_stubs.rst +++ b/docs/guides/writing_stubs.rst @@ -579,8 +579,14 @@ Language Features ----------------- Use the latest language features available, even for stubs targeting older -Python versions. Do not use quotes around forward references and do not use -``__future__`` imports. See :ref:`stub-file-syntax` for more information. +Python versions. For example, Python 3.7 added the ``async`` keyword (see +:pep:`492`). Stubs should use it to mark coroutines, even if the implementation +still uses the ``@coroutine`` decorator. On the other hand, the ``type`` soft +keyword from :pep:`695`, introduced in Python 3.12, should not be used in stubs +until Python 3.11 reaches end-of-life in October 2027. + +Do not use quotes around forward references and do not use ``__future__`` +imports. See :ref:`stub-file-syntax` for more information. Yes::