classification
Title: Py_GenericAlias is not documented
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Guido.van.Rossum, Jelle Zijlstra, docs@python, gvanrossum, kj, miss-islington, petr.viktorin, ronaldoussoren
Priority: normal Keywords: patch

Created on 2021-06-11 09:18 by ronaldoussoren, last changed 2021-06-16 15:43 by kj. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 26724 merged kj, 2021-06-14 17:18
PR 26739 closed kj, 2021-06-15 14:26
PR 26756 merged miss-islington, 2021-06-16 14:12
PR 26757 merged kj, 2021-06-16 14:38
Messages (17)
msg395625 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2021-06-11 09:18
Py_GenericAlias seems to be a public API given its name and is mention in the stable ABI list for 3.10 (https://docs.python.org/3.10/c-api/stable.html?highlight=py_genericalias), but the API is not documented. 

Likewise for Py_GenericAliasType.
msg395630 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-06-11 10:30
Ronald, may I take this please? Or are you working on something already?
msg395790 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2021-06-14 11:24
I'm not working on this. Feel free to work on a PR.
msg395822 - (view) Author: Guido van Rossum (Guido.van.Rossum) Date: 2021-06-14 17:33
Hm, maybe it was a mistake to expose this? Remind me what use is made of this from C code? Can we remove this from the stable API during beta? It was never exposed before.
msg395826 - (view) Author: Jelle Zijlstra (Jelle Zijlstra) * (Python triager) Date: 2021-06-14 17:51
It could be useful for C extensions that want to support PEP 585 for their types, such as numpy's array type.
msg395827 - (view) Author: Guido van Rossum (Guido.van.Rossum) Date: 2021-06-14 17:58
Hm, but is that what they are doing? I assume that they use stub files, since static type checkers don’t introspect the runtime API.
msg395829 - (view) Author: Jelle Zijlstra (Jelle Zijlstra) * (Python triager) Date: 2021-06-14 18:00
They'd still need runtime support from GenericAlias to allow users to write `numpy.ndarray[int]` at runtime.
msg395831 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-06-14 18:04
> maybe it was a mistake to expose this

I was wondering if this was accidentally added at the time too.

> Remind me what use is made of this from C code

It's required for a C extension type to implement the __class_getitem__ method properly. Eg. ``MyCType[int]``. The other alternative is for them to import the types.GenericAlias Python constructor and call that, but that seems strange.

> Can we remove this from the stable API during beta? It was never exposed before.

Unfortunately, it seems like it has been (accidentally?) exposed since 3.9 :(. I see some 3rd party projects using it already, so I don't know if we can get rid of it so easily:
https://github.com/Nuitka/Nuitka/blob/57fecfe6cc939f4694b57d2efa37d1893c06b85b/nuitka/build/include/nuitka/helper/subscripts.h#L97

CC-ing Petr, seeking advice on the C stable ABI for this please.
msg395832 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2021-06-14 18:06
Maybe the docs then should contain a more-or-less complete example showing how a 3rd party type should use this?
msg395833 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-06-14 18:15
(Copied over from the PR)

BTW, I also noticed the stable ABI manifest exposes the wrong return type for Py_GenericAliasType. It exposes it as a function when it's a var/type/struct. So I fixed that in the PR too otherwise the docs weren't compiling (I can split that into a separate PR if needed). But that means the exported symbol for Windows is also modified.
msg395839 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2021-06-14 19:26
> Can we remove this from the stable API during beta?

It was added (to PC/python3.def) in 3.9, so removing in 3.10 beta wouldn't be good.
It can be deprecated; should it?
msg395863 - (view) Author: Ronald Oussoren (ronaldoussoren) * (Python committer) Date: 2021-06-15 06:28
Why should this be deprecated at all? 

The API is a convenient way to add ``__class_getitem__`` in a way that is consistent with the implementation for builtin types and the stdlib.

I noticed the lack of documentation when I worked on implementing this for PyObjC (an easy first step towards adding type stubs to that project). 

For me the alternative to using Py_GenericAlias would be a dummy implementation of ``__class_getitem__`` that just returns self.
msg395922 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2021-06-16 14:12
New changeset 6773c3eaa735b5061b4a97f2c730703a32d8c9ff by Ken Jin in branch 'main':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
https://github.com/python/cpython/commit/6773c3eaa735b5061b4a97f2c730703a32d8c9ff
msg395923 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2021-06-16 14:15
Does it need a backport to 3.9 too, since GenericAlias was introduced there?
msg395927 - (view) Author: miss-islington (miss-islington) Date: 2021-06-16 14:34
New changeset 84ce737f73136c1de7c4dc92bc096ed6c963e42d by Miss Islington (bot) in branch '3.10':
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
https://github.com/python/cpython/commit/84ce737f73136c1de7c4dc92bc096ed6c963e42d
msg395936 - (view) Author: miss-islington (miss-islington) Date: 2021-06-16 15:35
New changeset c7e95715ec2f2a16eace7aa35a1eb2f18e8d06ed by Ken Jin in branch '3.9':
[3.9] bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) (GH-26757)
https://github.com/python/cpython/commit/c7e95715ec2f2a16eace7aa35a1eb2f18e8d06ed
msg395940 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-06-16 15:43
I'm closing this issue as all the relevant PRs have landed. Thanks everyone!

@Ronald
> Why should this be deprecated at all?

I can't speak for others, but personally I think it's here to stay (for the many reasons raised in the previous messages).

Thanks for catching and reporting this. Improving docs is always fun :).
History
Date User Action Args
2021-06-16 15:43:52kjsetstatus: open -> closed
resolution: fixed
messages: + msg395940

stage: patch review -> resolved
2021-06-16 15:35:00miss-islingtonsetmessages: + msg395936
2021-06-16 14:38:28kjsetpull_requests: + pull_request25342
2021-06-16 14:34:53miss-islingtonsetmessages: + msg395927
2021-06-16 14:15:10gvanrossumsetmessages: + msg395923
2021-06-16 14:12:39miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request25341
2021-06-16 14:12:33gvanrossumsetmessages: + msg395922
2021-06-15 14:26:19kjsetpull_requests: + pull_request25325
2021-06-15 06:28:14ronaldoussorensetmessages: + msg395863
2021-06-14 19:26:38petr.viktorinsetmessages: + msg395839
2021-06-14 18:15:42kjsetmessages: + msg395833
2021-06-14 18:06:06gvanrossumsetmessages: + msg395832
2021-06-14 18:04:19kjsetnosy: + petr.viktorin
messages: + msg395831
2021-06-14 18:00:09Jelle Zijlstrasetmessages: + msg395829
2021-06-14 17:58:37Guido.van.Rossumsetmessages: + msg395827
2021-06-14 17:51:57Jelle Zijlstrasetnosy: + Jelle Zijlstra
messages: + msg395826
2021-06-14 17:33:33Guido.van.Rossumsetnosy: + Guido.van.Rossum
messages: + msg395822
2021-06-14 17:18:15kjsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25314
2021-06-14 11:24:59ronaldoussorensetmessages: + msg395790
2021-06-11 10:30:05kjsetnosy: + gvanrossum, kj
messages: + msg395630
2021-06-11 09:18:35ronaldoussorencreate