-
-
Notifications
You must be signed in to change notification settings - Fork 117
Improve some docstrings #167
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should actually have our own docstrings, since we add the default=
argument to all of these, and it should be covered in the docstring.
Hmm, and that makes me realise that >>> import typing
>>> print(typing.TypeVar.__doc__)
Type variable.
Usage::
T = TypeVar('T') # Can be anything
A = TypeVar('A', str, bytes) # Must be str or bytes
Type variables exist primarily for the benefit of static type
checkers. They serve as the parameters for generic types as well
as for generic function definitions. See class Generic for more
information on generic types. Generic functions work as follows:
def repeat(x: T, n: int) -> List[T]:
'''Return a list containing n references to x.'''
return [x]*n
def longest(x: A, y: A) -> A:
'''Return the longest of two strings.'''
return x if len(x) >= len(y) else y
The latter example's signature is essentially the overloading
of (str, str) -> str and (bytes, bytes) -> bytes. Also note
that if the arguments are instances of some subclass of str,
the return type is still plain str.
At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
Type variables defined with covariant=True or contravariant=True
can be used to declare covariant or contravariant generic types.
See PEP 484 for more details. By default generic types are invariant
in all type variables.
Type variables can be introspected. e.g.:
T.__name__ == 'T'
T.__constraints__ == ()
T.__covariant__ == False
T.__contravariant__ = False
A.__constraints__ == (str, bytes)
Note that only type variables defined in global scope can be pickled. |
I suppose I can improve it in my PEP 695 docs PR. |
Do you want to carry over the docstring I pushed to python/cpython#104642? |
This has merge conflicts, and I'll need to basically start from scratch anyway once we've finished haggling over the wording of the docstring over at python/cpython#104642 :) So, closing for now |
help(typing_extensions.TypeVar)
gives quite poor results at the moment.N.B. I haven't included a test forTypeVar.__doc__
, as it feels like the test I'd add would fit most naturally into theTestCase
subclass @JelleZijlstra is adding in #165.^Tests added for all three classes.