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> _______________________________________