New submission from Alex Waygood <alex.wayg...@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 <rep...@bugs.python.org>
<https://bugs.python.org/issue46769>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
