bpo-46769: Improve documentation for typing.TypeVar
#31712
Conversation
AlexWaygood
requested review from
gvanrossum,
Fidget-Spinner and
JelleZijlstra
as code owners
Doc/library/typing.rst
Outdated
| def print_capitalized(x: S) -> S: | ||
| """Print x capitalized, and return x""" | ||
| print(x.capitalize()) | ||
| return x |
There was a problem hiding this comment.
I'm not wildly keen on this new example, but I was struggling to think of a better one that was (1) extremely simple and (2) showed the need for a bound TypeVar rather than a constrained TypeVar.
Doc/library/typing.rst
Outdated
| def concatenate(x: A, y: A) -> A: | ||
| """Add two strings together.""" | ||
| return x + y |
There was a problem hiding this comment.
I altered this example, as the longest example that is currently in the docs does not need a constrained TypeVar, and I'd like to use this section to illustrate the pros and cons of the two kinds of TypeVar.
| @@ -245,7 +245,7 @@ subscription to denote expected types for container elements. | |||
| def notify_by_email(employees: Sequence[Employee], | |||
| overrides: Mapping[str, str]) -> None: ... | |||
|
|
|||
| Generics can be parameterized by using a new factory available in typing | |||
There was a problem hiding this comment.
TypeVar isn't really very new anymore
| can only ever be solved as being exactly one of the constraints given:: | ||
|
|
||
| a = concatenate('one', 'two') | ||
| reveal_type(a) # revealed type is str |
There was a problem hiding this comment.
Using reveal_type() here is nice, but may make it tricky to backport this docs patch, because the 3.10 and 3.9 docs say nothing about reveal_type(). Then again, we've been using reveal_type() in PEPs for years too.
There was a problem hiding this comment.
Oh, do the typing docs not use reveal_type at all at the moment? I might have got the typing docs and PEP 484 confused in my head slightly.
There was a problem hiding this comment.
No (on 3.10), and neither does PEP 484. However, several later typing PEPs used (but did not define) reveal_type.
There was a problem hiding this comment.
I'll reword this bit then, thanks for the catch!
There was a problem hiding this comment.
I think it's good to use reveal_type() in the long term though. Maybe leave it as is, and we can reword in the 3.10/3.9 backport PRs later?
Co-authored-by: Jelle Zijlstra <[email protected]>
AlexWaygood
added
needs backport to 3.9
There was a problem hiding this comment.
Thanks! @gvanrossum planning to merge this docs change, though further feedback would be welcome too.
|
I need to make a few edits to the backports for this, so maybe I should just do them manually |
AlexWaygood
removed
needs backport to 3.9
|
Sure, thanks! |
…H-31712) Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit 81b425d) Co-authored-by: Alex Waygood <[email protected]>
… (GH-31941) * [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit 81b425d) * Remove references to `reveal_type`, add new section on `self` types
…ythonGH-31712) (pythonGH-31941) * [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (pythonGH-31712) Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit 81b425d) * Remove references to `reveal_type`, add new section on `self` types. (cherry picked from commit d5ed8a8) Co-authored-by: Alex Waygood <[email protected]>
GH-31941) (GH-32067) * [3.9] [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) (GH-31941) * [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (GH-31712) Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit 81b425d) * Remove references to `reveal_type`, add new section on `self` types. (cherry picked from commit d5ed8a8) Co-authored-by: Alex Waygood <[email protected]> * remove unused susp allowlist Co-authored-by: Alex Waygood <[email protected]>
…-31712) (pythonGH-31941) (pythonGH-32067) * [3.9] [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (pythonGH-31712) (pythonGH-31941) * [3.10] bpo-46769: Improve documentation for `typing.TypeVar` (pythonGH-31712) Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit 81b425d) * Remove references to `reveal_type`, add new section on `self` types. (cherry picked from commit d5ed8a8) Co-authored-by: Alex Waygood <[email protected]> * remove unused susp allowlist Co-authored-by: Alex Waygood <[email protected]>
This PR reworks the typing documentation to give more prominence to bound
TypeVars as opposed to constrainedTypeVars.As outlined in bpo-46769, constrained
TypeVars suffer from a number of issues which mean that boundTypeVars are often a more appropriate choice. However, the typing docs currently contain a number of examples of constrainedTypeVars, but no examples of boundTypeVars, which are barely mentioned.https://bugs.python.org/issue46769