The documentation of typing.TYPE_CHECKING has an example (introduced in issue #26141) that would lead to NameError at runtime. The example shows how to limit the import of "expensive_mod" to type checkers, but then goes on to use "expensive_mod.some_type" in a type annotation that is evaluated at runtime ("local_var: expensive_mod.some_type"). The use case of TYPE_CHECKING is probably meant for type annotations placed in comments, e.g. "local_var  # type: expensive_mod.some_type".

The example is actually correct; I just confirmed by running it in my shell. Type annotations on local variables are not evaluated at runtime; see PEP 526.

I have updated the patch after feedback from Jelle Zijlstra and Ivan Levkevskyi. Indeed the example was correct; the patch now adds wording from PEP 484 and PEP 526 to clarify why a function parameter annotation needs to be in quotes and a local variable annotation does not.

New changeset 87c07fe9d908d0a2143fcc8369255c6ff3241503 by Berker Peksag (Mathias Rav) in branch 'master':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
https://github.com/python/cpython/commit/87c07fe9d908d0a2143fcc8369255c6ff3241503

87c07fe9d908d0a2143fcc8369255c6ff3241503 should still be backported to 3.5 and 3.6 branches so please don't close it yet.

> 87c07fe9d908d0a2143fcc8369255c6ff3241503 should still be backported to 3.5 and 3.6 branches so please don't close it yet.

Thanks for making backport PRs! (and sorry for closing prematurely)

New changeset 271a289a03ad10c91c5326bde3020f1cdf6a1fff by Berker Peksag in branch '3.5':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
https://github.com/python/cpython/commit/271a289a03ad10c91c5326bde3020f1cdf6a1fff

New changeset 04f389b8b357c8507b6c9642adcb8b956489e034 by Berker Peksag in branch '3.6':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
https://github.com/python/cpython/commit/04f389b8b357c8507b6c9642adcb8b956489e034

Now all backport PRs have been merged. Thanks for the PR, Mathias.

> Thanks for making backport PRs! (and sorry for closing prematurely)

No problem, thanks for the reviews! By the way, sorry I missed the typo in your last name while doing the initial merge.

Sorry for making a typo in your last name, Ivan Levkivskyi! I should know better and use copy-and-paste.

> Sorry for making a typo in your last name

No problem!
This actually happened maaany times with me :-)