This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Improve documentation for `typing.TypeVar`
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: AlexWaygood, JelleZijlstra, docs@python, gvanrossum, kj, lukasz.langa, sobolevn
Priority: normal Keywords: patch

Created on 2022-02-16 17:01 by AlexWaygood, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 31712 merged AlexWaygood, 2022-03-06 22:39
PR 31941 merged AlexWaygood, 2022-03-16 18:43
PR 32067 merged JelleZijlstra, 2022-03-23 02:54
PR 32374 merged kj, 2022-04-06 17:21
PR 32375 merged kj, 2022-04-06 17:24
Messages (9)
msg413342 - (view) Author: Alex Waygood (AlexWaygood) * (Python triager) Date: 2022-02-16 17:01
There are three variants of `TypeVar`s:

(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 `re` module. However, it has a number of issues (see https://github.com/python/typing/discussions/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 to `T = TypeVar("T", bound=str|bytes)`, and often the latter is more appropriate.
msg413362 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2022-02-16 21:53
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.
msg415349 - (view) Author: Jelle Zijlstra (JelleZijlstra) * (Python committer) Date: 2022-03-16 15:56
New changeset 81b425d4dc43b60dd11a3e9abc5c84a4b8b384db by Alex Waygood in branch 'main':
bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712)
https://github.com/python/cpython/commit/81b425d4dc43b60dd11a3e9abc5c84a4b8b384db
msg415852 - (view) Author: Jelle Zijlstra (JelleZijlstra) * (Python committer) Date: 2022-03-23 02:52
New changeset d5ed8a8258eaf7a241978b1b0aeb971108d0f7e0 by Alex Waygood in branch '3.10':
[3.10] bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) (GH-31941)
https://github.com/python/cpython/commit/d5ed8a8258eaf7a241978b1b0aeb971108d0f7e0
msg415890 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2022-03-23 18:19
New changeset 0bbb6956f83ef457872b8f04242bb02b6898350d by Jelle Zijlstra in branch '3.9':
[3.9] bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) (GH-31941) (GH-32067)
https://github.com/python/cpython/commit/0bbb6956f83ef457872b8f04242bb02b6898350d
msg415892 - (view) Author: Jelle Zijlstra (JelleZijlstra) * (Python committer) Date: 2022-03-23 18:22
Thanks Alex for the PR and Łukasz for merging the last backport!
msg415893 - (view) Author: Alex Waygood (AlexWaygood) * (Python triager) Date: 2022-03-23 18:59
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.
msg416894 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2022-04-06 18:00
New changeset 80af26d25af5568229d31ecb2a8f1bf9702b7791 by Ken Jin in branch '3.10':
[3.10] bpo-46769: Fix backticks in typing.rst to appease rstlint (GH-32374)
https://github.com/python/cpython/commit/80af26d25af5568229d31ecb2a8f1bf9702b7791
msg416895 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2022-04-06 18:03
New changeset d6a7ee69fb3263450ba47bed9104f4a68a08a9bd by Ken Jin in branch '3.9':
[3.9] bpo-46769: Fix backticks in typing.rst to appease rstlint (GH-32375)
https://github.com/python/cpython/commit/d6a7ee69fb3263450ba47bed9104f4a68a08a9bd
History
Date User Action Args
2022-04-11 14:59:56adminsetgithub: 90925
2022-04-06 18:03:19kjsetmessages: + msg416895
2022-04-06 18:00:35kjsetmessages: + msg416894
2022-04-06 17:24:21kjsetpull_requests: + pull_request30418
2022-04-06 17:21:16kjsetpull_requests: + pull_request30417
2022-03-23 18:59:17AlexWaygoodsetmessages: + msg415893
2022-03-23 18:22:59JelleZijlstrasetstatus: open -> closed
resolution: fixed
messages: + msg415892

stage: patch review -> resolved
2022-03-23 18:19:46lukasz.langasetnosy: + lukasz.langa
messages: + msg415890
2022-03-23 02:54:58JelleZijlstrasetpull_requests: + pull_request30156
2022-03-23 02:52:43JelleZijlstrasetmessages: + msg415852
2022-03-16 18:43:01AlexWaygoodsetpull_requests: + pull_request30031
2022-03-16 15:56:36JelleZijlstrasetmessages: + msg415349
2022-03-06 22:39:47AlexWaygoodsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request29830
2022-02-16 21:53:18gvanrossumsetmessages: + msg413362
2022-02-16 17:01:18AlexWaygoodcreate