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.

Ronald, may I take this please? Or are you working on something already?

I'm not working on this. Feel free to work on a PR.

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.

It could be useful for C extensions that want to support PEP 585 for their types, such as numpy's array type.

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.

They'd still need runtime support from GenericAlias to allow users to write `numpy.ndarray[int]` at runtime.

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

Maybe the docs then should contain a more-or-less complete example showing how a 3rd party type should use this?

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

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

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.

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

Does it need a backport to 3.9 too, since GenericAlias was introduced there?

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

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

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