Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

Closed
wants to merge 3 commits into from

Conversation

AlexWaygood
Copy link
Member

@AlexWaygood AlexWaygood commented May 21, 2023

help(typing_extensions.TypeVar) gives quite poor results at the moment.

N.B. I haven't included a test for TypeVar.__doc__, as it feels like the test I'd add would fit most naturally into the TestCase subclass @JelleZijlstra is adding in #165.

^Tests added for all three classes.

Copy link
Member

@JelleZijlstra JelleZijlstra left a 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.

@AlexWaygood
Copy link
Member Author

Hmm, and that makes me realise that typing.TypeVar.__doc__ is pretty out of date on the CPython main branch:

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

@JelleZijlstra
Copy link
Member

I suppose I can improve it in my PEP 695 docs PR.

@JelleZijlstra
Copy link
Member

Do you want to carry over the docstring I pushed to python/cpython#104642?

@AlexWaygood
Copy link
Member Author

AlexWaygood commented May 22, 2023

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

@AlexWaygood AlexWaygood deleted the improve-docstrings branch May 22, 2023 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants