Change typing.TYPE_CHECKING doc example

[Mortal]

BPO	29974
Nosy	@berkerpeksag, @ilevkivskyi, @JelleZijlstra, @Mortal
PRs	bpo-29974: Change typing.TYPE_CHECKING doc example #982 [3.6] bpo-29974: Improve typing.TYPE_CHECKING example (GH-982) #1297 [3.5] bpo-29974: Improve typing.TYPE_CHECKING example (GH-982) #1299

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-04-26.14:28:41.505>
created_at = <Date 2017-04-03.17:32:43.641>
labels = ['type-bug', '3.7', 'docs']
title = 'Change typing.TYPE_CHECKING doc example'
updated_at = <Date 2017-04-26.15:21:38.194>
user = 'https://github.com/Mortal'

bugs.python.org fields:

activity = <Date 2017-04-26.15:21:38.194>
actor = 'levkivskyi'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-04-26.14:28:41.505>
closer = 'berker.peksag'
components = ['Documentation']
creation = <Date 2017-04-03.17:32:43.641>
creator = 'rav'
dependencies = []
files = []
hgrepos = []
issue_num = 29974
keywords = []
message_count = 11.0
messages = ['291085', '291101', '291121', '292332', '292334', '292351', '292352', '292353', '292354', '292361', '292362']
nosy_count = 5.0
nosy_names = ['docs@python', 'berker.peksag', 'levkivskyi', 'JelleZijlstra', 'rav']
pr_nums = ['982', '1297', '1299']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue29974'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[Mortal]

The documentation of typing.TYPE_CHECKING has an example (introduced in issue bpo-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".

[JelleZijlstra]

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.

[Mortal]

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.

[berkerpeksag]

New changeset 87c07fe by Berker Peksag (Mathias Rav) in branch 'master':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
87c07fe

[berkerpeksag]

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

[ilevkivskyi]

87c07fe 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)

[berkerpeksag]

New changeset 271a289 by Berker Peksag in branch '3.5':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
271a289

[berkerpeksag]

New changeset 04f389b by Berker Peksag in branch '3.6':
bpo-29974: Improve typing.TYPE_CHECKING example (GH-982)
04f389b

[berkerpeksag]

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.

[Mortal]

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

[ilevkivskyi]

Sorry for making a typo in your last name

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