Repository navigation
Improve documentation for typing.TypeVar #90925
Description
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 2022-03-23.18:22:59.879>
created_at = <Date 2022-02-16.17:01:18.275>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = 'Improve documentation for `typing.TypeVar`'
updated_at = <Date 2022-04-06.18:03:19.762>
user = 'https://github.com/AlexWaygood'bugs.python.org fields:
activity = <Date 2022-04-06.18:03:19.762>
actor = 'kj'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-03-23.18:22:59.879>
closer = 'JelleZijlstra'
components = ['Documentation']
creation = <Date 2022-02-16.17:01:18.275>
creator = 'AlexWaygood'
dependencies = []
files = []
hgrepos = []
issue_num = 46769
keywords = ['patch']
message_count = 9.0
messages = ['413342', '413362', '415349', '415852', '415890', '415892', '415893', '416894', '416895']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'docs@python', 'lukasz.langa', 'JelleZijlstra', 'sobolevn', 'kj', 'AlexWaygood']
pr_nums = ['31712', '31941', '32067', '32374', '32375']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46769'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
AlexWaygood commentedon Feb 16, 2022
There are three variants of
TypeVars:(1) TypeVars that are neither constrained nor bound:
T = TypeVar("T")(2) TypeVars that are bound:
U = TypeVar("U", bound=str)(3) TypeVars that are constrained:
V = TypeVar("V", str, bytes)The third variant is important for annotating certain functions, such as those in the
remodule. However, it has a number of issues (see python/typing#1080 for further discussion):(1) It has somewhat surprising semantics in many situations.
(2) It is difficult for type checkers to deal with, leading to a number of bugs in mypy, for example.
(3) Many users (especially people relatively inexperienced with Python typing) reach for constrained TypeVars in situations where using bound TypeVars or the @overload decorator would be more appropriate.
Both PEP-484 and the documentation for the typing module, however:
(1) Give examples for variants (1) and (3), but not for variant (2), which is treated as something of an afterthought.
(2) Do not mention that TypeVars can be bound to a union of types, which is an important point:
T = TypeVar("T", str, bytes)has different semantics toT = TypeVar("T", bound=str|bytes), and often the latter is more appropriate.gvanrossum commentedon Feb 16, 2022
Maybe historically constrained type vars predated bound type vars. This could have influenced the way PEP-484 was written and then the docs were derived from the PEP.
But yes, this should be fixed in as many places as possible (including the mypy docs, probably).
I would even support a minor update to PEP-484 to help people find the right way (the PEP is still widely cited). It would have to be just be a textual change, not a spec change.
JelleZijlstra commentedon Mar 16, 2022
New changeset 81b425d by Alex Waygood in branch 'main':
bpo-46769: Improve documentation for
typing.TypeVar(GH-31712)81b425d
JelleZijlstra commentedon Mar 23, 2022
New changeset d5ed8a8 by Alex Waygood in branch '3.10':
[3.10] bpo-46769: Improve documentation for
typing.TypeVar(GH-31712) (GH-31941)d5ed8a8
ambv commentedon Mar 23, 2022
New changeset 0bbb695 by Jelle Zijlstra in branch '3.9':
[3.9] bpo-46769: Improve documentation for
typing.TypeVar(GH-31712) (GH-31941) (GH-32067)0bbb695
JelleZijlstra commentedon Mar 23, 2022
Thanks Alex for the PR and Łukasz for merging the last backport!
AlexWaygood commentedon Mar 23, 2022
Thanks Guido for your insight, and Jelle/Łukasz for the reviews and backports!
I'm on holiday right now, but when I'm back, I'll take a look at maybe proposing some minor revisions to PEP-484 as well, as Guido suggests.
Fidget-Spinner commentedon Apr 6, 2022
New changeset 80af26d by Ken Jin in branch '3.10':
[3.10] bpo-46769: Fix backticks in typing.rst to appease rstlint (GH-32374)
80af26d
Fidget-Spinner commentedon Apr 6, 2022
New changeset d6a7ee6 by Ken Jin in branch '3.9':
[3.9] bpo-46769: Fix backticks in typing.rst to appease rstlint (GH-32375)
d6a7ee6