[issue46769] Improve documentation for `typing.TypeVar`

[Ken Jin]

Ken Jin  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/d6a7ee69fb3263450ba47bed9104f4a68a08a9bd


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Ken Jin]

Ken Jin  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/80af26d25af5568229d31ecb2a8f1bf9702b7791


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Ken Jin]

Change by Ken Jin :


--
pull_requests: +30418
pull_request: https://github.com/python/cpython/pull/32375

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Ken Jin]

Change by Ken Jin :


--
pull_requests: +30417
pull_request: https://github.com/python/cpython/pull/32374

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Alex Waygood]

Alex Waygood  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Jelle Zijlstra]

Jelle Zijlstra  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Łukasz Langa]

Łukasz Langa  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/0bbb6956f83ef457872b8f04242bb02b6898350d


--
nosy: +lukasz.langa

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Jelle Zijlstra]

Change by Jelle Zijlstra :


--
pull_requests: +30156
pull_request: https://github.com/python/cpython/pull/32067

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Jelle Zijlstra]

Jelle Zijlstra  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/d5ed8a8258eaf7a241978b1b0aeb971108d0f7e0


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Alex Waygood]

Change by Alex Waygood :


--
pull_requests: +30031
pull_request: https://github.com/python/cpython/pull/31941

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Jelle Zijlstra]

Jelle Zijlstra  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/81b425d4dc43b60dd11a3e9abc5c84a4b8b384db


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Alex Waygood]

Change by Alex Waygood :


--
keywords: +patch
pull_requests: +29830
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/31712

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Guido van Rossum]

Guido van Rossum  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46769] Improve documentation for `typing.TypeVar`

[Alex Waygood]

New submission from Alex Waygood :

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com