From 7036a84fd2293b4fdc40d7e1a11eaa71a444c31b Mon Sep 17 00:00:00 2001 From: Jon Shea <1385+jonshea@users.noreply.github.com> Date: Mon, 10 Apr 2023 15:39:23 -0400 Subject: [PATCH 1/2] Clarify "Using types...but not at runtime" docs The section "Using classes that are generic in stubs but not at runtime" on the runtime_troubles.html page is very helpful, but naive readers who follow its instructions will almost inevitably create a runtime `NameError`. This PR updates the example to include an `annotations` import that will avert such a `NameError`. --- docs/source/runtime_troubles.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/source/runtime_troubles.rst b/docs/source/runtime_troubles.rst index 0847a5796512..4d6b0815c6fe 100644 --- a/docs/source/runtime_troubles.rst +++ b/docs/source/runtime_troubles.rst @@ -277,10 +277,20 @@ sections, these can be dealt with by using :ref:`typing.TYPE_CHECKING .. code-block:: python + from __future__ import annotations from typing import TYPE_CHECKING if TYPE_CHECKING: from _typeshed import SupportsRichComparison + def f(x: SupportsRichComparison) -> None + +Note that the ``from __future__ import annotations`` is required to avoid +a ``NameError`` at the use site of the excluded import. In the example above, +``def f(x: SupportsRichComparison)`` would raise ``NameError`` if +``from __future__ import annotations`` is not included. For more information, +and additional caveats, see the section on +:ref:`future annotations `. + .. _generic-builtins: Using generic builtins From ddf8a3b8c54ffea2be472d154c1db1513b58d02f Mon Sep 17 00:00:00 2001 From: Jon Shea <1385+jonshea@users.noreply.github.com> Date: Mon, 10 Apr 2023 22:45:14 -0400 Subject: [PATCH 2/2] Update with suggested rewording. --- docs/source/runtime_troubles.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/source/runtime_troubles.rst b/docs/source/runtime_troubles.rst index 4d6b0815c6fe..909215a774a9 100644 --- a/docs/source/runtime_troubles.rst +++ b/docs/source/runtime_troubles.rst @@ -284,11 +284,9 @@ sections, these can be dealt with by using :ref:`typing.TYPE_CHECKING def f(x: SupportsRichComparison) -> None -Note that the ``from __future__ import annotations`` is required to avoid -a ``NameError`` at the use site of the excluded import. In the example above, -``def f(x: SupportsRichComparison)`` would raise ``NameError`` if -``from __future__ import annotations`` is not included. For more information, -and additional caveats, see the section on +The ``from __future__ import annotations`` is required to avoid +a ``NameError`` when using the imported symbol. +For more information and caveats, see the section on :ref:`future annotations `. .. _generic-builtins: