[issue46769] Improve documentation for `typing.TypeVar`
New submission from Alex Waygood <Alex.Waygood@Gmail.com>: 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. ---------- assignee: docs@python components: Documentation messages: 413342 nosy: AlexWaygood, Jelle Zijlstra, docs@python, gvanrossum, kj, sobolevn priority: normal severity: normal stage: needs patch status: open title: Improve documentation for `typing.TypeVar` type: behavior versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Guido van Rossum <guido@python.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Change by Alex Waygood <Alex.Waygood@Gmail.com>: ---------- keywords: +patch pull_requests: +29830 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/31712 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Jelle Zijlstra <jelle.zijlstra@gmail.com> added the comment: New changeset 81b425d4dc43b60dd11a3e9abc5c84a4b8b384db by Alex Waygood in branch 'main': bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) https://github.com/python/cpython/commit/81b425d4dc43b60dd11a3e9abc5c84a4b8b... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Change by Alex Waygood <Alex.Waygood@Gmail.com>: ---------- pull_requests: +30031 pull_request: https://github.com/python/cpython/pull/31941 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Jelle Zijlstra <jelle.zijlstra@gmail.com> added the comment: 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/d5ed8a8258eaf7a241978b1b0aeb971108d... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Change by Jelle Zijlstra <jelle.zijlstra@gmail.com>: ---------- pull_requests: +30156 pull_request: https://github.com/python/cpython/pull/32067 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Łukasz Langa <lukasz@langa.pl> added the comment: 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/0bbb6956f83ef457872b8f04242bb02b689... ---------- nosy: +lukasz.langa _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Jelle Zijlstra <jelle.zijlstra@gmail.com> added the comment: Thanks Alex for the PR and Łukasz for merging the last backport! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Alex Waygood <Alex.Waygood@Gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Change by Ken Jin <kenjin4096@gmail.com>: ---------- pull_requests: +30417 pull_request: https://github.com/python/cpython/pull/32374 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Change by Ken Jin <kenjin4096@gmail.com>: ---------- pull_requests: +30418 pull_request: https://github.com/python/cpython/pull/32375 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Ken Jin <kenjin4096@gmail.com> added the comment: 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/80af26d25af5568229d31ecb2a8f1bf9702... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
Ken Jin <kenjin4096@gmail.com> added the comment: 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/d6a7ee69fb3263450ba47bed9104f4a68a0... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________
participants (5)
-
Alex Waygood -
Guido van Rossum
-
Jelle Zijlstra
-
Ken Jin
-
Łukasz Langa