bpo-46589: Improve documentation for typing._GenericAlias #31026
Conversation
|
This is awesome! This will definitely benefit new contributors. I can personally attest to taking the same path you took (and being confused at exactly the same parts). I'll send a full review at a later date. PS. Please create an issue. It's easier for us to track this that way in case anything crops up after. |
Lib/typing.py
Outdated
| @@ -999,16 +999,42 @@ def __dir__(self): | |||
|
|
|||
|
|
|||
| class _GenericAlias(_BaseGenericAlias, _root=True): | |||
| def __init__(self, origin, params, *, inst=True, name=None, | |||
| """The type of parameterized generics. | |||
There was a problem hiding this comment.
I wonder if this should be a docstring or a comment -- it's not a public class.
There was a problem hiding this comment.
Oh, interesting, I wasn't aware of that convention. I've gone ahead and changed these docstrings to comments.
There was a problem hiding this comment.
I am super sorry for making you do that! It seems the rest of this module uses docstrings for all internal types.
As penance I will fix it back before landing.
While implementing PEP 646, I was getting really confused about what was happening in
typing._GenericAlias, so I've tried to improve it with the following changes:__init__and__getitem__.paramstoargs. (My understanding is that in the context of generic types, the term 'arguments' should be used to refer to the list of things passed through the square brackets - e.g. intuple[int, T],(int, T)are the arguments.)_determine_new_args.Callable.subst→new_arg_by_paramarg→old_argornew_argdepending on the context(I'm hoping this is just about trivial enough to be alright without an issue on bugs.python.org. If not, I'm happy to create one.)Done!https://bugs.python.org/issue46589